Rotas da API

Base URL

https://producer-whatsapp-trigger.incibrasil.workers.dev

Autenticação

Todas as requisições devem incluir a API key como parâmetro na URL:

?api_key=<INCI_API_KEY>

Exemplo:

https://producer-whatsapp-trigger.incibrasil.workers.dev?api_key=<INCI_API_KEY>

Segurança

• Mantenha a API key em segredo (variáveis de ambiente)
• Nunca compartilhe a chave em repositórios públicos
• Substitua <INCI_API_KEY> pela chave real fornecida pela equipe

---

1. Envio de Mensagem Única

POST /

Envia mensagem para um único contato.

Request Body

{
  "phone_number": "5588981397730",
  "name": "João Edson",
  "inbox_id": "123",
  "template_name": "saudacao_inicial",
  "template_language": "pt_BR",
  "template_category": "UTILITY",
  "variables": ["João Edson", "10:00"]
}

Campos

Campo	Tipo	Obrigatório	Descrição
phone_number	string	Sim	Número com código do país (apenas dígitos)
name	string	Sim	Nome do contato
inbox_id	string	Sim	ID do inbox no Chatwoot
template_name	string	Sim	Nome do template aprovado
template_language	string	Sim	Idioma (ex: pt_BR, en_US)
template_category	string	Sim	Categoria (UTILITY, MARKETING, etc.)
variables	array	Não	Variáveis do template (ordem importa)
contact_id	string	Não	ID do contato no Chatwoot (opcional)
source_id	string	Não	Source ID do contato (opcional)

Response (Sucesso)

{
  "success": true,
  "message": "Mensagem enfileirada com sucesso",
  "data": {
    "message_id": "uuid-aqui"
  }
}

---

2. Envio em Lote (Batch)

POST /

Envia mesma mensagem (template) para múltiplos contatos com variáveis diferentes.

Request Body

{
  "inbox_id": "123",
  "template_name": "saudacao_inicial",
  "template_language": "pt_BR",
  "template_category": "UTILITY",
  "contacts": [
    {
      "phone_number": "5588981397730",
      "name": "João Edson",
      "variables": ["João Edson", "pedido #123"]
    },
    {
      "phone_number": "5511999887766",
      "name": "Maria Silva",
      "variables": ["Maria Silva", "pedido #456"]
    }
  ]
}

Campos

• Nível batch: inbox_id, template_name, template_language, template_category
• Nível contact: phone_number, name, variables, contact_id (opcional), source_id (opcional)

Response (Sucesso)

{
  "success": true,
  "message": "Todos os 2 contatos foram validados e enfileirados com sucesso",
  "data": {
    "total": 2,
    "template": "saudacao_inicial"
  }
}

Response (Lista Grande - Chunks)

Se a lista tiver mais de 10 contatos, será dividida em chunks:

{
  "success": true,
  "message": "Lista de 150 contatos dividida em 15 chunks e enfileirada com sucesso",
  "data": {
    "total": 150,
    "chunks": 15,
    "chunkSize": 10,
    "template": "saudacao_inicial"
  }
}

---

3. Envio de Array

POST /

Envia lista de objetos completos (cada contato pode ter template diferente).

Request Body

[
  {
    "phone_number": "5588981397730",
    "name": "João Edson",
    "inbox_id": "123",
    "template_name": "template_a",
    "template_language": "pt_BR",
    "template_category": "UTILITY",
    "variables": ["variavel1", "variavel2"]
  },
  {
    "phone_number": "5511999887766",
    "name": "Maria Silva",
    "inbox_id": "123",
    "template_name": "template_b",
    "template_language": "pt_BR",
    "template_category": "MARKETING",
    "variables": ["outra_var"]
  }
]

Response (Sucesso)

{
  "success": true,
  "message": "Todos os 2 contatos foram validados e enfileirados com sucesso",
  "data": {
    "total": 2
  }
}

---

4. Integração com Brevo

POST /brevo/{template_name}/{inbox_id}/{variables}

Rota especial para webhooks do Brevo com parâmetros dinâmicos na URL. Esta rota permite que automações da Brevo disparem mensagens do WhatsApp usando as propriedades dos contatos.

Como Configurar na Brevo

Para ativar esta integração na Brevo:

1. Acesse sua automação (workflow) na Brevo
2. Adicione uma ação do tipo Webhook
3. Configure a URL com os parâmetros desejados (exemplos abaixo)
4. ⚠️ IMPORTANTE: Marque o checkbox "Quero enviar as propriedades do contato para o webhook"
5. Salve a automação

Propriedades do Contato

As propriedades enviadas pela Brevo vêm do trackEvent da API Brevo, que permite rastrear eventos personalizados com dados associados aos contatos.

URL Structure

Exemplo 1: Template sem variáveis

Para templates que não possuem variáveis dinâmicas:

