Soporte en vivo, dentro de
tu app de Flutter

§ 00Visión general

El SDK de Flutter habla el mismo protocolo de widget anónimo que usa el chat de tu sitio web, de modo que los clientes pueden contactar con el soporte desde dentro de tu app móvil, en las mismas conversaciones que tus agentes ya gestionan en la bandeja de entrada compartida.

Se distribuye como dos paquetes:

• easylivechat — cliente de protocolo headless más estado reactivo, sin interfaz
• easylivechat_ui — widgets prediseñados y personalizables: lanzador, pantalla de chat, formulario previo al chat, adjuntos, CSAT

§ 01Instalación

Añade el SDK al pubspec.yaml de tu app. La mayoría de las apps quieren easylivechat_ui, que reexporta el núcleo. Recurre al headless easylivechat por sí solo únicamente cuando estés creando una interfaz totalmente personalizada.

dependencies:
  easylivechat_ui: ^0.1.0   # prebuilt UI + the headless core
  # — or, headless only —
  easylivechat: ^0.1.0

Requiere Flutter 3.19 o una versión más reciente. socket_io_client debe ser una versión 3.x (Engine.IO v4) para coincidir con el servidor.

§ 02Inicio rápido (interfaz lista para usar)

Inicializa el cliente una vez con el slug de tu espacio de trabajo y luego coloca un lanzador en tu árbol de widgets. La burbuja abre un chat totalmente integrado: formulario previo al chat, hilo en tiempo real, indicador de escritura, adjuntos, CSAT, un formulario sin conexión para horario de atención, además de tematización gestionada por el servidor y RTL.

import 'package:easylivechat_ui/easylivechat_ui.dart';

await EasyLiveChat.instance.boot(
  const EasyLiveChatConfig(
    apiBase: 'https://api.livechattools.com',
    tenantSlug: 'acme',          // your workspace slug
  ),
  storage: SecurePrefsStorage(), // durable visitorId + JWT
);

// In your widget tree — a floating bubble that opens the full chat:
Stack(children: [ MyApp(), const EasyLiveChatLauncher() ]);

Encuentra el slug de tu espacio de trabajo en tu panel de control. El lanzador se inicializa de forma diferida en la primera apertura; proporciona un almacenamiento duradero para que la identidad del visitante sobreviva a los reinicios de la app.

§ 03Headless (crea tu propia interfaz)

¿Prefieres tu propio sistema de diseño? Controla el cliente headless directamente. Todo se expone como ValueListenables y Streams que puedes vincular a cualquier gestión de estado.

import 'package:easylivechat/easylivechat.dart';

final chat = EasyLiveChat.instance;
await chat.boot(const EasyLiveChatConfig(
  apiBase: 'https://api.livechattools.com', tenantSlug: 'acme'),
  storage: myDurableStorage);  // implement EasyLiveChatStorage
await chat.open();             // config → resume → prechat/anon → connect

chat.messages.addListener(rebuild);    // ValueListenable<List<ChatMessage>>
chat.agentTyping.addListener(rebuild);

final res = chat.sendMessage('Hello!'); // optimistic; res.serverMessageId on ack
await chat.submitFeedback(rating: 5);

open() orquesta todo el ciclo de vida: obtiene la configuración, reanuda cualquier conversación abierta, condiciona al formulario previo al chat o comienza de forma anónima y luego conecta el socket en tiempo real.

§ 04Cómo funciona

Cuando se abre una sesión, el servidor emite un token efímero por conversación. El SDK lo usa para las llamadas REST y el socket en tiempo real, lo vuelve a emitir de forma transparente antes de que expire y se reconecta con una recuperación segura ante huecos cuando la red móvil se cae.

Todo es anónimo por defecto: el SDK genera un id de visitante duradero en el dispositivo —sin necesidad de iniciar sesión— y, opcionalmente, recopila un nombre y un correo electrónico a través del formulario previo al chat del tenant.

Seguridad: nunca incrustes la clave de API de tu tenant en una app publicada; es un secreto de servidor a servidor. El SDK de Flutter solo utiliza el token de sesión por visitante, que es seguro para un cliente distribuido.

§ 05Qué requiere trabajo en el servidor

La experiencia completa de chat en primer plano funciona hoy sin cambios en el backend. La única capacidad que requiere trabajo en el servidor son las notificaciones push en segundo plano —entregar una notificación de “un agente ha respondido” a una app cerrada— porque actualmente el backend solo envía notificaciones push a los agentes. Se necesita un registro de push de visitantes y su distribución para habilitarlo; el hook de push del SDK permanece inactivo hasta entonces.

Seguimientos recomendados antes de un lanzamiento público: limitación de tasa en la creación de sesiones y el envío de mensajes, un endpoint de actualización de tokens y soporte para subir archivos HEIC/MOV para el contenido multimedia del teléfono.