Apariencia
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:
| Filtro | Qué hace |
|---|---|
phone | Solo el chat directo con ese número, en ambos sentidos. No incluye lo que esa persona escribe en grupos. |
group | Solo los mensajes de ese grupo (grp_..., ver Grupos). |
since | Solo mensajes que entraron a ZAPPIO a partir de ese momento (ISO 8601 o Unix en segundos). |
until | Solo 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
| Para | Consulta |
|---|---|
| Ver una conversación completa | GET /api/v1/messages?phone=%2B5215500000000&limit=100, y después las páginas con cursor |
| El último mensaje de un chat antes de un momento | GET /api/v1/messages?phone=%2B5215500000000&until=1793577600&limit=1 |
| Lo que llegó desde un momento, de todos los chats | GET /api/v1/messages?since=1793577600&limit=100, y después las páginas con cursor |
| Solo lo que te escribieron en un periodo | GET /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
sincedesde 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 /messagescon 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}traehistory:statusessyncingmientras llega ycompletedcuando terminó, conimported(mensajes guardados). Espera acompletedantes de leer los chats completos. Esnullsi 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.