Disparar mensagem proativa por API (WhatsApp e Widget Web)

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).

• 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

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://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation

{
  "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". Não inicie esses campos dentro de um objeto template_params nem utilize chaves posicionais ("1", "2").

• 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; com token de agente, títulos inexistentes são ignorados. Detalhes em Como enviar mensagem proativa pelo WhatsApp via API.

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://cloudchat.cloudhumans.com/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.

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

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.