Disparar mensagem proativa por API (WhatsApp e Widget Web)

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 um sistema externo (seu backend, CRM, automação de marketing) precisa iniciar uma conversa com um contato específico — sem um agente abrir manualmente.
Para avisos transacionais e proativos por contato: confirmação de pedido, lembrete de pagamento, atualização de status, retomada de carrinho.
Em dois canais, com a mesma autenticação (api_access_token):
- WhatsApp — envia uma mensagem de template aprovado para o telefone do contato.
- Widget Web de área autenticada (HMAC) — exibe uma mensagem que aparece quando o contato volta autenticado no chat do seu site/app.

Pré-requisitos

Um Token de Acesso API do Cloud Chat (disponível no seu perfil, em Perfil → Configurações → Access Token). Ele deve estar no cabeçalho api_access_token.
O account_id da sua conta (aparece na URL do Cloud Chat).
O endereço da sua instância do Cloud Chat, que é o domínio que aparece no navegador quando você acessa a plataforma (ex.: cloudchat5.cloudhumans.com). As chamadas devem ir para esse endereço. Um endereço de outra instância responde 401.
O token vale só para a instância em que foi gerado. Se gerar um novo, o anterior deixa de funcionar na hora, então atualize em todos os sistemas que o usam.
Para WhatsApp: uma caixa de entrada de WhatsApp conectada + um template aprovado pela Meta.
Para Widget Web: uma caixa de entrada de Widget Web com HMAC obrigatório (área autenticada / identidade verificada) + um contato identificável.

Como funciona

Autenticação

Os dois endpoints utilizam o mesmo cabeçalho. Nunca exponha o token no front-end — esses disparos são servidor-para-servidor.

api_access_token: SEU_API_ACCESS_TOKEN
Content-Type: application/json

Envie o token somente no cabeçalho api_access_token, só o valor, sem aspas nem o prefixo Bearer. Não adicione um cabeçalho Authorization, porque ele faz a chamada ser recusada com 401.

WhatsApp: disparo por template

Envia (push) uma mensagem ativa — chega no WhatsApp do contato na hora. Como é WhatsApp, o conteúdo precisa ser um template aprovado.

POST https://{SEU_DOMINIO}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation

{SEU_DOMINIO} é o endereço da sua instância (ex.: cloudchat5.cloudhumans.com).

{
  "inbox_id": 123,
  "phone_number": "+5511999998888",
  "template_name": "lembrete_pagamento",
  "labels": ["campanha-x", "vip"],
  "cliente": "João",
  "valor": "R$ 120,00"
}

inbox_id — a caixa de WhatsApp pela qual a mensagem é enviada.
phone_number — telefone do contato no formato internacional E.164 (com + e código do país, ex.: +5511999998888).
template_name — nome do template aprovado.
Variáveis do template — cada variável deve ser enviada como um campo no nível raiz do corpo (irmão de inbox_id/phone_number/template_name), com o nome da variável do template. Ex.: um template com as variáveis cliente e valor deve receber os campos "cliente" e "valor". Se o template usa variáveis numeradas ({{1}}, {{2}}), os campos são "1" e "2". Não coloque esses campos dentro de um objeto template_params.
labels (opcional) — array de strings com títulos de tags a aplicar na conversa criada (ex.: ["campanha-x", "vip"]). Os títulos são normalizados para minúsculas e as tags são adicionadas sem remover tags existentes. Tags novas são criadas na conta automaticamente apenas se o token for de administrador ou CX Engineer; com token de agente, títulos inexistentes são ignorados. Detalhes em Como enviar mensagem proativa pelo WhatsApp via API.

WhatsApp: limite de requisições

O endpoint de WhatsApp aceita até 200 requisições por minuto por chave de API. Acima disso, a resposta é 429 com o cabeçalho Retry-After (segundos até liberar). Aguarde esse tempo antes de reenviar e, em lotes grandes, distribua os disparos ao longo dos minutos. Uma requisição que recebeu 429 não foi processada, então reenviá-la não duplica a mensagem. Corpo da resposta, demais cabeçalhos e como o limite é contado estão em Quais são os limites de requisição (rate limits) das rotas da API do Cloud Chat?.

