Principal APIs Como enviar mensagem proativa pelo WhatsApp via API

Como enviar mensagem proativa pelo WhatsApp via API

Última atualização em May 21, 2026

Quando usar

  • Você quer iniciar uma conversa de WhatsApp por API a partir de um sistema externo
  • Você precisa disparar templates aprovados pela Meta com variáveis dinâmicas
  • Você precisa entender o comportamento esperado do ticket criado por essa API

Pré-requisitos

Sobre este artigo

Este endpoint cria uma conversa proativa pelo WhatsApp usando um template previamente configurado. Os parâmetros do template são dinâmicos e variam conforme a configuração do template.

Comportamento de criação do ticket

Como o sistema não sabe qual agente deve receber, a mensagem não nasce assignada. Por isso o balão aparece verde (mensagens automáticas), em vez de laranja.

  • Sempre gera um novo ticket

  • O ticket nasce com status em aberto

Se o cliente tiver dois tickets em aberto, novas mensagens enviadas pelo cliente serão sempre direcionadas ao ticket mais recente.

Endpoint

POST https://cloudchat.cloudhumans.com/api/v1/accounts/{account_id}/conversations/create_proactive_whatsapp_conversation

Headers

Header Valor
content-type application/json
api_access_token Chave de acesso da API

Parâmetros do body

Parâmetro Obrigatório Descrição
inbox_id Sim ID da inbox por onde a mensagem será enviada
phone_number Sim Número do destinatário em formato E.164
template_name Sim Nome exato do template aprovado
header_attachment Não URL do anexo, se o template suportar mídia no cabeçalho
button_param_# Não Variáveis de botões — substituir # pelo índice (0 a N)
Variáveis do template Não Variáveis específicas do template (chave-valor na raiz do JSON)

Sobre as variáveis dinâmicas

Templates podem conter variáveis como {{contact.name}}, {{contact.email}} ou estáticas como "Fulaninho". Envie essas variáveis diretamente na raiz do JSON, ao lado de inbox_id, phone_number e template_name.

Exemplo de requisição

curl --location 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/create_proactive_whatsapp_conversation' \
  --header 'content-type: application/json' \
  --header 'api_access_token: ACCESS_TOKEN' \
  --data '{
    "inbox_id": "INBOX_ID",
    "phone_number": "+5511999998888",
    "template_name": "test_template",
    "header_attachment": "ATTACHMENT_URL",
    "button_param_0": "BUTTON PARAMETER",
    "button_param_1": "ANOTHER BUTTON PARAMETER",
    "name": "John Doe",
    "email": "[email protected]",
    "custom_code": "12345"
  }'

Onde encontrar os parâmetros

  • account_id — no painel administrativo da conta

  • inbox_id — ID da caixa de entrada configurada (https://cloudchat.cloudhumans.com/app/accounts/{account_id}/settings/inboxes/{inbox_id})

  • api_access_token — gere no painel de configuração de API

  • Variáveis dinâmicas — consulte a configuração do template no painel administrativo. Esses parâmetros vão na raiz do payload.

Certifique-se de que o número de telefone esteja no formato E.164, com o código do país.

Observações