Conversaciones y mensajes

Gestiona el inbox: lista conversaciones, cambia su estado, toma el control y envía mensajes. Requieren autenticación (API key o sesión).

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
PATCH	/workspaces/:workspaceId/conversations/:conversationId/take-control	Pausar la IA y tomar el control
PATCH	/workspaces/:workspaceId/conversations/:conversationId/release-control	Devolver el control a la IA

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), page, limit.

status (ver estados de una conversación):

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.

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 aprobada
POST	/workspaces/:workspaceId/conversations/:conversationId/attachment	Subir un adjunto (multipart, campo file, máx. 16 MB) y devolver su URL pública
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.

Consejo

attachment solo sube el archivo y devuelve { "url": "..." }. Para que el contacto lo reciba hay que enviarlo después como mensaje normal con POST .../messages, usando esa URL en mediaUrl y el type correspondiente (IMAGE, AUDIO, DOCUMENT).

Ejemplo — enviar un mensaje

POST /workspaces/:workspaceId/conversations/:conversationId/messages Copiar

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, DOCUMENT, TEMPLATE (por defecto TEXT).
mediaUrl	string (máx. 2000)	No	URL del adjunto, si type no es TEXT.
mediaMimeType	string	No	Tipo MIME del adjunto.
filename	string	No	Nombre de archivo del adjunto.

Consejo

Para responder como humano sin que el asistente interfiera, primero llama a take-control. El asistente vuelve a responder recién cuando llames a release-control.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/conversations/CONV_ID/messages" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "¡Hola! Ya revisamos tu caso." }'

Node

await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/conversations/CONV_ID/messages',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ content: '¡Hola! Ya revisamos tu caso.' }),
  }
);

Python

import requests

requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/conversations/CONV_ID/messages",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"content": "¡Hola! Ya revisamos tu caso."},
)

Respuesta 201

{
  "success": true,
  "data": {
    "id": "msg_abc123",
    "conversationId": "CONV_ID",
    "role": "USER",
    "type": "TEXT",
    "content": "¡Hola! Ya revisamos tu caso.",
    "sentAt": "2026-06-18T09:00:00.000Z"
  }
}

Ejemplo — tomar el control de una conversación

PATCH /workspaces/:workspaceId/conversations/:conversationId/take-control Copiar

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

cURL

curl -X PATCH "https://api.waiify.com/workspaces/WORKSPACE_ID/conversations/CONV_ID/take-control" \
  -H "Authorization: Bearer TU_API_KEY"

Node

await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/conversations/CONV_ID/take-control',
  { method: 'PATCH', headers: { Authorization: 'Bearer TU_API_KEY' } }
);

Python

import requests

requests.patch(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/conversations/CONV_ID/take-control",
    headers={"Authorization": "Bearer TU_API_KEY"},
)

Respuesta 200

{
  "success": true,
  "data": {
    "id": "CONV_ID",
    "status": "OPEN",
    "aiPaused": true,
    "assignedTo": "USER_ID"
  }
}

Relacionado

• Bandeja de conversaciones · Tomar el control
• Los mensajes que llegan por el widget web se crean con el chat público del widget, no con este endpoint.