En Chat, usuario y agente no son roles de tu producto. Son quién habla en la conversación. Eso cambia webhooks, métricas y el JWT que entregas en la app.
En pocas palabras
Cuándo usar USER
Usa USER para todo el que entra al chat desde tu aplicación. Cada persona tiene un externalUserId estable en tu base.
Flujo típico:
- La persona inicia sesión en tu app
- Tu backend hace upsert (
PUT /v1/chat/users)
- Tu backend emite el JWT (
POST /v1/chat/users/token)
- La app abre el WebSocket con ese JWT y envía como esa persona
El JWT lleva kind: USER. Quien tiene ese token es esa persona en la conversación.
Cuándo usar AGENT
Usa AGENT cuando el mensaje debe aparecer como tu empresa, no como un usuario final.
Casos:
- Alguien del equipo responde en el panel (Chat o Inbox) — Notifique ya crea el agente
agent:{workspaceUserId}
- Tu backend envía un aviso en el hilo como soporte
- Quieres métricas de enviados (agente) vs recibidos (usuario) en el detalle del Chat App
workspaceUserId debe ser miembro del workspace. El externalUserId por defecto es agent:{workspaceUserId}.
Luego envía como ese agente:
Qué no mezclar
- No entregues JWT de
AGENT en la app del cliente. El cliente habla con JWT de USER.
- No registres al equipo como
USER si atiende desde el panel — el webhook saldría como chat.received.
- Dos
USER en un 1:1 es conversación entre personas de tu producto. Un USER y un AGENT es atención.
Flags del Chat App
Quién puede crear conversación, crear grupo y añadir miembros con JWT de usuario vale para cualquiera con token de usuario. Un agente por API Key ignora esas flags: el backend siempre puede crear.
Ver Quick Start y Enviar mensajes.
