SDK móvil de Chat2Desk para iOS y Android

Lleva el chat de Chat2Desk a tu propia aplicación móvil. El SDK se encarga de la conexión en tiempo real, del historial, del envío de mensajes y archivos y del modo sin conexión, para que tus clientes escriban a tu equipo sin salir de tu app. Funciona sobre la API de chat en línea (livechat-v2) de Chat2Desk.

Dos celulares, uno con estilo iOS y otro con estilo Android, mostrando un chat y conectados a la nube mediante una pieza de rompecabezas y un enchufe que representan el SDK de Chat2Desk

En resumen

Un solo SDK para iOS (Swift) y Android (Kotlin), construido con Kotlin Multiplatform sobre un módulo compartido.
Instalación con Swift Package Manager (iOS 12 o posterior) y Maven Central (Android).
Mensajes de texto y archivos, historial, búsqueda, datos del cliente y modo sin conexión.
Se inicializa con cuatro valores de tu canal de Widget y chat en línea: WIDGET_TOKEN, BASE_HOST, WS_HOST y STORAGE_HOST.

Cómo funciona

Diagrama de la arquitectura del SDK de Chat2Desk: tu app para iOS o Android usa el SDK de su plataforma, ambos comparten un módulo común que se conecta por WebSocket al servidor de Chat2Desk y guarda los mensajes en el dispositivo

Conexión: los eventos del servidor llegan por un socket (WebSocket) abierto por el SDK. Tú solo llamas a start y stop y observas el estado de la conexión.
Autorización: el SDK recibe el token del canal y la dirección del servidor con el que debe comunicarse.
Sin conexión: los mensajes y la información de servicio se guardan en el almacenamiento interno del dispositivo, así que el chat sigue mostrando el historial aunque no haya red.
Arquitectura: un módulo compartido (lógica de negocio, conexión con el servidor, mensajes, eventos del socket y almacenamiento) más una capa propia para Android y otra para iOS (red y base de datos).

Antes de empezar

Necesitas un canal de Widget y chat en línea conectado en tu cuenta de Chat2Desk. En el panel, en la configuración de ese canal, aparece la sección SDK Configuraciones (pestañas Android y iOS) con los valores que usarás: WIDGET_TOKEN (authToken), BASE_HOST, WS_HOST y STORAGE_HOST. Trata el token como un dato de configuración de tu app; no lo publiques en repositorios abiertos.

Instalación en iOS

Requisitos: iOS 12.0 o posterior y Xcode 14 o posterior. Activa la capacidad Background Modes en Signing & Capabilities.

En Xcode elige File → Add Package Dependencies…
Escribe la URL https://github.com/chat2desk/chat2desk-sdk-spm.
Selecciona la regla Up to Next Major Version a partir de la 1.5.14.
Agrega el producto chat2desk_sdk a tu target e impórtalo con import chat2desk_sdk.

Si usas Package.swift:

.package(url: "https://github.com/chat2desk/chat2desk-sdk-spm.git", from: "1.5.14")

// En las dependencias de tu target:
.product(name: "chat2desk_sdk", package: "chat2desk-sdk-spm")

Instalación en Android

Agrega mavenCentral() a los repositorios del build.gradle raíz.
Agrega la dependencia con la versión actual, la 1.5.14 (consulta las versiones disponibles en Maven Central):

dependencies {
    implementation 'com.chat2desk:chat2desk_sdk:${Version}'
}

Activa Java 8 en el build.gradle del módulo:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

Si tu app admite dispositivos con API menor a 26, usa Android Gradle Plugin 4.0 o posterior y habilita core library desugaring.

Permisos en AndroidManifest.xml: INTERNET siempre; si vas a leer archivos multimedia del almacenamiento compartido, añade los que necesites entre READ_MEDIA_IMAGES, READ_MEDIA_VIDEO y READ_MEDIA_AUDIO.

Inicialización

iOS (Swift)

let settings = Settings.init(
    authToken: "WIDGET_TOKEN",
    baseHost: "BASE_HOST",
    wsHost: "WS_HOST",
    storageHost: "STORAGE_HOST"
)
let chat2desk = Chat2Desk.Companion().create(settings: settings)

Android (Kotlin)

val settings = Settings(
    authToken = WIDGET_TOKEN,
    baseHost = BASE_HOST,
    wsHost = WS_HOST,
    storageHost = STORAGE_HOST
)
val chat2desk: IChat2Desk = Chat2Desk.create(settings, context)

