Ir al contenido

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, phone o group.
  • type es direct (con phone) o group (con group_id). name es el nombre que el contacto se puso en WhatsApp, o el nombre del grupo.
  • unread_count cuenta 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=… o GET /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ónEndpoint
Leer (palomitas azules a lo no leído y el chat leído en todos lados)POST /conversations/{cnv}/read
Marcar como no leídoPOST /conversations/{cnv}/unread
Archivar / desarchivarPOST / DELETE /conversations/{cnv}/archive
Fijar / desfijarPOST / DELETE /conversations/{cnv}/pin
Silenciar / quitar silencioPOST / 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"}'
  • mute sin until silencia 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.