Ir al contenido

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).

MétodoRutaDescripción
GET/workspaces/:workspaceId/conversationsListar (ver filtros abajo)
POST/workspaces/:workspaceId/conversationsCrear/reutilizar una conversación abierta con un contacto
GET/workspaces/:workspaceId/conversations/:conversationIdObtener conversación
PATCH/workspaces/:workspaceId/conversations/:conversationIdActualizar status / assignedTo
POST/workspaces/:workspaceId/conversations/:conversationId/readMarcar como leída, solo para el usuario que llama
POST/workspaces/:workspaceId/conversations/:conversationId/internal-notesDejar una nota interna (se abre en una pestaña nueva) que nunca llega al cliente
PATCH/workspaces/:workspaceId/conversations/:conversationId/take-controlPausar la IA (se abre en una pestaña nueva) y tomar el control
PATCH/workspaces/:workspaceId/conversations/:conversationId/release-controlDevolver el control a la IA, con note opcional
POST/workspaces/:workspaceId/conversations/:conversationId/transferTransferir la conversación a otro asesor
GET/workspaces/:workspaceId/conversations/:conversationId/transfer-targetsAsesores 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)):

ValorSignificado
OPENAbierta, la IA responde normalmente.
WAITINGEn cola, esperando que un agente humano la tome.
RESOLVEDResuelta por un agente.
CLOSEDCerrada.

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ódigoCuándo
400El 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.
409El 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.

MétodoRutaDescripción
GET/workspaces/:workspaceId/conversations/:conversationId/messagesListar mensajes (paginado; sin page trae la última página, es decir los más recientes)
POST/workspaces/:workspaceId/conversations/:conversationId/messagesEnviar mensaje
POST/workspaces/:workspaceId/conversations/:conversationId/send-templateEnviar una plantilla de WhatsApp (se abre en una pestaña nueva) aprobada
POST/workspaces/:workspaceId/conversations/:conversationId/attachments/upload-ticketPedir un permiso de subida para un adjunto (solo conversaciones de WhatsApp)
DELETE/workspaces/:workspaceId/conversations/:conversationId/messages/:messageIdEliminar mensaje
PATCH/workspaces/:workspaceId/conversations/:conversationId/messages/:messageId/feedbackCalificar 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.

POST/workspaces/:workspaceId/conversations/:conversationId/messages
CampoTipoRequeridoDescripción
contentstring (máx. 10 000)SíContenido del mensaje.
typestringNoTEXT, IMAGE, AUDIO, VIDEO, DOCUMENT, TEMPLATE (por defecto TEXT).
mediaKeystring (máx. 500)NostorageKey que devolvió upload-ticket, si el mensaje lleva adjunto.
replyToMessageIdstringNoMensaje de la conversación al que se responde; el contacto lo ve citado.
mediaMimeTypestringNoTipo MIME del adjunto.
filenamestringNoNombre de archivo del adjunto.

Ejemplo — tomar el control de una conversación

Sección titulada «Ejemplo — tomar el control de una conversación»
PATCH/workspaces/:workspaceId/conversations/:conversationId/take-control
ParámetroTipoDescripción
workspaceIdstringIdentificador del workspace.
conversationIdstringConversació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).

Controla quién recibe conversaciones transferidas. Ver receso y equipo de asesores (se abre en una pestaña nueva).

MétodoRutaDescripción
GET/workspaces/:workspaceId/advisor-availabilityEstado de los asesores con fila (quien no aparece está disponible)
GET/workspaces/:workspaceId/advisor-availability/teamVista de equipo: estado y carga de cada miembro. Requiere workspace:settings
GET/workspaces/:workspaceId/advisor-availability/meMi estado
PUT/workspaces/:workspaceId/advisor-availability/mePonerme en receso o disponible. Requiere conversations:control o conversations:manage
PUT/workspaces/:workspaceId/advisor-availability/:userIdCambiar el estado de otro asesor. Solo el dueño del workspace

Cuerpo de los PUT:

CampoTipoDescripción
statusAVAILABLE | ON_BREAKNuevo estado.
minutesentero o nullSolo 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.

Define cuándo pueden salir los seguimientos automáticos (se abre en una pestaña nueva) del workspace.

MétodoRutaDescripción
GET/workspaces/:workspaceId/contact-policyObtener 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-policyGuardar el horario. Requiere workspace:settings

Cuerpo del PUT:

CampoTipoDescripción
scheduleobjetoClaves "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.
holidaysarray de AAAA-MM-DDFestivos sin contacto, en la zona horaria del workspace (máx. 120).