Saltar a contenido

Consultar mensajes y cuentas

Además de enviar, la API te deja leer: el estado de un mensaje puntual, listados con filtros para reconciliar en lote, y tus cuentas de WhatsApp. Todo con la misma autenticación x-api-key y siempre acotado a tu cuenta.

Tip

Para enterarte de los cambios de estado en tiempo real no hagas polling: usá webhooks. Estos endpoints brillan para reconciliar (ej.: "todos mis mensajes sent de las últimas 48 h") o como plan B.

GET /messages/{id}

Devuelve un mensaje tuyo. {id} puede ser el messageId de Arplyx o tu propio externalId — usá el que tengas a mano.

curl https://api.arplyx.com/messages/turno-4812-recordatorio \
  -H "x-api-key: ak_live_xxxxxxxx..."

Respuesta 200:

{
  "messageId": "b7a19c4d-…",
  "externalId": "turno-4812-recordatorio",
  "recipient": "+5493416631539",
  "channel": "whatsapp_direct",
  "status": "read",
  "attemptCount": 1,
  "lastErrorCode": null,
  "broadcastId": null,
  "whatsappAccountId": "9d2f81b3-…",
  "createdAt": "2026-07-04T12:00:00.000Z",
  "sentAt": "2026-07-04T12:00:02.000Z",
  "deliveredAt": "2026-07-04T12:00:04.000Z",
  "readAt": "2026-07-04T12:01:10.000Z",
  "failedAt": null
}
Campo Descripción
status Ver ciclo de vida.
sentAt / deliveredAt / readAt / failedAt Timestamp de cada transición; null si (aún) no ocurrió.
attemptCount Intentos de envío realizados.
lastErrorCode Código del último error de envío (null si no hubo).
broadcastId Presente si el mensaje nació de un broadcast.

Errores: 404 message_not_found si el id no existe, no es tuyo o el mensaje ya fue purgado por la retención de tu plan (3–30 días según plan). Diseñá tu reconciliación asumiendo que los mensajes viejos desaparecen.

GET /messages (listado)

Lista tus mensajes, los más recientes primero, con filtros y paginación por cursor.

curl "https://api.arplyx.com/messages?status=sent&since=2026-07-02T00:00:00Z&limit=100" \
  -H "x-api-key: ak_live_xxxxxxxx..."

Parámetros de query (todos opcionales):

Parámetro Descripción
status pending, queued, sent, delivered, read o failed.
channel whatsapp_direct o whatsapp_meta.
whatsappAccountId Solo mensajes de esa cuenta.
since / until Rango sobre createdAt (ISO 8601).
limit 1–100, default 50.
cursor El nextCursor de la página anterior.

Respuesta 200:

{
  "messages": [ { "…mismo shape que GET /messages/{id}…" } ],
  "nextCursor": "MTc1MTYzMDQwMDAwMHxiN2ExOWM0ZA"
}
  • nextCursor es null cuando no hay más páginas. Es un cursor opaco: pasalo tal cual, no lo construyas.
  • Un cursor mal formado responde 400 invalid_cursor.

Ejemplo de reconciliación — "¿qué pasó con todo lo que quedó sent en las últimas 48 h?":

curl "https://api.arplyx.com/messages?status=sent&since=$(date -u -d '48 hours ago' +%FT%TZ)" \
  -H "x-api-key: ak_live_xxxxxxxx..."

GET /whatsapp-accounts

Lista tus cuentas de WhatsApp vinculadas, con el whatsappAccountId que necesitás para enviar.

curl https://api.arplyx.com/whatsapp-accounts \
  -H "x-api-key: ak_live_xxxxxxxx..."

Respuesta 200:

{
  "accounts": [
    {
      "id": "9d2f81b3-…",
      "type": "WHATSAPP_DIRECT",
      "status": "CONNECTED",
      "phoneNumber": "+5493416631539",
      "displayName": "Estudio Pilates Centro",
      "connectedAt": "2026-06-11T14:30:00.000Z"
    }
  ]
}
Campo Valores
type WHATSAPP_DIRECT | META_OFFICIAL
status PENDING, AUTHENTICATING, CONNECTED, DISCONNECTED, BANNED, ERROR

Mayúsculas vs. minúsculas

Ojo al parsear: type usa el formato del modelo interno (WHATSAPP_DIRECT, mayúsculas), mientras que el campo channel al enviar usa minúsculas (whatsapp_direct, whatsapp_meta). La correspondencia es WHATSAPP_DIRECT → whatsapp_direct y META_OFFICIAL → whatsapp_meta.