Antes de eliminar la instancia, llama a IChat2Desk.close para evitar fugas de memoria.

Conectar y desconectar

Usa IChat2Desk.start para conectarte y IChat2Desk.stop para desconectarte. El estado de la conexión se observa con watchConnectionStatus() en iOS y con connectionStatus (un Flow<ConnectionState>) en Android.

// iOS
class SomeClass: ObservableObject {
    @Published public var connectionStatus: ConnectionState? = nil
    let chat2desk: Chat2Desk
    var connectionStatusWatcher: Closeable?

    init(chat2desk: Chat2Desk) {
        self.chat2desk = chat2desk
        connectionStatusWatcher = chat2desk.watchConnectionStatus().watch { status in
            self.connectionStatus = status
        }
    }
    func start() { Task { try await chat2desk.start() } }
    func stop() { Task { try await chat2desk.stop() } }
    deinit { connectionStatusWatcher?.close() }
}

// Android
class SomeClass(private val chat2desk: IChat2Desk) {
    private val coroutineScope = CoroutineScope(Dispatchers.Main)

    init {
        coroutineScope.launch {
            chat2desk.connectionStatus.collect { println(it) }
        }
    }
    suspend fun start() { chat2desk.start() }
    suspend fun stop() { chat2desk.stop() }
}

Mensajes

Para trabajar con mensajes, el SDK debe estar conectado. Todos los mensajes entrantes y salientes se guardan en caché dentro de la librería y se pueden leer sin conexión.

Qué quieres hacer	iOS (Swift)	Android (Kotlin)
Observar la lista de mensajes	`chat2desk.watchMessages.watch { messages in … }`	`chat2desk.messages.collect { messages -> … }`
Cargar los últimos 100 mensajes	`chat2desk.fetchMessages()`	`chat2desk.fetchMessages()`
Cargar solo los nuevos (posteriores al último guardado)	`chat2desk.fetchNewMessages()`	`chat2desk.fetchNewMessages()`
Cargar mensajes anteriores (hasta 100 por vez)	`chat2desk.fetchMessage(loadMore: true)`	`chat2desk.fetchMessage(loadMore = true)`
Enviar texto	`chat2desk.sendMessage(msg: txt)`	`chat2desk.sendMessage(txt)`
Reenviar un mensaje fallido	`chat2desk.resendMessage(message: message)`	`chat2desk.resendMessage(message)`

Importante: el SDK descarga del servidor un máximo de 100 mensajes por solicitud.

Enviar un archivo adjunto

// iOS
let attachedFile = AttachedFile.Companion().fromURL(url: url, originalName: originalName, mimeType: mimeType, fileSize: fileSize)
chat2desk.sendMessage(msg: txt, attachedFile: attachedFile)

// Android
val attachedFile = AttachedFile.fromUri(context, uri, originalName, mimeType, fileSize)
chat2desk.sendMessage(txt, attachedFile)

Buscar mensajes

Hay dos formas de buscar; ambas consultan el texto del mensaje (Message.text) y devuelven la lista de mensajes encontrados.

Búsqueda de texto completo: chat2desk.fullTextSearch(query: String). Los términos se dividen en fragmentos (tokens): solo cuentan los caracteres ASCII y Latin-1 (idiomas occidentales); las palabras unidas por guion se separan en dos; no distingue mayúsculas ni acentos. Para excluir una palabra antepón - (por ejemplo, ficción -ciencia) y para buscar por prefijo termina la palabra en * (por ejemplo, fict*). No hay búsqueda por sufijo.
Búsqueda con operadores: chat2desk.searchByQuery(query, options), con SearchOptions(operator:, caseSensitivity:). Los operadores disponibles son:

Operador	Coincide cuando…
`beginswith`	el texto empieza con la consulta
`contains`	el texto contiene la consulta (valor predeterminado)
`endswith`	el texto termina con la consulta
`like`	el texto coincide con un comodín: `*` equivale a cero o más caracteres y `?` a un carácter (por ejemplo, `d?g` coincide con «dog», «dig» y «dug»)
`equal`	el texto es igual a la consulta
`notequal`	el texto es distinto de la consulta

La sensibilidad a mayúsculas (caseSensitivity, desactivada por defecto) solo aplica a caracteres ASCII y Latin-1. En Android los operadores se escriben en mayúsculas (CONTAINS, BEGINSWITH, etc.).

Datos del cliente y campos personalizados

Puedes enviar el nombre y el teléfono del cliente con chat2desk.sendClientParams(name, phone). Además, el servicio entrega la lista de campos personalizados definidos en tu empresa (customFields) para que envíes sus valores:

