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

A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá.

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 ou supervisor do Cloud Chat. Para pegar o seu: clique no seu avatar (canto inferior esquerdo) → Configurações de Perfil e role até a seção "Token de acesso" — o campo vem mascarado, use os botões ao lado para revelar ou copiar. Com token de agente o endpoint retorna 401/403. Usuários com acesso somente à ClaudIA não veem essa seção.
O account_id da sua conta — é o número logo após /accounts/ na URL do Cloud Chat. Exemplo: em https://cloudchat.cloudhumans.com/app/accounts/1/dashboard, o account_id é 1.
Uma campanha de WhatsApp já disparada, cujo template tenha botões de Quick Reply.
O display_id da campanha — veja a seção abaixo "Como descobrir o ID da campanha".

Como descobrir o ID da campanha (display_id)

A interface do Cloud Chat não exibe o ID da campanha (ele não aparece na listagem nem na URL). Para descobrir, use o endpoint de listagem de campanhas com o mesmo token:

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

query busca pelo título da campanha (o mesmo que aparece na listagem da interface) e campaign_type=one_off restringe às campanhas únicas — juntos, normalmente devolvem direto a campanha desejada.
Para listar todas as campanhas (extração em massa), chame sem query, paginando:

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

A resposta vem paginada no formato { "data": [...], "meta": {...} } — default 20 por página, per_page máximo 100; itere page de 1 até meta.total_pages.
O campo id de cada campanha retornada já é o display_id que você usa no endpoint de respostas — não confunda com nenhum id interno.

{ "id": 22081, "title": "Minha campanha", "campaign_status": "completed", "campaign_type": "one_off" }

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'

Dica: esse curl pode ser importado direto no Postman (File → Import → Raw text) — basta trocar o token e os ids.

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 (created_at é um timestamp Unix, em segundos).
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". O summary sempre considera a campanha inteira, independente da página.
meta — paginação: current_page, total_count (total de respostas da campanha), total_pages. Atenção: total_pages depende do per_page usado. Para exportar todas as respostas, use per_page=500 e itere page de 1 até total_pages.

Erros comuns

401 Unauthorized — token inválido, expirado/regenerado, ou o header api_access_token não foi enviado.
401/403 — o token é de um usuário agente (o endpoint exige administrador ou supervisor na conta).
404 Not Found — campanha não encontrada: ou o número usado não é o display_id (veja "Como descobrir o ID da campanha"), ou a campanha pertence a outra conta que não a do {ACCOUNT_ID} da URL.
responses vazio com a campanha certa — o template não tinha botões Quick Reply, ninguém tocou em botão ainda, ou a campanha foi disparada antes do lançamento do recurso (sem dados retroativos).

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).
As contagens são por toque, não por contato único. Se o mesmo contato tocar em mais de um botão (ou no mesmo botão mais de uma vez), cada toque vira uma resposta e entra no summary. Para métricas por contato único, deduplique por sender.id no seu lado.
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.