Como extrair respostas de botões (Quick Reply) de campanhas WhatsApp via API

Quando usar

• Quando você dispara uma campanha de WhatsApp com um template que tem botões de resposta rápida (Quick Reply) e quer saber, por campanha, quem tocou em qual botão e quando.

• Para montar métricas de campanha e de botões (taxa de resposta, qual opção foi mais escolhida) a partir do seu backend, sem precisar abrir conversa a conversa na interface.

• É um endpoint servidor-para-servidor, somente leitura. Não há interface para isso no Cloud Chat — os dados saem pela API.

Pré-requisitos

• Um Token de Acesso API de administrador do Cloud Chat (em Perfil → Configurações → Access Token). Com token de agente o endpoint retorna 401/403.

• O account_id da sua conta (aparece na URL do Cloud Chat).

• Uma campanha de WhatsApp já disparada, cujo template tenha botões de Quick Reply.

• O display_id da campanha — é o número que aparece na URL/listagem da campanha (não o id interno do banco).

Como funciona

Autenticação

api_access_token: SEU_API_ACCESS_TOKEN

Rota

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

• {ACCOUNT_ID} — id da conta.

• {DISPLAY_ID} — display_id da campanha.

Parâmetros de query (opcionais)

• page — página (default 1).

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

Exemplo de chamada

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

Resposta

A resposta tem três partes: responses, summary e 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 item é a mensagem de resposta do contato (o toque no botão). Campos úteis:

  • content — o texto do botão tocado.

  • sender — o contato que respondeu (nome + telefone).

  • additional_attributes.template_button_payload — o payload do botão (ecoa o texto do botão).

  • conversation_id / created_at — onde e quando a resposta aconteceu.

• summary — contagem agregada por texto do botão: { "<texto do botão>": <quantidade> }. É o atalho para a métrica "quantas pessoas escolheram cada opção".

• meta — paginação: current_page, total_count (total de respostas da campanha), total_pages.

Notas importantes

• Sem histórico retroativo. Só aparecem respostas registradas a partir do lançamento do recurso. Campanhas antigas não são preenchidas retroativamente.

• O identificador de análise é o texto do botão. Como os templates não definem um payload próprio, o payload apenas repete o texto do botão. Agrupe/analise pelo texto (é o que o summary faz).

• Só contam toques de botão Quick Reply de campanha. Se o contato responder com texto livre (em vez de tocar num botão), essa resposta não entra aqui — o vínculo com a campanha só existe quando é um toque de botão de um envio de campanha.