ZAPO — Mensajes Interactivos (API)

ZAPO NO es un canal de conexión. No aparece en Administración → Canales ni se conecta por QR u OAuth. ZAPO son endpoints de la API Externa de ChatCielo para enviar mensajes interactivos a un ticket ya existente. Si buscas conectar un número, ve a Canales. Si quieres disparar botones/listas/PIX por API, estás en el lugar correcto.

Ubicación correcta en la documentación oficial: ZAPO vive en Central do Assinante → Referência da API → 🟢 Interativo Zapo (/central-do-assinante/referencia-da-api/interativo-zapo.md). No está en Canais de comunicação ni en Administração → Canais. Esta guía lo trae a la sección API de ChatCielo para evitar la confusión más común.

¿Buscabas conectar un canal? → WhatsApp No Oficial (QR) · WhatsApp con Coexistencia (OAuth) · Modo Híbrido

Qué es ZAPO

ZAPO es el grupo de endpoints interactivos de la API Externa de ChatCielo (/v2/api/external/{apiId}/sendInteractive/zapo/*). Permiten que tu backend, n8n, Typebot u otra integración envíe mensajes que el cliente puede tocar/responder (botones, listas, PIX, enlaces, llamadas y encuestas) dentro de una conversación ya abierta (ticketId).

No crean tickets: requieren un ticketId existente.
Funcionan sobre cualquier canal que soporte interactivos (WABA y no oficiales compatibles); el render final depende del canal/motor.
Se autentican con Bearer Token del tenant + apiId de la API Externa configurada en ChatCielo.

Lista de endpoints

Base: https://{baseUrl}/v2/api/external/{apiId}/sendInteractive/zapo/{recurso}

{baseUrl} es el dominio del backend ChatCielo del tenant (sin protocolo ni barra final) — ej. api.seudominio.com.br. {apiId} es el ID de la API Externa dada de alta en el panel.

Endpoint	Recurso	Para qué sirve
`POST /v2/api/external/{apiId}/sendInteractive/zapo/quickReply`	Botones de respuesta rápida	Hasta 3 botones con `display_text` + `id`
`POST /v2/api/external/{apiId}/sendInteractive/zapo/singleSelect`	Lista (singleSelect)	Menú con secciones y filas (`title`, `rows[].title/description`)
`POST /v2/api/external/{apiId}/sendInteractive/zapo/pixButton`	Botón PIX	Botón de pago PIX (Brasil) con `pixType`, `pixKey`, `pixName`
`POST /v2/api/external/{apiId}/sendInteractive/zapo/ctaCopy`	Copiar código	Botón que copia un `copyCode` (cupón, clave)
`POST /v2/api/external/{apiId}/sendInteractive/zapo/ctaUrl`	Botón URL	Botón que abre una `url`
`POST /v2/api/external/{apiId}/sendInteractive/zapo/ctaCall`	Botón Llamar	Botón que inicia llamada a `phoneNumber`
`POST /v2/api/external/{apiId}/sendInteractive/zapo/poll`	Encuesta (poll)	Encuesta con `name`, `options[]` y `selectableCount`

Todos responden 200 OK si la solicitud fue procesada, 400 si faltan parámetros y 401 si el token es ausente/inválido.

Requisitos

API Externa creada en ChatCielo (te da el {apiId}).
Bearer Token del tenant (en la colección Postman figura como BearerToken).
ticketId válido (entero) de una conversación abierta.

POST /v2/api/external/abc123/sendInteractive/zapo/quickReply HTTP/1.1
Host: api.seudominio.com.br
Authorization: Bearer SEU_TOKEN_AQUI
Content-Type: application/json

Ejemplo principal — zapoQuickReply (botones rápidos)

{
  "ticketId": 12345,
  "body": { "text": "¿Cómo quieres continuar?" },
  "footer": { "text": "Elige una opción abajo" },
  "buttons": [
    { "display_text": "Ver catálogo", "id": "catalog" },
    { "display_text": "Hablar con asesor", "id": "human" },
    { "display_text": "Salir", "id": "exit" }
  ]
}

Campos:

ticketId (integer, requerido) — ticket destino.
body.text (string) — texto principal.
footer.text (string, opcional) — pie pequeño.
buttons[] — 1 a 3 botones; cada uno con display_text (lo que ve el cliente) e id (lo que recibes como respuesta).

Otros ejemplos por endpoint

{
  "ticketId": 12345,
  "body": { "text": "Elige tu plan" },
  "footer": { "text": "Toca para ver opciones" },
  "list": {
    "title": "Planes disponibles",
    "sections": [
      {
        "title": "Mensuales",
        "rows": [
          { "id": "basic", "title": "Básico", "description": "Hasta 500 conversaciones" },
          { "id": "pro", "title": "Pro", "description": "Hasta 2.000 conversaciones" }
        ]
      },
      {
        "title": "Anuales",
        "rows": [
          { "id": "annual_pro", "title": "Pro Anual", "description": "2 meses gratis" }
        ]
      }
    ]
  }
}

POST /v2/api/external/{apiId}/sendInteractive/zapo/singleSelect

Errores comunes y troubleshooting

Código	Causa probable	Qué hacer
401 Unauthorized	Token ausente/expirado o `apiId` no pertenece al tenant	Re-genera el Bearer Token en el panel y confirma que `{apiId}` es el de API Externa (no el ID de canal). Verifica `Authorization: Bearer ...` sin prefijos extra.
400 Bad Request	Falta `ticketId`, `body.text` o estructura de `buttons/list` inválida	Valida el JSON contra el schema OpenAPI de la página oficial (ver Fuentes). `buttons` requiere `display_text` + `id`; `singleSelect` requiere `list.sections[].rows[]`.
200 pero no llega	`ticketId` cerrado/inexistente o canal desconectado	Confirma que el ticket está Abierto/Pendiente y que el canal del ticket está Conectado en Canales. Reintenta con un ticket activo.
Botón no renderiza	Canal no soporta ese interactivo	Algunos motores no oficiales renderizan listas/poll como texto; prueba en WABA o Baileys/Evolution recientes.

¿Webhook de respuesta? Cuando el cliente toca un botón o elige una fila, la respuesta llega al ticket como mensaje entrante con el id que definiste (ej. catalog, human). Úsalo en ChatFlow con condición “si mensaje == catalog” para bifurcar el flujo.

Enlaces cruzados

¿Buscabas conectar un canal por QR? → WhatsApp No Oficial (QR)
¿Quieres coexistencia oficial (celular + panel)? → WhatsApp con Coexistencia (OAuth)
¿Quieres ahorrar con híbrido? → Modo Híbrido
Referencia rápida de automatización → API de WhatsApp Business — índice

Fuentes

Fuente primaria: 🟢 Interativo Zapo — ajudas ZDG (OpenAPI 3.0.3 con 7 operaciones: ZapoQuickReply, ZapoSingleSelect, ZapoPixButton, ZapoCtaCopy, ZapoCtaUrl, ZapoCtaCall, ZapoPoll), security bearerAuth, path param apiId.
Colección Postman: BearerToken como Authorization: Bearer y baseUrl como api.seudominio.com.br.

Traducción y adaptación a ChatCielo por el equipo de docs. Schemas resumidos de la spec oficial; valida campos exactos en la página fuente antes de publicar en producción.