find_ai_chat library

Flutter SDK for embedding the Find AI chat assistant — equivalent to widget.js for Flutter apps (mobile & web), talking to the same public webchat API.

Quick start:

FindChatWidget(
  connectionId: 'your-connection-id',
  baseUrl: 'https://api.example.com',
  theme: FindChatTheme.light,
  mode: FindChatMode.floating,
)

See the package README for the full guide (setup, modes, programmatic control, known limitations).

Classes

ChatStreamNode: Nodo actualmente en ejecución (node.started sin su node.finished aún).
ChatTurnCompletedData: data del evento terminal message.completed. response es el texto canónico del turno (puede diferir del texto acumulado por deltas si hubo un reintento de nodo — por eso siempre se usa este valor, no el acumulado).
FindChatAction: Una acción del menú flotante del chat (long press sobre el botón de enviar). El SDK trae una sola por default — "Eliminar conversación" — y la app host puede agregar, quitar o reordenar con FindChatWidget(actionsBuilder: ...).
FindChatActionConfirmation: Texto del paso de confirmación que se muestra antes de ejecutar una FindChatAction. Declararlo en la acción (en vez de hardcodear el diálogo en el panel) hace que cada acción nueva decida por sí misma si necesita confirmar — el panel la resuelve genéricamente.
FindChatClient: Cliente HTTP + SSE de la API pública del canal "webchat" (/api/v1/channels/webchat/{connectionId}/...). Sin estado de sesión (visitor_id/conversation_id) — eso lo maneja FindChatSessionStore; este cliente solo sabe hablar el protocolo HTTP.
FindChatConfig: Espeja WebchatPublicConfig — la respuesta de GET /api/v1/channels/webchat/{connectionId}/config. Solo branding y flags públicos, nunca secretos.
FindChatController: Controla un chat: inicialización, envío de mensajes, apertura/cierre (en modos FindChatMode.floating/FindChatMode.drawer) y limpieza de la conversación. ChangeNotifier estándar de Flutter — se puede escuchar con ListenableBuilder/AnimatedBuilder, o pasarlo explícito a FindChatWidget para controlarlo desde fuera del widget tree:
FindChatConversationsResult: Respuesta de GET /conversations: las conversaciones del visitante del token, actividad más reciente primero.
FindChatConversationSummary: Un item de GET /conversations (solo conexiones auth_mode: "signed").
FindChatDrawerView: Modo FindChatMode.drawer: sin burbuja — se abre/cierra solo por código (controller.open()/close()/toggle()). En pantallas angostas (<600dp) se muestra como bottom sheet; en pantallas anchas, como panel lateral deslizándose desde la derecha. Se inserta vía Overlay, igual que FindChatFloatingBubble — requiere un Navigator/Overlay ancestro.
FindChatEmbeddedView: Modo FindChatMode.embedded: el chat como un widget más del árbol, sin overlay ni burbuja — ocupa el espacio que le da el padre (usalo dentro de un Expanded/SizedBox/Scaffold.body, como cualquier otro widget).
FindChatEnvironment: Resuelve la URL base del backend sin hardcodearla en el SDK.
FindChatFloatingBubble: Modo FindChatMode.floating: burbuja flotante (esquina inferior derecha) que abre/cierra una tarjeta de chat superpuesta. Se inserta vía Overlay — flota sobre TODA la app, no solo sobre el widget donde se montó FindChatWidget, igual que la burbuja position:fixed del widget web. Requiere un Navigator/Overlay ancestro (automático bajo MaterialApp/WidgetsApp).
FindChatHistoryMessage: Un mensaje de GET /history. Distinto de FindChatMessage porque el rol llega como string libre del backend (puede incluir roles que la UI no muestra, p.ej. "system") — el caller filtra antes de convertir.
FindChatHistoryResult: Respuesta de GET /history.
FindChatMessage: Un mensaje de la conversación (enviado por el visitante o recibido del asistente). id es local para mensajes recién enviados (no hay un id de servidor todavía) o el id de historial cuando viene de /history.
FindChatSendResult: Respuesta de POST /messages (202).
FindChatSessionStore: Persiste visitor_id/conversation_id por conexión, vía shared_preferences (funciona igual en mobile y Flutter web, ahí usa localStorage por debajo — mismo mecanismo que el widget JS).
FindChatState: Estado inmutable del chat. FindChatController es el único que lo muta; la UI solo lo lee (vía ListenableBuilder/AnimatedBuilder).
FindChatWidget: Punto de entrada del SDK. Ejemplo mínimo:

Enums

FindChatColorScheme: Modo de color persistido de la conexión (color_scheme). No confundir con FindChatTheme, que es el override que puede pasar el dev.
FindChatMode: Cómo se presenta el chat dentro del árbol de widgets de la app.
FindChatRemoteDisplayMode: Modo de visualización persistido de la conexión (display_mode).
FindChatRole: Autor de un mensaje del chat.
FindChatStatus: Fase actual del FindChatController.
FindChatTheme: Modo de color del widget.
FindChatVisualStyle: Tratamiento visual del chat en sí (independiente de FindChatMode).

Properties

findChatVisitorIdPattern → RegExp: ^[a-zA-Z0-9_-]{8,64}$ — mismo formato que exige el backend para visitor_id/conversation_id (webchat_models.VISITOR_ID_PATTERN).
final

Functions

findChatVisualStyleFromWire(String? value) → FindChatVisualStyle: "classic" / "gpt_style" ⇒ tipo. Cualquier otro valor (incl. ausente) cae a FindChatVisualStyle.classic — mismo default que el backend.
generateFindChatVisitorId() → String: UUID v4 sin guiones (32 hex chars) — mismo formato que crypto.randomUUID().replace(/-/g, "") en el widget web. Los bits de versión/variante se setean por prolijidad, no porque el backend los valide (solo exige el charset/largo de arriba).

Typedefs

FindChatActionsBuilder = List<FindChatAction> Function(BuildContext context, List<FindChatAction> defaults): Hook para que la app host arme el menú a partir de las acciones que trae el SDK. Recibe defaults ya resueltas contra el estado actual (p. ej. el borrado llega con enabled: false durante un turno en curso) y devuelve la lista final. Devolver una lista vacía deshabilita el menú por completo: el botón de enviar vuelve a comportarse como un botón común.
FindChatThemeBuilder = ThemeData Function(BuildContext context, ThemeData baseTheme): Permite ajustar el ThemeData que el SDK ya resolvio para el chat.
FindChatTokenProvider = Future<String> Function(): Provee el visitor token para conexiones con auth_mode: "signed".

Exceptions / Errors

FindChatApiException: Error HTTP de la API pública de webchat. El body de error del backend es {"error": "HTTP_ERROR", "message": "..."} (o {"error":"VALIDATION_ERROR", "message":"...","details":[...]} para 422) — no {"detail": "..."} pese a que algunos clientes viejos revisan ese campo por compatibilidad; acá leemos ambos por las dudas.
FindChatAuthException: 401 del backend en una conexión con auth_mode: "signed": el visitor token falta, es inválido o expiró — incluso después de reintentar una vez con un token fresco del tokenProvider. La app host debe renovar la sesión de su usuario (o revisar que el secret con el que firma siga siendo el de la conexión).
FindChatTurnFailedException: El turno terminó con un evento SSE terminal error (falló el flujo).
FindChatTurnUnavailableException: No se pudo sostener la conexión SSE tras varios reintentos consecutivos sin recibir ningún evento.

find_ai_chat library

Classes

Enums

Properties

Functions

Typedefs

Exceptions / Errors

find_ai_chat package

find_ai_chat library