Inicio API e integraciones | Claves, endpoints y webhooks Cómo extraer respuestas de botones (Quick Reply) de campañas de WhatsApp vía API

Cómo extraer respuestas de botones (Quick Reply) de campañas de WhatsApp vía API

Última actualización el Aug 18, 2026

Cuándo usarlo

  • Cuando envías una campaña de WhatsApp con una plantilla que tiene botones de respuesta rápida (Quick Reply) y quieres saber, por campaña, quién tocó cuál botón y cuándo.

  • Para armar métricas de campaña y de botones (tasa de respuesta, cuál opción fue la más elegida) desde tu backend, sin necesidad de abrir conversación por conversación en la interfaz.

  • Es un endpoint servidor a servidor, solo de lectura. No hay interfaz para esto en Cloud Chat — los datos salen por la API.

Requisitos previos

  • Un Token de Acceso API de administrador o supervisor de Cloud Chat. Para obtener el tuyo: haz clic en tu avatar (esquina inferior izquierda) → Configuraciones de Perfil y baja hasta la sección "Token de acceso" — el campo viene enmascarado; usa los botones al lado para revelarlo o copiarlo. Con un token de agente el endpoint devuelve 401/403. Los usuarios con acceso solo a ClaudIA no ven esa sección.

  • El account_id de tu cuenta — es el número justo después de /accounts/ en la URL de Cloud Chat. Ejemplo: en https://cloudchat.cloudhumans.com/app/accounts/1/dashboard, el account_id es 1.

  • Una campaña de WhatsApp ya enviada, cuya plantilla tenga botones de Quick Reply.

  • El display_id de la campaña — mira la sección de abajo, "Cómo encontrar el ID de la campaña".

Cómo encontrar el ID de la campaña (display_id)

La interfaz de Cloud Chat no muestra el ID de la campaña (no aparece en el listado ni en la URL). Para encontrarlo, usa el endpoint de listado de campañas con el mismo token:

curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns?query=TITULO_DE_LA_CAMPANA&campaign_type=one_off' \
  -H 'api_access_token: TU_API_ACCESS_TOKEN'

  • query busca por el título de la campaña (el mismo que aparece en el listado de la interfaz) y campaign_type=one_off restringe a las campañas únicas — juntos, normalmente devuelven directo la campaña deseada.

  • Para listar todas las campañas (extracción masiva), llámalo sin query, paginando:

curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns?page=1&per_page=100' \
  -H 'api_access_token: TU_API_ACCESS_TOKEN'

  • La respuesta viene paginada en el formato { "data": [...], "meta": {...} } — default 20 por página, per_page máximo 100; itera page de 1 hasta meta.total_pages.

  • El campo id de cada campaña devuelta ya es el display_id que usas en el endpoint de respuestas — no lo confundas con ningún id interno.

{ "id": 22081, "title": "Mi campaña", "campaign_status": "completed", "campaign_type": "one_off" }

Cómo funciona

Autenticación

api_access_token: TU_API_ACCESS_TOKEN

Ruta

GET https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns/{DISPLAY_ID}/responses

  • {ACCOUNT_ID} — id de la cuenta.

  • {DISPLAY_ID} — display_id de la campaña.

Parámetros de query (opcionales)

  • page — página (default 1).

  • per_page — ítems por página (default 100, máximo 500).

Ejemplo de llamada

curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/7/campaigns/156/responses?page=1&per_page=100' \
  -H 'api_access_token: TU_API_ACCESS_TOKEN'

Tip: este curl se puede importar directo en Postman (File → Import → Raw text) — solo cambia el token y los ids.

Respuesta

La respuesta tiene tres partes: responses, summary y meta.

{
  "responses": [
    {
      "id": 27749371,
      "content": "Sim, tenho interesse e desejo prosseguir",
      "inbox_id": 174,
      "conversation_id": 1777,
      "message_type": 0,
      "status": "delivered",
      "additional_attributes": {
        "campaign_id": 188,
        "template_button_reply": true,
        "template_button_payload": "Sim, tenho interesse e desejo prosseguir"
      },
      "created_at": 1784781019,
      "sender": {
        "id": 1350835,
        "type": "contact",
        "name": "João da Silva",
        "phone_number": "+5511999998888"
      }
    }
  ],
  "summary": {
    "Sim, tenho interesse e desejo prosseguir": 1
  },
  "meta": {
    "current_page": 1,
    "total_count": 1,
    "total_pages": 1
  }
}

  • responses — cada ítem es el mensaje de respuesta del contacto (el toque en el botón). Campos útiles:

    • content — el texto del botón tocado.

    • sender — el contacto que respondió (nombre + teléfono).

    • additional_attributes.template_button_payload — el payload del botón (repite el texto del botón).

    • conversation_id / created_at — dónde y cuándo ocurrió la respuesta (created_at es un timestamp Unix, en segundos).

  • summary — conteo agregado por texto del botón: { "<texto del botón>": <cantidad> }. Es el atajo para la métrica "cuántas personas eligieron cada opción". El summary siempre considera la campaña entera, sin importar la página.

  • meta — paginación: current_page, total_count (total de respuestas de la campaña), total_pages. Atención: total_pages depende del per_page usado. Para exportar todas las respuestas, usa per_page=500 e itera page de 1 hasta total_pages.

Errores comunes

  • 401 Unauthorized — token inválido, expirado/regenerado, o el header api_access_token no fue enviado.

  • 401/403 — el token es de un usuario agente (el endpoint exige administrador o supervisor en la cuenta).

  • 404 Not Found — campaña no encontrada: o el número usado no es el display_id (mira "Cómo encontrar el ID de la campaña"), o la campaña pertenece a otra cuenta distinta del {ACCOUNT_ID} de la URL.

  • responses vacío con la campaña correcta — la plantilla no tenía botones Quick Reply, nadie tocó un botón todavía, o la campaña fue enviada antes del lanzamiento del recurso (sin datos retroactivos).

Notas importantes

  • Sin historial retroactivo. Solo aparecen respuestas registradas a partir del lanzamiento del recurso. Las campañas antiguas no se completan retroactivamente.

  • El identificador de análisis es el texto del botón. Como las plantillas no definen un payload propio, el payload solo repite el texto del botón. Agrupa/analiza por el texto (es lo que hace el summary).

  • Los conteos son por toque, no por contacto único. Si el mismo contacto toca más de un botón (o el mismo botón más de una vez), cada toque se vuelve una respuesta y entra en el summary. Para métricas por contacto único, deduplica por sender.id de tu lado.

  • Solo cuentan los toques de botón Quick Reply de campaña. Si el contacto responde con texto libre (en vez de tocar un botón), esa respuesta no entra aquí — el vínculo con la campaña solo existe cuando es un toque de botón de un envío de campaña.