Chat
El módulo de Chat es el sistema central de comunicación de Vivla Tools. Permite gestionar conversaciones con huéspedes, administrar canales de soporte, crear tickets y coordinar agentes de atención.
Arquitectura
El sistema se basa en Stream Chat como proveedor de mensajería en tiempo real. El backend actúa como orquestador: gestiona canales, usuarios, permisos y sincronización, mientras que Stream Chat maneja el transporte de mensajes y la presencia.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Frontend │────▶│ Backend │────▶│ Stream Chat │
│ (React SDK) │◀────│ (NestJS) │◀────│ (SaaS) │
└──────────────┘ └──────────────┘ └──────────────┘
│
┌──────▼──────┐
│ Supabase │
│ (metadata) │
└─────────────┘
Sub-módulos
El módulo de Chat está compuesto por 17 sub-módulos en el backend:
| Sub-módulo | Descripción |
|---|
| Channels | CRUD de canales, operaciones batch (agente activo, moderadores, archivado, eliminación), filtros avanzados |
| Messages | Registro de mensajes para analytics, consulta de historial por canal |
| Bookings | Creación de canales por reserva, batch create/archive de canales de booking |
| Tickets | Sistema de tickets de soporte (campos, adjuntos, SLAs, actividad, sync con Zendesk). Ver la sección Tickets |
| Shifts | Programación de turnos de agentes de soporte |
| Invitations | Invitaciones a canales con tokens y deep links |
| Mobile | Autenticación y endpoints específicos para vivla-mobile |
| Users | Gestión de usuarios de chat |
| Quick Replies | Respuestas rápidas reutilizables por los agentes, organizadas en grupos (CRUD de grupos y respuestas bajo /chat/quick-replies) |
| Notifications | Notificaciones específicas del chat |
| Analytics | Métricas de uso: canales, usuarios, mensajes |
| Webhooks | Recepción de eventos de Stream.io, Zendesk e invitaciones |
| Sync | Sincronización de datos entre Supabase y Stream Chat |
| Property Assignments | Mapeo de propiedades a canales |
| Channel Types | Definición de tipos de canal (configuración de templates) |
| Integrations | Integraciones con servicios externos |
| Copilot | Cimientos del copiloto de IA por agente (agent_key): sesiones de conversación (regla 24h), caché de sugerencias y config de agente. Detalle en AI → §6. El motor de generación llega en una fase posterior |
Flujo principal
Creación de canales por booking
- Se reciben las reservas (bookings) desde el sistema externo
- Un agente o proceso automático crea canales asociados a cada booking
- Cada canal se vincula a una propiedad y un tipo de canal
- Se asignan agentes (activo y por defecto) y moderadores. Un canal de propiedad nunca se crea sin agente: si no se indica uno, el backend resuelve el agente por defecto desde la asignación
chat_agent de la propiedad y, si no existe, desde el turno (shift) activo que la cubre; si tampoco hay turno, la creación falla con un 400 pidiendo asignar un agente en Configuración
- El huésped accede al canal desde la app mobile
Gestión de tickets
- Un agente selecciona mensajes de una conversación
- Crea un ticket con título, prioridad y los mensajes seleccionados
- El ticket se puede actualizar, agregar más mensajes y resolver
- Filtros por estado, prioridad, propiedad y agente asignado
Webhooks
El sistema recibe eventos externos en:
| Endpoint | Origen | Validación |
|---|
POST /api/chat/webhooks/stream | Stream.io | Firma de Stream |
POST /api/chat/webhooks/zendesk | Zendesk | HMAC-SHA256 |
POST /api/chat/webhooks/invitation-accepted | Vivla | HMAC-SHA256 (X-Vivla-Signature) |
Los webhooks son públicos (sin Bearer token) pero están protegidos por validación de firma criptográfica.
