Apariencia
Conversaciones (bandeja)
Una conversación (cnv_…) es un chat de una instancia: un contacto o un grupo. Existe en cuanto el chat tiene un mensaje en ZAPPIO y se actualiza con cada mensaje nuevo, en los dos sentidos. Con ella armas la bandeja de tu CRM sin recorrer todo el historial.
Leer conversaciones necesita el scope messages:read; actuar sobre ellas, messages:send y la instancia conectada. Ninguna acción cuenta como mensaje.
Listar la bandeja
bash
curl "https://zappio.cloud/api/v1/conversations?instance=ins_...&unread=true" \
-H "Authorization: Bearer $ZAPPIO_API_KEY"json
{
"data": [
{
"id": "cnv_...",
"instance_id": "ins_...",
"type": "direct",
"phone": "5215500000000",
"group_id": null,
"name": "Ana López",
"unread_count": 2,
"marked_unread": false,
"archived": false,
"pinned": false,
"muted": false,
"muted_until": null,
"last_message_at": "2026-11-13T17:02:11+00:00",
"last_message": { "id": "msg_...", "direction": "inbound", "text": "¿Tienen envío a Toluca?", "...": "..." }
}
],
"meta": { "per_page": 25, "next_cursor": null, "prev_cursor": null }
}- Orden: la actividad más reciente primero. Paginación por cursor (
meta.next_cursor). - Filtros:
instance,unread(true: con no leídos o marcada como no leída),archived,pinned,phoneogroup. typeesdirect(conphone) ogroup(congroup_id).namees el nombre que el contacto se puso en WhatsApp, o el nombre del grupo.unread_countcuenta los mensajes que el contacto escribió desde la última vez que se leyó el chat: por la API, en el panel o en el teléfono del negocio. Responder desde el teléfono también lo lee.- Los mensajes de la conversación se consultan con
GET /messages?phone=…oGET /messages?group=grp_…(ver Historial).
Leer, marcar como no leído, archivar, fijar y silenciar
Cada acción llega primero a WhatsApp y se ve en todos los dispositivos del número (teléfono y WhatsApp Web). Si WhatsApp no la acepta, no cambia nada y recibes el error.
| Acción | Endpoint |
|---|---|
| Leer (palomitas azules a lo no leído y el chat leído en todos lados) | POST /conversations/{cnv}/read |
| Marcar como no leído | POST /conversations/{cnv}/unread |
| Archivar / desarchivar | POST / DELETE /conversations/{cnv}/archive |
| Fijar / desfijar | POST / DELETE /conversations/{cnv}/pin |
| Silenciar / quitar silencio | POST / DELETE /conversations/{cnv}/mute |
bash
curl -X POST "https://zappio.cloud/api/v1/conversations/cnv_.../mute" \
-H "Authorization: Bearer $ZAPPIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"until": "2026-11-14T08:00:00-06:00"}'mutesinuntilsilencia para siempre (muted: true,muted_until: null).- Leer da palomitas azules a los mensajes no leídos más recientes (hasta 100). Si tu cuenta tiene apagadas las confirmaciones de lectura, WhatsApp no muestra palomitas azules, pero el chat sí queda leído.
- La respuesta es la conversación ya actualizada.
Mantenerla al día por webhook
Suscríbete a conversation.updated: llega cuando un chat se lee, se marca como no leído, se archiva, se fija o se silencia, también cuando eso pasa en el teléfono. data.changes dice qué cambió. Los mensajes nuevos no lo disparan: usa message.received y message.sent_external para mover el último mensaje y los no leídos.