Principal API e integrações | Chaves, endpoints e webhooks Como enviar mensagem proativa pelo WhatsApp via API

Como enviar mensagem proativa pelo WhatsApp via API

Última atualização em Sep 23, 2026

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

  • 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 Sim, se o template tiver variáveis Um campo para cada variável, com o nome exato dela, na raiz do JSON (ver abaixo)

Sobre as variáveis dinâmicas

Cada variável do template vira um campo na raiz do JSON, ao lado de inbox_id, phone_number e template_name, com o nome exato da variável:

  • Template com variáveis nomeadas, como Olá {{cliente}}, seu boleto de {{valor}} vence amanhã: envie os campos "cliente" e "valor".

  • Template com variáveis numeradas, como Olá {{1}}, seu boleto de {{2}} vence amanhã: envie os campos "1" e "2".

Se faltar alguma variável, a API recusa a requisição com o erro missing params. Campos que não correspondem a nenhuma variável são ignorados. Nomes de variável com ponto ou acento (como {{contact.name}} ou {{horário}}) não são aceitos pela Meta como variável.

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": "lembrete_pagamento",
    "labels": ["campanha-x", "vip"],
    "header_attachment": "ATTACHMENT_URL",
    "button_param_0": "BUTTON PARAMETER",
    "button_param_1": "ANOTHER BUTTON PARAMETER",
    "cliente": "João",
    "valor": "R$ 120,00"
  }'

Onde encontrar os parâmetros

  • account_id — no painel administrativo da conta

  • inbox_id — ID da caixa de entrada configurada (https://{SEU_DOMINIO}/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 ou CX Engineer. 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