> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.vivla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat

> Sistema de mensajería y soporte en tiempo real basado en Stream Chat

# 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](/tickets/index)                                                                                                    |
| **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](/integrations/ai). El motor de generación llega en una fase posterior |

## Flujo principal

### Creación de canales por booking

1. Se reciben las reservas (bookings) desde el sistema externo
2. Un agente o proceso automático crea canales asociados a cada booking
3. Cada canal se vincula a una propiedad y un tipo de canal
4. 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
5. El huésped accede al canal desde la app mobile

### Gestión de tickets

1. Un agente selecciona mensajes de una conversación
2. Crea un ticket con título, prioridad y los mensajes seleccionados
3. El ticket se puede actualizar, agregar más mensajes y resolver
4. 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) |

<Note>
  Los webhooks son públicos (sin Bearer token) pero están protegidos por validación de firma criptográfica.
</Note>