WhatsApp: leer las conversaciones por la API
Lista las conversaciones de un número de WhatsApp y lee los mensajes de un contacto por la API de XBASE, con la ventana de 24 horas de cada conversación.
Actualizado el
Con la lectura de conversaciones, tu sistema o agente ve lo que escribió el contacto, lo que respondió la empresa y si la ventana de 24 horas está abierta, antes de elegir entre un mensaje libre y una plantilla. Las dos rutas solo leen: nada cambia en la conversación.
La clave necesita el permiso whatsapp:read (Leer conversaciones de WhatsApp en la pantalla de claves).
Listar las conversaciones
GET https://api.xbase.app/api/external/v1/whatsapp/conversations?numberId={numberId}| Parámetro | Obligatorio | Regla |
|---|---|---|
numberId | sí | Número del workspace (listar los números) |
limit | no | Cuántas conversaciones, de 1 a 100. Por defecto: 50 |
before | no | Fecha ISO 8601. Trae las conversaciones con actividad anterior a ella (ver paginación) |
curl "https://api.xbase.app/api/external/v1/whatsapp/conversations?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b&limit=20" \
-H "Authorization: Bearer $XBASE_API_KEY"Respuesta 200, de la conversación más reciente a la más antigua:
[
{
"threadId": "c1d7f0b2-5a4e-4f3d-9c2b-1a0e9d8c7b6a",
"phone": "5521999990000",
"contact": { "id": "8b2f4c1e-3d5a-4e6f-9a8b-7c6d5e4f3a2b", "name": "Maria Souza" },
"lastActivityAt": "2026-11-07T14:02:11.000Z",
"lastMessage": {
"id": "5a0e4c31-7b2d-4e8f-a1c3-9d6b5e4f3a21",
"messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABIYFDNBMjc1QjE3RjdCNEE1QzlEMjA4AA==",
"direction": "in",
"type": "text",
"text": "¿Mi pedido ya salió?",
"at": "2026-11-07T14:02:11.000Z"
},
"unansweredCount": 2,
"window": { "open": true, "expiresAt": "2026-11-08T14:02:11.000Z", "reason": null }
}
]| Campo | Descripción |
|---|---|
threadId | Conversación en XBASE |
phone | Teléfono del contacto con código de país, solo dígitos |
contact | Contacto de la conversación (id y name), o null |
lastActivityAt | Última actividad de la conversación. Úsala en before para pedir la página siguiente |
lastMessage | Último mensaje, en el formato de los mensajes (sin status ni author), o null |
unansweredCount | Mensajes del contacto después de la última respuesta de la empresa |
window | Ventana de 24 horas de la conversación |
Leer una conversación
GET https://api.xbase.app/api/external/v1/whatsapp/conversations/{phone}?numberId={numberId}phone es el teléfono del contacto con código de país. Se quitan +, espacios, guiones y paréntesis.
| Parámetro | Obligatorio | Regla |
|---|---|---|
numberId | sí | Número del workspace |
limit | no | Cuántos mensajes, de 1 a 200. Por defecto: 50 (los más recientes) |
before | no | Fecha ISO 8601. Trae los mensajes anteriores a ella |
curl "https://api.xbase.app/api/external/v1/whatsapp/conversations/5521999990000?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
-H "Authorization: Bearer $XBASE_API_KEY"Respuesta 200, con los mensajes en orden cronológico:
{
"contact": { "id": "8b2f4c1e-3d5a-4e6f-9a8b-7c6d5e4f3a2b", "name": "Maria Souza", "phone": "5521999990000" },
"threadId": "c1d7f0b2-5a4e-4f3d-9c2b-1a0e9d8c7b6a",
"window": { "open": true, "expiresAt": "2026-11-08T14:02:11.000Z", "reason": null },
"messages": [
{
"id": "0b9c8d7e-6f5a-4b3c-2d1e-0f9a8b7c6d5e",
"messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABEYEjQ1QzM1RkQ2RDhGNjZBMDQ3MwA=",
"direction": "out",
"type": "template",
"text": "Hola Maria, tu pedido 12345 fue entregado el 04/11 a las 14:28.",
"at": "2026-11-07T13:40:02.000Z",
"status": "read",
"author": "Integración de la tienda"
},
{
"id": "5a0e4c31-7b2d-4e8f-a1c3-9d6b5e4f3a21",
"messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABIYFDNBMjc1QjE3RjdCNEE1QzlEMjA4AA==",
"direction": "in",
"type": "text",
"text": "¿Mi pedido ya salió?",
"at": "2026-11-07T14:02:11.000Z",
"status": null,
"author": null
}
]
}Si el teléfono nunca conversó con el número, la respuesta también es 200: threadId nulo, messages vacío y la ventana cerrada con reason: "no_contact_message". Para iniciar la conversación, envía una plantilla.
Mensajes
| Campo | Descripción |
|---|---|
id | Id del mensaje en XBASE |
messageId | Id del mensaje en Meta (wamid.…), el mismo de los webhooks. Úsalo para reaccionar o marcar como leído. Puede ser null |
direction | in: del contacto. out: de la empresa (persona, agente o API) |
type | text, image, audio, video, document, sticker, location, template, interactive… |
text | Texto, pie o transcripción del audio. La plantilla viene con las variables completadas. La multimedia sin texto viene con una etiqueta, como [imagem] |
at | Cuándo se registró el mensaje |
status | Estado del envío: submitted, sent, delivered, read, deleted o error. En los mensajes recibidos, en general null |
author | Quién lo envió por la empresa: el nombre de la persona, del agente o de la clave de API |
La multimedia (imagen, audio, documento) no viene en la respuesta. Los registros de la conversación que no son mensajes, como un cambio de etiqueta o de etapa, quedan fuera.
Ventana de 24 horas
| Campo | Descripción |
|---|---|
window.open | true: se puede enviar un mensaje libre ahora |
window.expiresAt | Cuándo se cierra la ventana (24 horas después del último mensaje del contacto), o null |
window.reason | Con la ventana cerrada: no_contact_message (el contacto nunca escribió), window_expired (pasaron más de 24 horas) o awaiting_template_reply (la empresa envió una plantilla y el contacto aún no respondió). null con la ventana abierta |
La lectura usa la misma regla del envío: con open: true, POST /whatsapp/messages no rechaza por ventana cerrada en ese momento.
Paginación
- Conversaciones: envía en
beforeellastActivityAtde la última conversación recibida. Una lista menor quelimites la última página. - Mensajes: envía en
beforeelatdel primer mensaje recibido para pedir los anteriores.
Errores
| Status | code | Cuándo |
|---|---|---|
| 400 | (sin code) | Parámetro inválido, como un teléfono mal formado, limit fuera de rango o before que no es fecha |
| 403 | MISSING_SCOPE | La clave no tiene el permiso whatsapp:read |
| 404 | NUMBER_NOT_FOUND | El número no existe en este workspace |
Mira el formato completo en Errores.