Principal APIs API: Enviar Mensagem Proativa pelo WhatsApp

API: Enviar Mensagem Proativa pelo WhatsApp

Última atualização em Oct 21, 2025

Comportamento de criação do ticket via API

  • A mensagem não nasce assignada, pois o sistema não sabe qual agente deve receber. Por esse motivo, ao invés do balão ser laranja, ele aparece verde, a cor verde representa mensagens "robóticas" de automação dentro do próprio Cloud Chat.

  • 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 para o ticket mais recente.

API: Enviar Mensagem Proativa pelo WhatsApp

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

Body Parameters

inbox_id(String/Obrigatório): ID da inbox por onde a mensagem será enviada.
phone_number(String/Obrigatório): Número de telefone do destinatário.
template_name(String/Obrigatório): Nome do template configurado no sistema.
header_attachment(String/Opcional): URL do anexo a ser enviado, caso a template suporte um anexo em seu cabeçalho.
button_param_#(String/Opcional): Variáveis de botões presentes no template. Devem ser enviados tantos quantos forem necessários (substituir # pelo índice ordenado do botão de 0 a N).
Parâmetros dinâmicos do template(String/Opcional): Variáveis específicas do template que serão substituídas no envio.

Sobre os Parâmetros Dinâmicos

Os templates configurados podem conter variáveis dinâmicas que são substituídas no momento do envio.

Essas variáveis devem ser enviadas diretamente no corpo da requisição, ao lado de outros campos obrigatórios, como inbox_id, phone_number, e template_name.

  • Exemplo de Variáveis no Template: Um template pode incluir variáveis como {{contact.name}}, {{contact.email}}, ou valores estáticos como "Fulaninho".

  • Formato no Payload: Envie essas variáveis diretamente na raiz do JSON, substituindo os valores de acordo com as informações desejadas.

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": "PHONE_NUMBER",
  "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"
}'

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.

Guias de integrações