https://producer-whatsapp-trigger.incibrasil.workers.dev/brevo/boas_vindas/123/

• boas_vindas = nome do template
• 123 = inbox_id do Chatwoot
• Sem parâmetros de variáveis (template estático)

Exemplo 2: Extraindo propriedades dinâmicas

Para templates com variáveis preenchidas pelas propriedades do contato:

https://producer-whatsapp-trigger.incibrasil.workers.dev/brevo/confirmacao_pedido/123/props:properties.nome&props:properties.numero_pedido

• confirmacao_pedido = nome do template
• 123 = inbox_id
• props:properties.nome = extrai o campo nome de properties
• props:properties.numero_pedido = extrai o campo numero_pedido

Exemplo 3: Combinando valores fixos e dinâmicos

Para templates com valores fixos (literais) + dinâmicos:

https://producer-whatsapp-trigger.incibrasil.workers.dev/brevo/novo_produto/123/Smartwatch%20Pro&props:properties.nome

• novo_produto = nome do template
• 123 = inbox_id
• Smartwatch%20Pro = valor fixo (literal) - nome do produto que não muda
• props:properties.nome = valor dinâmico extraído das propriedades

Espaços na URL

Use %20 para representar espaços em valores literais (ex: Smartwatch%20Pro = "Smartwatch Pro")

Parâmetros da URL

• {template_name}: Nome do template aprovado no WhatsApp (ex: saudacao_inicial)
• {inbox_id}: ID do inbox do Chatwoot
• {variables}: Variáveis separadas por & (deixe vazio se o template não tiver variáveis)
  • props:caminho.do.campo - Extrai valor do body JSON enviado pela Brevo
  • texto_literal - Usa valor fixo/literal na mensagem
  • Suporta navegação aninhada: props:properties.endereco.cidade

Request Body (Enviado pela Brevo)

Exemplo do payload enviado pela Brevo quando o webhook é acionado:

{
  "email": "joao@example.com",
  "event": "cart_updated",
  "eventdata": {
    "data": {
      "added_product": [
        {
          "currency": "EUR",
          "name": "Wrist watch",
          "type": "accessories",
          "price": "50.00"
        }
      ]
    }
  },
  "properties": {
    "nome": "João Edson",
    "numero_pedido": "#12345",
    "whatsapp": "5588981397730"
  }
}

Estrutura do Payload

O campo properties contém os dados personalizados enviados via trackEvent da API Brevo. Use props:properties.campo para acessar esses valores.

Como Funciona

Exemplo com URL:

/brevo/confirmacao_pedido/123/props:properties.nome&props:properties.numero_pedido&Entrega%20Expressa

Processamento:

1. Worker extrai nome de properties.nome → "João Edson"
2. Worker extrai numero_pedido de properties.numero_pedido → "#12345"
3. Worker usa o valor literal → "Entrega Expressa"
4. Template final: "Olá João Edson, seu pedido #12345 será enviado via Entrega Expressa"

Response (Sucesso)

{
  "success": true,
  "message": "Mensagem enfileirada com sucesso",
  "data": {
    "message_id": "uuid-aqui"
  }
}

---

5. Listar Templates

GET /templates?inbox_id={id}

Retorna templates disponíveis para um inbox específico.

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
inbox_id	string	Sim	ID do inbox no Chatwoot

Response (Sucesso)

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "1234567890",
        "name": "saudacao_inicial",
        "status": "APPROVED",
        "category": "UTILITY",
        "language": "pt_BR",
        "components": [
          {
            "type": "BODY",
            "text": "Olá {{1}}, seu pedido {{2}} está pronto!"
          }
        ],
        "parameter_format": "{{1}}"
      }
    ]
  }
}

---

Erros Comuns

400 - Bad Request

{
  "success": false,
  "message": "Campo obrigatório ausente: phone_number"
}

Causas comuns:

• Campos obrigatórios faltando
• Número de telefone inválido (deve conter apenas dígitos)
• Template não encontrado
• Número de variáveis incorreto

400 - Validação em Lote

{
  "success": false,
  "message": "Encontrados 3 erros de validação. Nenhum contato foi processado.",
  "data": {
    "errors": [
      {
        "index": 0,
        "phone_number": "5588981397730",
        "error": "O template requer 2 variáveis, mas apenas 1 foi fornecida"
      },
      {
        "index": 5,
        "phone_number": "ausente",
        "error": "Número de telefone obrigatório"
      }
    ]
  }
}

Importante

Em modo batch/array, se qualquer contato falhar na validação, nenhum contato é processado (comportamento "tudo ou nada").

500 - Internal Server Error

{
  "success": false,
  "message": "Erro ao processar requisição: <detalhes>"
}

---

CORS

Todas as rotas retornam headers CORS permissivos:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

---

Próximos Passos

• Veja Exemplos de Uso práticos
• Entenda o Schema do Banco de Dados