Interacciones y Mensajeria

El modulo de Interacciones es el mas complejo del backend. Gestiona conversaciones en tiempo real a traves de multiples canales de mensajeria.

Arquitectura del sistema

                   Meta (WhatsApp/IG/Messenger)
                            |
                            v
               Communications Service (externo)
                            |
                     webhook POST
                            |
                            v
                    BoostAPI Ingestion
                   /interactions/webhooks/communications
                            |
                            v
                  Projection + Routing
                            |
                  +---------+---------+
                  |                   |
                  v                   v
             MySQL (local)     WebSocket push
          (conversations,      (/interactions)
           message index,
           timeline events)

Canales soportados

Canal	Codigo	Estado
WhatsApp	whatsapp	Produccion
Instagram	instagram	Disponible
Messenger	messenger	Disponible
TikTok	tiktok	Planificado
Web	web	Planificado

Servicios principales

Servicio	Funcion
CommunicationsClientService	Cliente HTTP al servicio externo de Communications
InteractionsCommunicationsContextService	Resuelve contexto runtime: entity mapping, webhook URLs, API keys
CommunicationsAccessPolicyService	Determina que usuarios pueden acceder a Communications
InteractionsProjectionService	Proyecta webhooks a estado local de conversaciones
InteractionsRoutingService	Routing de mensajes entrantes a agentes (round-robin con colas/filtros)
InteractionsRealtimeService	RxJS Subject para broadcast de eventos a WebSocket
InteractionsGateway	Gateway Socket.IO (namespace /interactions)
InteractionsInlineWorkerService	Procesa eventos de inbox en linea

Tipos de mensaje soportados

Se pueden enviar los siguientes tipos de mensaje:

• text – Texto plano
• image – Imagenes (con caption opcional)
• video – Videos
• audio – Notas de voz / audio
• document – Documentos (PDF, etc.)
• location – Ubicacion geografica
• contacts – Tarjetas de contacto
• reaction – Reacciones a mensajes
• template – Plantillas aprobadas de WhatsApp
• interactive – Mensajes interactivos:
  • button – Botones de accion
  • list – Listas con opciones
  • cta-url – Call-to-action con URL
  • cta-url-image – CTA con URL e imagen

Endpoints de conversaciones

Metodo	Ruta	Descripcion
GET	/interactions/conversations	Listar conversaciones / inbox
GET	/interactions/conversations/:id	Detalle de conversacion
GET	/interactions/conversations/:id/history	Historial de mensajes
PATCH	/interactions/conversations/:id/workspace-notes	Notas del vendedor
POST	/interactions/conversations/:id/read	Marcar como leida
POST	/interactions/conversations/:id/follow-up	Marcar seguimiento

Catalogo dentro de conversacion

Metodo	Ruta	Descripcion
GET	/interactions/conversations/:id/catalog/context	Contexto de catalogo
GET	/interactions/conversations/:id/catalog/products	Productos del catalogo
POST	/interactions/conversations/:id/catalog/send	Enviar producto por chat

Envio de mensajes

Metodo	Ruta	Descripcion
POST	/interactions/conversations/:id/messages/text	Enviar texto
POST	/interactions/conversations/:id/messages/image	Enviar imagen (multipart)
POST	/interactions/conversations/:id/messages/video	Enviar video (multipart)
POST	/interactions/conversations/:id/messages/audio	Enviar audio (multipart)
POST	/interactions/conversations/:id/messages/document	Enviar documento (multipart)
POST	/interactions/conversations/:id/messages/location	Enviar ubicacion
POST	/interactions/conversations/:id/messages/contacts	Enviar contactos
POST	/interactions/conversations/:id/messages/reaction	Enviar reaccion
POST	/interactions/conversations/:id/messages/template	Enviar plantilla WhatsApp
POST	/interactions/conversations/:id/messages/interactive/*	Enviar interactivo

Plantillas

Metodo	Ruta	Descripcion
GET	/interactions/templates	Listar plantillas
POST	/interactions/templates	Crear plantilla
PATCH	/interactions/templates/:id	Actualizar plantilla
DELETE	/interactions/templates/:id	Eliminar plantilla

Media proxy

Metodo	Ruta	Descripcion
GET	/interactions/media/:mediaId	Proxy de media de WhatsApp

WebSocket en tiempo real

El gateway Socket.IO escucha en el namespace /interactions.

Autenticacion

Se acepta JWT via:

1. auth.token en el handshake
2. Header [REDACTED] [REDACTED]<token>
3. Query parameter token

Rooms

Room	Formato	Proposito
Entity	interactions:entity:{entityId}	Todos los eventos de la entidad
Chat	interactions:entity:{entityId}:chat:{externalChatId}	Eventos de un chat especifico
Conversation	interactions:entity:{entityId}:conversation:{conversationId}	Eventos de una conversacion

Eventos

Evento	Direccion	Descripcion
interaction.ready	Server -> Client	Conexion exitosa
interaction.chat.subscribe	Client -> Server	Suscribirse a un chat
interaction.chat.unsubscribe	Client -> Server	Desuscribirse de un chat
Eventos tipados	Server -> Client	Mensajes nuevos, actualizaciones de estado, etc.

Sistema de routing

El routing de mensajes entrantes funciona con:

1. Colas (routing_queue) – Definen grupos de agentes disponibles
2. Miembros (routing_queue_member) – Empleados asignados a colas
3. Filtros (routing_filter) – Reglas para decidir a que cola va un mensaje
4. Round-robin (routing_rr_cursor) – Distribucion equitativa entre agentes

Configuracion por entidad

Cada entidad tiene su configuracion de Communications en la tabla interaction_communications_config:

• communications_entity_id – ID de la entidad en el servicio de Communications
• external_app_id – ID de la app en Communications
• base_url – URL base del servicio
• api_key – API key para autenticacion
• meta_access_token – Token de acceso de Meta (WhatsApp)

Tunnel de desarrollo

Para desarrollo local, el modulo soporta un Cloudflare Quick Tunnel que expone el webhook local a internet. Se activa con COMMUNICATIONS_DEV_TUNNEL_ENABLED=true.

Referencia privada: Ver BoostAPI/docs/interactions-front-api.md, BoostAPI/docs/interactions-outbound-channels-runbook.md y BoostAPI/docs/interactions-contact-timeline-architecture.md para detalles de implementacion.