Principal APIs Como enviar mensagem proativa pelo WhatsApp via API

Como enviar mensagem proativa pelo WhatsApp via API

Última atualização em Jul 22, 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.

  • Gera um novo ticket — exceto se a inbox estiver configurada com conversa única (lock to single conversation), caso em que a mensagem é adicionada à conversa existente do contato

  • 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
labels Não Array de strings com tags a aplicar na conversa criada — ver seção Aplicando tags (labels) abaixo
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",
    "labels": ["campanha-x", "vip"],
    "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.

Aplicando tags (labels) na conversa criada

O parâmetro opcional labels recebe um array de strings com os títulos das tags a aplicar na conversa criada pelo disparo — sem precisar de uma segunda chamada à API de labels.

"labels": ["campanha-x", "vip"]

Comportamento:

  • Os títulos são normalizados: espaços nas pontas removidos, convertidos para minúsculas e deduplicados.

  • As tags são adicionadas à conversa (nunca substituem tags existentes) — em inboxes com conversa única, as tags de disparos anteriores e as aplicadas por agentes são preservadas.

  • Se a tag ainda não existir na conta, ela é criada automaticamente (e passa a aparecer nos filtros do painel) — desde que o token utilizado seja de um administrador. Com token de agente (não-admin), apenas tags já existentes na conta são aplicadas; títulos novos são ignorados silenciosamente.

  • Omitir o parâmetro (ou enviar um array vazio) mantém o comportamento anterior — nenhuma tag é aplicada.

Limite de requisições (rate limit)

Este endpoint aceita no máximo 200 requisições por minuto.

Acima desse limite, a API responde HTTP 429 e a requisição não é processada (a mensagem não é enviada). A resposta inclui os headers:

Header Descrição
Retry-After Segundos até a janela liberar novas requisições
X-RateLimit-Limit Limite de requisições da janela (200)
X-RateLimit-Remaining Requisições restantes na janela atual

Exemplo de resposta ao exceder o limite:

{
  "error": "Rate limit exceeded. Retry later.",
  "retry_after": 42
}

Se a sua integração dispara mensagens em lote, trate o retorno 429 reenviando a requisição após o tempo indicado em Retry-After. Sem esse tratamento, os disparos que excederem o limite serão perdidos.

Observações