// Android
chat2desk.customFields.collect { fields = it }
chat2desk.sendClientParams(name, phone, mapOf(fields[0].id to "valor"))

// iOS
chat2desk.watchCustomFields().watch { customFields in
    self.fields = customFields?.compactMap({ $0 as? CustomField }) ?? []
}
let fieldSet: [KotlinInt: String] = [KotlinInt(value: self.fields[0].id): "valor"]
Task { try await chat2desk.sendClientParams(name: "nombre", phone: "teléfono", fieldSet: fieldSet) }

Operador y errores

Operador que atiende: chat2desk.watchOperator() (iOS) o chat2desk.operator (Android, Flow<Operator?>).
Errores: chat2desk.watchError() (iOS) o chat2desk.error (Android, Flow<Throwable?>).

Repositorios y recursos

SDK para iOS (Swift Package Manager): github.com/chat2desk/chat2desk-sdk-spm, con las notas de la versión 1.5.14.
SDK para Android: com.chat2desk:chat2desk_sdk en Maven Central.
App de ejemplo para iOS (Swift): github.com/chat2desk/ios-sdk-demo.
App de ejemplo para Android (Kotlin): github.com/chat2desk/android-sdk-demo.
Referencia de la API del SDK (generada con Dokka, en inglés): sdk.chat2desk.com.
Historial de cambios oficial (en inglés): Changelog del SDK.

Prueba el SDK con las apps de ejemplo

Las dos apps de ejemplo muestran cómo enviar mensajes con y sin adjuntos, recibir mensajes entrantes, consultar el historial, enviar los datos del cliente, ver al operador que atiende y guardar los mensajes sin conexión para enviarlos al reconectar. Para ejecutarlas necesitas una cuenta de Chat2Desk con un canal de Widget y chat en línea y sus cuatro valores (WIDGET_TOKEN, BASE_HOST, WS_HOST y STORAGE_HOST).

iOS: crea el archivo Config.xcconfig en la carpeta raíz del proyecto con la línea SIMPLE_SLASH = / y los cuatro valores. Xcode toma // como inicio de comentario, así que escribe las direcciones con esa variable, por ejemplo https:$(SIMPLE_SLASH)/tu-servidor. Abre iOS SDK Demo.xcodeproj y espera a que Swift Package Manager resuelva la dependencia (la app de ejemplo usa la versión 1.5.14).
Android: crea el archivo app/apikey.properties con WIDGET_TOKEN, BASE_HOST, WS_HOST y STORAGE_HOST, cada uno entre comillas.
Compila y ejecuta la app.

Historial de versiones

Versión	Fecha	Cambio principal
1.5.14	13/10/2026	Publicación en Swift Package Manager
1.5.13	05/10/2026	Corrige un cierre inesperado en iOS por excepciones de corrutinas; los errores se reportan en `IChat2Desk.error`
1.5.12	19/06/2026	Corrige la actualización de la base de datos al migrar desde versiones antiguas
1.5.11	10/06/2026	Registro personalizado (logger) en la configuración
1.5.7	15/07/2025	Botones de teclado en mensajes
1.4.0	24/06/2024	Búsqueda por texto y carga de mensajes antiguos

El historial completo está en el changelog oficial del SDK.

Preguntas frecuentes

¿Qué plataformas admite? iOS 12 o posterior (Swift) y Android (Kotlin); un mismo módulo compartido da soporte a ambas.

¿Funciona sin conexión? Sí: los mensajes se guardan en el dispositivo y se pueden leer sin red; los envíos requieren conexión.

¿Dónde obtengo WIDGET_TOKEN y los hosts? En la configuración de tu canal de Widget y chat en línea, sección «SDK Configuraciones».

¿Es lo mismo que la app móvil de Chat2Desk? No. La app móvil es para que tus operadores atiendan desde el celular; el SDK es para incrustar el chat en tu propia app.

¿Cuántos mensajes carga cada vez? Hasta 100 por solicitud.

¿Necesitas ayuda con tu integración?

Cuéntanos qué quieres conectar y te orientamos. Si todavía no tienes cuenta, empieza con la prueba gratuita.

Una persona programando en una laptop y otra colocando la última pieza de un rompecabezas con íconos de chat, base de datos y engranaje, que representa la ayuda con una integración de Chat2Desk

¿Prefieres escribirnos? Habla con un asesor de Chat2Desk por WhatsApp.