Widget Web (área autenticada): disparo por contato

Exibe uma mensagem que aparece de forma passiva: o widget não envia push — a mensagem surge na próxima vez que o contato abre o chat autenticado na área logada. Você pode disparar mesmo para quem ainda não abriu o chat (identificando pelo identifier).

POST https://{SEU_DOMINIO}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_web_widget_conversation

{
  "inbox_id": 456,
  "identifier": "user-42",
  "content": "Oi João! Vi que seu plano vence amanhã. Posso te ajudar a renovar?",
  "idempotency_key": "renovacao-user-42-2026-06-28"
}

inbox_id — a caixa do Web Widget (HMAC obrigatório).
Identificação do contato — envie exatamente um destes:
- identifier — seu identificador estável do usuário. Cria o contato se ainda não existir.
- email — usa um contato já identificável com aquele email.
- contact_id — o ID do contato no Cloud Chat.
content — o texto livre da mensagem (não necessita de template).
idempotency_key (opcional) — consulte abaixo.
contact_attributes (opcional) — atributos/nome para enriquecer o contato na criação.

A entrega é passiva: a mensagem só fica visível após o contato autenticar a sessão no widget (HMAC). É por isso que esse disparo é exclusivo de caixas de área logada.

Widget Web: formato do identificador

O identifier precisa ser idêntico ao valor que seu app usa para gerar o HMAC no SDK do widget para aquele usuário. Se eles divergirem (ex.: você dispara "42", mas o widget envia "user-42"), o Cloud Chat tratará como contatos diferentes e a mensagem não aparecerá para o usuário.

identifier — string estável (o mesmo do HMAC). Recomenda-se utilizar o ID do usuário no seu sistema.
email — um email válido de um contato já identificável.

Widget Web: múltiplas caixas e contatos sem telefone

Múltiplas caixas de Web Widget. O identifier identifica o contato ** em toda a conta**, então o mesmo usuário pode ser alcançado em diferentes caixas (ex.: produtos ou áreas logadas distintas) usando o mesmo identifier. O disparo ocorre sempre por caixa (inbox_id): cada caixa mantém sua própria conversa/sessão com o contato. Para falar com o usuário em duas áreas, envie uma mensagem para cada inbox_id.
Quando não há número de telefone. Diferente do WhatsApp (onde o número é a identidade), no Web Widget o contato é identificado por identifier/email e não precisa ter telefone. Contatos sem número são suportados plenamente — o telefone é irrelevante para esse canal.

Idempotência (Web Widget)

Reenvios são seguros se você usar idempotency_key. A mesma chave, dentro de 24 horas, retorna a mesma conversa, ao invés de criar uma duplicata — útil para tentativas de reenvio. Reusar a mesma chave para um contato diferente é rejeitado (erro idempotency_key_contact_mismatch).

Principais erros

Código	Significado
`inbox_id_required` / `inbox_not_found`	Caixa de entrada ausente ou não encontrada na conta.
`contact_not_identifiable`	`email`/`contact_id` fornecido não corresponde a um contato identificável.
`ambiguous_contact_match`	Os dados correspondem a mais de um contato — refine a identificação.
`invalid_contact_attributes`	`contact_attributes` inválidos para criar o contato.
`idempotency_key_contact_mismatch`	A `idempotency_key` já foi usada para outro contato.

Observações

WhatsApp = ativo (push, via template); Widget Web = passivo (texto livre, na próxima sessão autenticada). Escolha o canal de acordo com o tipo de entrega desejada.
O disparo é por contato nos dois canais (um a um), não uma campanha em massa.
A conversa criada fica fora da fila/SLA dos agentes até que o contato engaje — ela não conta como atendimento ativo enquanto ninguém responder.
Mantenha o api_access_token somente no servidor.