Ir al contenido

Historial de conversaciones ​

GET /api/v1/messages (scope messages:read) devuelve los mensajes enviados y recibidos, los más recientes primero, con paginación por cursor. Con estos filtros obtienes el historial de una conversación:

FiltroQué hace
phoneSolo el chat directo con ese número, en ambos sentidos. No incluye lo que esa persona escribe en grupos.
groupSolo los mensajes de ese grupo (grp_..., ver Grupos).
sinceSolo mensajes que entraron a ZAPPIO a partir de ese momento (ISO 8601 o Unix en segundos).
untilSolo mensajes que entraron a ZAPPIO hasta ese momento (ISO 8601 o Unix en segundos).

phone y group no se combinan. Los dos se pueden combinar con since, until, instance, direction, type y status.

El historial de un contacto ​

bash
curl "https://zappio.cloud/api/v1/messages?phone=%2B5215500000000&limit=100" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

El número va en formato internacional (código de país + número), con o sin +, espacios o guiones. En celulares de México, 52 + 10 dígitos y 521 + 10 dígitos son el mismo chat: cualquiera de los dos trae ambos.

Para la página siguiente, repite la misma consulta con cursor= y el valor de meta.next_cursor, hasta que sea null (ver Convenciones).

Un rango de fechas ​

bash
curl "https://zappio.cloud/api/v1/messages?phone=%2B5215500000000&since=2026-11-01T00:00:00-06:00&until=2026-11-30T23:59:59-06:00" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

Las fechas se comparan con el momento en que el mensaje entró a ZAPPIO (created_at). Sin zona horaria, se toman en UTC. También aceptan Unix en segundos: since=1793577600.

Consultas frecuentes ​

ParaConsulta
Ver una conversación completaGET /api/v1/messages?phone=%2B5215500000000&limit=100, y después las páginas con cursor
El último mensaje de un chat antes de un momentoGET /api/v1/messages?phone=%2B5215500000000&until=1793577600&limit=1
Lo que llegó desde un momento, de todos los chatsGET /api/v1/messages?since=1793577600&limit=100, y después las páginas con cursor
Solo lo que te escribieron en un periodoGET /api/v1/messages?direction=inbound&since=2026-11-01&until=2026-11-30

Mantener tu sistema sincronizado ​

Si guardas los mensajes en tu propio sistema (un CRM, una mesa de ayuda, un reporte):

  • Carga inicial: recorre el historial con phone (o sin él, para todo) y el cursor.
  • Al día: usa los webhooks (message.received, message.sent, …) para registrar cada mensaje nuevo sin consultar.
  • Recuperar un hueco (por ejemplo, si tu sistema estuvo caído): consulta con since desde el último mensaje que guardaste.

La paginación es por cursor: no se saltan ni se repiten mensajes aunque lleguen nuevos mientras recorres las páginas.

Desde cuándo hay historial ​

  • Números vinculados por QR: al escanear el código, WhatsApp manda a ZAPPIO los chats de los últimos 30 días. Aparecen en GET /messages con su fecha real, en ambos sentidos, sin disparar webhooks ni contar como uso. Puede tardar unos minutos en llegar completo.
  • ¿Ya terminó de llegar? GET /api/v1/instances/{instance} trae history: status es syncing mientras llega y completed cuando terminó, con imported (mensajes guardados). Espera a completed antes de leer los chats completos. Es null si el número se vinculó antes de que existiera esta función.
  • Desde entonces: todo lo que pasa por el número queda guardado, incluidas las respuestas que se escriben directo desde el teléfono o WhatsApp Web (salen como enviadas, sin webhook ni consumo).
  • Números vinculados antes: pídele al teléfono el último mes de un chat con una sola llamada.

Traer el último mes de un chat ​

POST /api/v1/messages/history (scope messages:read) le pide al teléfono los mensajes de los últimos 30 días de ese chat, anteriores al más viejo que ZAPPIO ya tiene:

bash
curl -X POST "https://zappio.cloud/api/v1/messages/history" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instance": "ins_01EXAMPLE00000000000000001", "phone": "+5215500000000"}'

Para un grupo, manda group (grp_...) en vez de phone. Responde 202 con {"data": {"requested": true}}. El teléfono los manda por partes y ZAPPIO sigue pidiendo hasta cubrir el mes: en menos de un minuto quedan en GET /messages?phone=.... Una petición por chat por minuto.

Si no se pidió nada responde 200 con requested: false y el motivo: NO_MESSAGES (el chat no tiene ningún mensaje desde dónde empezar) o WINDOW_REACHED (ya llega a 30 días). La instancia debe estar conectada (409 INSTANCE_NOT_CONNECTED) y el teléfono con internet; si el teléfono no contesta, simplemente no llegan mensajes.