Referencia del SDK

Todos los SDK de Telybot (Android, iOS, React Native, Flutter, Ionic) implementan el mismo contrato pequeño. Si ha usado uno, los ha usado todos.

La API

Llamar	Lo que hace
`init` / `initialize`	Almacena tu client id. Lo valida y falla de forma evidente si tiene un formato incorrecto.
`show`	Muestra el chat sobre tu app. Acepta una pregunta opcional para el cuadro de mensaje (0.2.0).
`dismiss`	Lo cierra.
`isShowing`	Ya sea que se presente en este momento.
chat integrado	El chat dentro de una de tus propias pantallas, como una pestaña de Ayuda (0.2.0).
`onShow` / `onDismiss`	Te avisa cuando el chat se abre y se cierra, en Android e iOS (0.2.0).
`setVisitor`	El nombre, el teléfono y el correo de tu cliente con sesión iniciada, ofrecidos en los formularios del chat (0.2.0).
`hasUnreadReply` / `onReply`	Una respuesta de tu equipo que el cliente aún no ha visto (0.2.0).

Abrir con una pregunta. Pasa una pregunta a show y se coloca en el cuadro de mensaje del chat; el cliente la lee y toca enviar. Viaja en el #fragment del enlace, así que nunca llega a un registro del servidor. Hasta 500 caracteres, en una sola línea.

El chat dentro de tu propia pantalla. Android KeydaBotView, iOS KeydaBot.makeChatViewController o SwiftUI KeydaBotView, React Native <KeydaBotChat />, Flutter KeydaBotChat, y el embedWidget() del paquete de Ionic. No tiene botón de cerrar: la navegación de tu pantalla es la salida. En Android, Atrás cierra primero un artículo o carrito abierto: React Native y Flutter lo hacen por ti mientras el chat es la pantalla en primer plano, y con la KeydaBotView nativa tu gestión de Atrás llama a su goBack().

Tu cliente con sesión iniciada. Dale al SDK el nombre, el número de teléfono o el correo de tu cliente y el chat rellena lo que tu app ya sabe. Los datos se ofrecen, nunca se envían: aparecen en el formulario de «hablar con una persona», en un pedido, una reserva y una pregunta de bienvenida que pide nombre, teléfono o correo, y es el cliente quien los envía. Viajan en el #fragment del enlace y son la palabra de tu app, no una identidad verificada. Un valor que el chat rechazaría se omite: un nombre de más de 80 caracteres, un número de teléfono sin 8 a 15 dígitos, una dirección de correo sin un dominio válido. El chat a pantalla completa de Ionic se abre en el navegador del sistema, que guarda las direcciones en su historial, así que no los acepta; su widget integrado sí.

Una respuesta mientras el chat está cerrado. Cuando un cliente pide hablar con una persona y cierra el chat, tu respuesta desde el panel espera en la conversación. Los SDK de Android, iOS, React Native y Flutter la comprueban cuando tu app vuelve al primer plano y se lo indican a tu app, para que puedas mostrar un punto en tu botón de chat hasta que el cliente abra el chat. Solo preguntan por los chats en los que el cliente pidió una persona en los últimos 14 días. Un chat que tu app mantiene cargado fuera de la vista, como una pestaña de Ayuda en segundo plano, no cuenta como leído: el punto permanece hasta que el cliente mira. No es una notificación push: la respuesta se detecta cuando se abre la app.

Deliberadamente no hay nada más. Ni API para enviar mensajes ni llamada de identidad de usuario, porque ninguna de las dos funciona todavía de extremo a extremo, y un método que no funciona es peor que uno que falta.

La URL que abre cada SDK

{baseUrl}/chat/{clientId}

baseUrl tiene por defecto https://telybot.com y se puede anular en cualquier plataforma, ya sea para pruebas o para una instalación autohospedada.

Por qué usar una vista web y qué te cuesta

Hay una interfaz de chat, servida por la plataforma, y cada superficie la carga.

Lo que obtienes: un cambio que el propietario hace en el panel —color de acento, mensaje de bienvenida, nombre del bot, activación— llega a todas las aplicaciones de inmediato, sin necesidad de una nueva versión. Una corrección se aplica en todas partes a la vez. El chat es idéntico en todas las plataformas.

Lo que cuesta: el chat necesita una conexión. No hay modo sin conexión ni notificaciones push por ahora.

Preferimos que sepas esto antes de lanzar el producto en lugar de descubrirlo después.

Garantías que ofrece cada SDK

Salidas de navegación. Un enlace a cualquier otro origen se abre en el navegador del sistema en lugar de reemplazar el chat. Sin esto, un solo toque en un enlace del pie de página termina la conversación de un cliente sin posibilidad de volver.
Continuidad de la conversación. El almacenamiento DOM está activo, por lo que un cliente que cierra la app y regresa encuentra su hilo donde lo dejó (durante 24 horas).
El teclado nunca cubre el campo de entrada.
Se respetan las áreas seguras — no se dibuja ningún chat debajo de una muesca o indicador de inicio.
Ningún fallo llega a tu aplicación. Si se produce un error de carga, se muestra la opción de reintentar.
Sin analíticas, sin identificadores de dispositivos, sin dependencias de terceros. Añadir un SDK de Telybot no añade ningún rastreador a tu aplicación.
Atrás cierra primero lo que el cliente está mirando. En Android, Atrás sobre un artículo, carrito o reserva abiertos cierra eso, y solo después el chat (SDK 0.2.0 y posteriores).

Dentro del chat

Todo esto viene de la página alojada, así que llega a todas las apps sin actualizar el SDK:

Un mensaje de bienvenida con botones de sugerencia, en el idioma configurado para el bot.
La conversación se guarda en el dispositivo durante 24 horas, y el chat no crea ningún identificador de visitante. En un sitio web, una conversación dura una pestaña del navegador. (El chat a pantalla completa del SDK de Ionic necesita la 0.2.0 para esto.)
Pedidos y reservas, cuando el negocio los acepta: un carrito, fechas y horas de reserva, un enlace para llamar al negocio cuando un pedido o una reserva ha esperado demasiado, y «Añadir al calendario» para una reserva confirmada.
Adjuntos: fotos (JPEG, PNG, WebP, GIF) y archivos PDF, DOCX, TXT, CSV y MD. Los SDK de Android y Flutter necesitan la 0.1.4 o posterior para el botón de adjuntar, y Flutter necesita la 0.2.0 para documentos.
«Añadir al calendario» es un enlace a un archivo .ics. iOS lo abre en Calendario como un calendario al que suscribirse. Android ofrece la app de calendario del teléfono cuando esta importa archivos .ics — el Google Calendar actual lo hace — y, si no, el navegador descarga el archivo.

Formato de Client ID

kb_live_ followed by 8-48 hexadecimal characters

Cualquier otra cosa se rechaza al iniciar en lugar de abrir un 404 frente a un cliente. El Client ID es público por diseño —es visible en cualquier sitio web que incruste el widget— y no tiene la capacidad de leer ni modificar tu cuenta. Consulta límites y seguridad.

Fuente

Público, con licencia MIT: github.com/telybotai/telybot-Sdks. El contrato compartido que cumple cada paquete está en CONTRACT.md en la parte superior de ese repositorio.