Referencia de API
Conversaciones y mensajes
Gestiona el inbox (se abre en una pestaña nueva): lista conversaciones, cambia su estado, toma el control y envía mensajes. Requieren autenticación (se abre en una pestaña nueva) (API key o sesión).
Conversaciones
Sección titulada «Conversaciones»| Método | Ruta | Descripción |
|---|---|---|
GET | /workspaces/:workspaceId/conversations | Listar (ver filtros abajo) |
POST | /workspaces/:workspaceId/conversations | Crear/reutilizar una conversación abierta con un contacto |
GET | /workspaces/:workspaceId/conversations/:conversationId | Obtener conversación |
PATCH | /workspaces/:workspaceId/conversations/:conversationId | Actualizar status / assignedTo |
POST | /workspaces/:workspaceId/conversations/:conversationId/read | Marcar como leída, solo para el usuario que llama |
POST | /workspaces/:workspaceId/conversations/:conversationId/internal-notes | Dejar una nota interna (se abre en una pestaña nueva) que nunca llega al cliente |
PATCH | /workspaces/:workspaceId/conversations/:conversationId/take-control | Pausar la IA (se abre en una pestaña nueva) y tomar el control |
PATCH | /workspaces/:workspaceId/conversations/:conversationId/release-control | Devolver el control a la IA, con note opcional |
POST | /workspaces/:workspaceId/conversations/:conversationId/transfer | Transferir la conversación a otro asesor |
GET | /workspaces/:workspaceId/conversations/:conversationId/transfer-targets | Asesores a los que se puede transferir |
Filtros de GET .../conversations (query string, todos opcionales): status (OPEN/WAITING/RESOLVED/CLOSED), channel (WHATSAPP/WEB_WIDGET/PLAYGROUND), assignedTo (id de usuario), agentId (asistente que atiende la conversación), tagId (etiqueta del contacto), search (nombre/teléfono del contacto), isTest ('true' para listar solo conversaciones de prueba; por defecto quedan excluidas), assignee (none para las que nadie atiende), queued (1 para las que esperan en la fila a un asesor), conversationId (devuelve solo esa conversación con la forma de la lista), page, limit.
El unreadCount de cada conversación es por usuario: cuenta los mensajes del cliente posteriores a la última vez que ese usuario la marcó como leída. POST .../read no afecta al resto del equipo. Lo anterior a la activación de esta función se considera leído.
POST .../internal-notes requiere conversations:control. Cuerpo: { "content": "..." } (1 a 2000 caracteres). La nota queda en el hilo como mensaje interno y nunca se envía al cliente por ningún canal.
status (ver estados de una conversación (se abre en una pestaña nueva)):
| Valor | Significado |
|---|---|
OPEN | Abierta, la IA responde normalmente. |
WAITING | En cola, esperando que un agente humano la tome. |
RESOLVED | Resuelta por un agente. |
CLOSED | Cerrada. |
take-control pone aiPaused: true y asigna la conversación al usuario que llama (falla si ya la tomó otro agente distinto). release-control la libera de nuevo hacia la IA. Acepta un cuerpo opcional { "note": "..." } (hasta 300 caracteres) que se guarda como mensaje interno. Solo puede devolverla quien la tiene asignada, el dueño o un administrador del workspace; si la atiende otro asesor responde 403.
POST .../transfer (requiere conversations:control o conversations:manage). Cuerpo: { "toUserId": "usr_...", "note": "..." }, donde note es opcional y de hasta 300 caracteres. Solo quien tiene la conversación asignada o el dueño puede transferirla (403 en otro caso). Respuestas de rechazo:
| Código | Cuándo |
|---|---|
400 | El destino no es miembro, no puede atender conversaciones, está Terminando, En receso o fuera de línea, es la misma persona que actúa o que ya la atiende, o la conversación no está abierta o no tiene asesor. |
409 | El destino está al límite de conversaciones, o la conversación cambió de asesor mientras se transfería. |
La escritura es condicional: si dos transferencias llegan a la vez, solo una gana. El turno y la fila no se tocan, se deja un mensaje interno, se notifica al destino y se avisa al cliente en su idioma.
GET .../transfer-targets devuelve los asesores del asistente responsable, de menor a mayor carga, y al final los no elegibles: { userId, name, avatarUrl, active, limit, status, eligible, reason }. reason explica por qué no se puede elegir (por ejemplo, “Está en receso” o “Está al límite de conversaciones”). Quien no puede atender conversaciones no aparece.
Mensajes
Sección titulada «Mensajes»| Método | Ruta | Descripción |
|---|---|---|
GET | /workspaces/:workspaceId/conversations/:conversationId/messages | Listar mensajes (paginado; sin page trae la última página, es decir los más recientes) |
POST | /workspaces/:workspaceId/conversations/:conversationId/messages | Enviar mensaje |
POST | /workspaces/:workspaceId/conversations/:conversationId/send-template | Enviar una plantilla de WhatsApp (se abre en una pestaña nueva) aprobada |
POST | /workspaces/:workspaceId/conversations/:conversationId/attachments/upload-ticket | Pedir un permiso de subida para un adjunto (solo conversaciones de WhatsApp) |
DELETE | /workspaces/:workspaceId/conversations/:conversationId/messages/:messageId | Eliminar mensaje |
PATCH | /workspaces/:workspaceId/conversations/:conversationId/messages/:messageId/feedback | Calificar una respuesta de la IA (helpful / not_helpful / null para quitar la calificación) |
GET .../messages acepta page y limit (por defecto 50) en la query string.
Ejemplo — enviar un mensaje
Sección titulada «Ejemplo — enviar un mensaje»/workspaces/:workspaceId/conversations/:conversationId/messagesCuerpo de la petición
Sección titulada «Cuerpo de la petición»| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
content | string (máx. 10 000) | Sí | Contenido del mensaje. |
type | string | No | TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT, TEMPLATE (por defecto TEXT). |
mediaKey | string (máx. 500) | No | storageKey que devolvió upload-ticket, si el mensaje lleva adjunto. |
replyToMessageId | string | No | Mensaje de la conversación al que se responde; el contacto lo ve citado. |
mediaMimeType | string | No | Tipo MIME del adjunto. |
filename | string | No | Nombre de archivo del adjunto. |
Ejemplo — tomar el control de una conversación
Sección titulada «Ejemplo — tomar el control de una conversación»/workspaces/:workspaceId/conversations/:conversationId/take-controlParámetros de ruta
Sección titulada «Parámetros de ruta»| Parámetro | Tipo | Descripción |
|---|---|---|
workspaceId | string | Identificador del workspace. |
conversationId | string | Conversación a tomar. |
Este endpoint no recibe cuerpo: el responsable es el usuario autenticado (vía sesión o el titular de la API key).
Disponibilidad de asesores (receso)
Sección titulada «Disponibilidad de asesores (receso)»Controla quién recibe conversaciones transferidas. Ver receso y equipo de asesores (se abre en una pestaña nueva).
| Método | Ruta | Descripción |
|---|---|---|
GET | /workspaces/:workspaceId/advisor-availability | Estado de los asesores con fila (quien no aparece está disponible) |
GET | /workspaces/:workspaceId/advisor-availability/team | Vista de equipo: estado y carga de cada miembro. Requiere workspace:settings |
GET | /workspaces/:workspaceId/advisor-availability/me | Mi estado |
PUT | /workspaces/:workspaceId/advisor-availability/me | Ponerme en receso o disponible. Requiere conversations:control o conversations:manage |
PUT | /workspaces/:workspaceId/advisor-availability/:userId | Cambiar el estado de otro asesor. Solo el dueño del workspace |
Cuerpo de los PUT:
| Campo | Tipo | Descripción |
|---|---|---|
status | AVAILABLE | ON_BREAK | Nuevo estado. |
minutes | entero o null | Solo para ON_BREAK: duración del receso (5 a 480 minutos). Con null o sin valor, dura hasta que el asesor vuelva. |
Al poner a un asesor en receso, sus conversaciones pasan a otro asesor disponible o vuelven al asistente. Al marcarlo disponible, la fila avanza.
Horario de contacto de los seguimientos
Sección titulada «Horario de contacto de los seguimientos»Define cuándo pueden salir los seguimientos automáticos (se abre en una pestaña nueva) del workspace.
| Método | Ruta | Descripción |
|---|---|---|
GET | /workspaces/:workspaceId/contact-policy | Obtener el horario de contacto (si no se configuró, el predeterminado: lunes a viernes 7:00 a 19:00, sábados 8:00 a 15:00) |
PUT | /workspaces/:workspaceId/contact-policy | Guardar el horario. Requiere workspace:settings |
Cuerpo del PUT:
| Campo | Tipo | Descripción |
|---|---|---|
schedule | objeto | Claves "1" (lunes) a "7" (domingo), cada una con { "start": "HH:MM", "end": "HH:MM" } o null si ese día no se escribe. Al menos un día habilitado. |
holidays | array de AAAA-MM-DD | Festivos sin contacto, en la zona horaria del workspace (máx. 120). |
Relacionado
Sección titulada «Relacionado»- Bandeja de conversaciones (se abre en una pestaña nueva) · Tomar el control (se abre en una pestaña nueva)
- Los mensajes que llegan por el widget web se crean con el chat público del widget (se abre en una pestaña nueva), no con este endpoint.
