API - Enviar Mensagem Proativa pelo WhatsApp

Este artigo é a referência rápida do endpoint de WhatsApp. O guia completo, com Widget Web e tags, está em Disparar mensagem proativa por API (WhatsApp e Widget Web).

Descrição

Esse endpoint permite criar uma conversa proativa pelo WhatsApp utilizando um template previamente configurado. Os parâmetros do template são dinâmicos e podem variar dependendo da configuração do template utilizado.

Endpoint

URL:

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

Headers:

• content-type: application/json

• api_access_token: Chave de acesso da API.

Parâmetros

Path Parameter

account_id

• Tipo: String

• Obrigatório: Sim

• Descrição: ID da conta no sistema.

Body Parameters

1. inbox_id

   • Tipo: String

   • Obrigatório: Sim

   • Descrição: ID da inbox para onde a mensagem será enviada.

2. phone_number

   • Tipo: String

   • Obrigatório: Sim

   • Descrição: Número de telefone do destinatário, incluindo o código do país.

3. template_name

   • Tipo: String

   • Obrigatório: Sim

   • Descrição: Nome do template configurado no sistema.

4. Parâmetros Dinâmicos do Template

   • Tipo: Vários

   • Obrigatório: Sim, se o template tiver variáveis (todas são obrigatórias)

   • Descrição: Um campo para cada variável do template, com o nome exato dela (veja abaixo).

5. labels

   • Tipo: Array de strings

   • Obrigatório: Não

   • Descrição: Títulos de tags a aplicar na conversa criada. Detalhes no guia completo.

Sobre os Parâmetros Dinâmicos

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",
  "cliente": "João",
  "valor": "R$ 120,00"
}'

Notas

1. account_id: O account_id pode ser encontrado no painel administrativo da conta.

2. inbox_id: O inbox_id corresponde ao id da caixa de entrada configurada para receber mensagens.

3. api_access_token: Gere o token no painel de configuração de API.
   

4. Parâmetros Dinâmicos do Template: Consulte a configuração do seu template no painel administrativo para identificar as variáveis disponíveis e obrigatórias. Esses parâmetros devem ser enviados diretamente na raiz do payload.

Importante: Certifique-se de que o número de telefone esteja no formato internacional (E.164), incluindo o código do país.

Limite de requisições

Este endpoint 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?.

Campanhas via API

Para disparar para uma lista de contatos, use a criação de campanha da API pública (api.cloudhumans.com), disponível também no MCP da Cloud Humans:

• A audiência é definida por tag: a campanha vai para os contatos com a tag.

• Antes de criar, a API pede a confirmação de quantos contatos vão receber.

• O envio sai pelo agendador de campanhas, em alguns minutos ou no horário agendado.

• A autenticação é por login de usuário (token Bearer), não pela api_access_token deste endpoint.

Referência: Criar uma campanha. O endpoint desta página continua sendo o caminho para o envio um a um; para enviar em volume por ele, respeite o limite de 200 requisições por minuto.