WhatsApp APIAPI

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ámetroObligatorioRegla
numberIdsíNúmero del workspace (listar los números)
limitnoCuántas conversaciones, de 1 a 100. Por defecto: 50
beforenoFecha 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 }
  }
]
CampoDescripción
threadIdConversación en XBASE
phoneTeléfono del contacto con código de país, solo dígitos
contactContacto 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
unansweredCountMensajes del contacto después de la última respuesta de la empresa
windowVentana 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ámetroObligatorioRegla
numberIdsíNúmero del workspace
limitnoCuántos mensajes, de 1 a 200. Por defecto: 50 (los más recientes)
beforenoFecha 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

CampoDescripción
idId del mensaje en XBASE
messageIdId del mensaje en Meta (wamid.…), el mismo de los webhooks. Úsalo para reaccionar o marcar como leído. Puede ser null
directionin: del contacto. out: de la empresa (persona, agente o API)
typetext, image, audio, video, document, sticker, location, template, interactive…
textTexto, pie o transcripción del audio. La plantilla viene con las variables completadas. La multimedia sin texto viene con una etiqueta, como [imagem]
atCuándo se registró el mensaje
statusEstado del envío: submitted, sent, delivered, read, deleted o error. En los mensajes recibidos, en general null
authorQuié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

CampoDescripción
window.opentrue: se puede enviar un mensaje libre ahora
window.expiresAtCuándo se cierra la ventana (24 horas después del último mensaje del contacto), o null
window.reasonCon 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 before el lastActivityAt de la última conversación recibida. Una lista menor que limit es la última página.
  • Mensajes: envía en before el at del primer mensaje recibido para pedir los anteriores.

Errores

StatuscodeCuándo
400(sin code)Parámetro inválido, como un teléfono mal formado, limit fuera de rango o before que no es fecha
403MISSING_SCOPELa clave no tiene el permiso whatsapp:read
404NUMBER_NOT_FOUNDEl número no existe en este workspace

Mira el formato completo en Errores.

Preguntas frecuentes

Ver también

En esta página