Mensagem Ativa — WhatsApp Oficial

Mensagens ativas com WhatsApp Oficial (Meta Business API) permitem enviar mensagens proativas usando templates pré-aprovados pela Meta. É a opção recomendada para empresas que precisam de conformidade total com os termos do WhatsApp.

Diferença em relação à Evolution

	WhatsApp Oficial	Evolution
Tipo de mensagem	Somente templates aprovados pela Meta	Texto livre, mídia e listas
Aprovação	Template deve ser aprovado pela Meta antes	Não requer aprovação
Conformidade	Totalmente dentro dos termos do WhatsApp	Uso não oficial da API
Variáveis	Parâmetros indexados no template (`{{1}}`, `{{2}}`)	Variáveis livres (`$nome`, `$plano`)

Pré-requisitos

Conta no Meta Business Manager com WhatsApp Business API habilitada
Instância WhatsApp criada no painel Verboo com:
- MetaAccessToken — token de acesso da Meta
- PhoneNumberID — ID do número de telefone no Meta
- MetaBusinessID — ID da conta de negócios
Template criado e aprovado no Meta Business Manager
assistantID do assistente
integrationID da instância WhatsApp

Como obter o integrationID

Liste as instâncias WhatsApp do assistente para encontrar o id da instância desejada. O campo phoneNumber ajuda a identificar qual número usar:

http

GET /whatsapp-instance
Authorization: Bearer {token}

json

[
  {
    "id": 789,
    "uuid": "xyz456...",
    "assistantID": 123,
    "phoneNumber": "+55 85 99999-0001",
    "active": true
  }
]

Use o campo id como integrationID no payload da task.

Criar uma task

http

POST /assistant/{assistant_id}/task
Content-Type: application/json
Authorization: Bearer {token}

Payload completo

json

{
  "integrationID": 789,
  "integrationType": "WHATSAPP",
  "triggerType": "CRONJOB",
  "triggerData": "0 10 * * 1",
  "type": "TEMPLATE_MESSAGES",
  "data": {
    "title": "Lembrete de Consulta — Segunda",
    "template": {
      "name": "lembrete_consulta",
      "language": {
        "code": "pt_BR"
      }
    },
    "contacts": [
      {
        "to": "5585999990001",
        "name": "Ana Souza",
        "header": {
          "params": [
            {
              "key": "nome_clinica",
              "text": "Bioclínica"
            }
          ]
        },
        "body": {
          "params": [
            {
              "key": "nome_paciente",
              "text": "Ana"
            },
            {
              "key": "data_consulta",
              "text": "12/03/2025 às 14h"
            },
            {
              "key": "especialidade",
              "text": "Cardiologia"
            }
          ]
        },
        "clientData": {
          "paciente_id": "pac_001"
        }
      }
    ],
    "webhooks": [
      {
        "url": "https://sistema.clinica.com/hooks/lembrete-enviado",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer token_clinica"
        },
        "body": "{\"paciente_id\": \"$paciente_id\", \"telefone\": \"$phone\"}"
      }
    ]
  }
}

Campos do payload

Raiz

Campo	Tipo	Obrigatório	Descrição
`integrationID`	number	sim	ID da instância WhatsApp
`integrationType`	string	sim	Sempre `"WHATSAPP"`
`triggerType`	string	sim	Sempre `"CRONJOB"`
`triggerData`	string	sim	Expressão cron (TZ: America/Sao_Paulo)
`type`	string	sim	Sempre `"TEMPLATE_MESSAGES"`
`data`	object	sim	Configuração da campanha

`data`

Campo	Tipo	Obrigatório	Descrição
`title`	string	não	Nome interno da campanha
`template`	object	sim	Template a ser usado
`contacts`	array	sim	Lista de destinatários
`webhooks`	array	não	Chamadas HTTP antes/depois do envio

`data.template`

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome do template no Meta Business Manager
`language.code`	string	sim	Código do idioma (ex: `pt_BR`, `en_US`)

`contacts[]`

Campo	Tipo	Obrigatório	Descrição
`to`	string	sim	Número de telefone (somente dígitos, com código do país)
`name`	string	não	Nome do contato
`header`	object	não	Parâmetros do cabeçalho do template
`body`	object	não	Parâmetros do corpo do template
`clientData`	object	não	Dados extras armazenados na sessão

`header` e `body`

Cada um contém uma lista de params:

json

{
  "params": [
    { "key": "nome_variavel", "text": "valor" }
  ]
}

Para header com imagem:

json

{
  "params": [
    {
      "key": "imagem_header",
      "image": {
        "link": "https://cdn.empresa.com/banner.png"
      }
    }
  ]
}

Como funciona o mapeamento de parâmetros

O template no Meta define variáveis por posição: {{1}}, {{2}}, {{3}}. No payload Verboo, você nomeia cada parâmetro com uma key descritiva — o sistema substitui na ordem em que os parâmetros aparecem.

Exemplo de template aprovado na Meta:

Olá {{1}}, sua consulta de {{2}} está confirmada para {{3}}.

Payload de body:

json

{
  "params": [
    { "key": "nome_paciente", "text": "Ana" },
    { "key": "especialidade", "text": "Cardiologia" },
    { "key": "data_consulta", "text": "12/03/2025 às 14h" }
  ]
}

Resultado enviado:

Olá Ana, sua consulta de Cardiologia está confirmada para 12/03/2025 às 14h.

Exemplos de casos de uso

Lembrete de consulta com imagem no header

json

{
  "data": {
    "template": {
      "name": "lembrete_consulta_v2",
      "language": { "code": "pt_BR" }
    },
    "contacts": [
      {
        "to": "5585999990001",
        "name": "João Silva",
        "header": {
          "params": [
            {
              "key": "imagem_clinica",
              "image": {
                "link": "https://cdn.clinica.com/logo-banner.png"
              }
            }
          ]
        },
        "body": {
          "params": [
            { "key": "nome", "text": "João" },
            { "key": "data", "text": "Terça, 13/03 às 10h" },
            { "key": "medico", "text": "Dr. Carlos Andrade" }
          ]
        }
      }
    ]
  }
}

Cobrança de inadimplência

json

{
  "data": {
    "template": {
      "name": "cobranca_amigavel",
      "language": { "code": "pt_BR" }
    },
    "contacts": [
      {
        "to": "5511988880002",
        "name": "Maria Costa",
        "body": {
          "params": [
            { "key": "nome", "text": "Maria" },
            { "key": "valor", "text": "R$ 299,90" },
            { "key": "vencimento", "text": "15/03/2025" },
            { "key": "link_pagamento", "text": "https://pagar.empresa.com/fatura123" }
          ]
        }
      }
    ]
  }
}

Formato do número de telefone

O número deve ser enviado somente com dígitos, incluindo o código do país:

Formato	Exemplo
Brasil (55) + DDD + número	`5585999990001`
Com 9 dígito (celular SP 11)	`5511991234567`

Não envie +, (, ), - ou espaços.

Expressão cron

O campo triggerData aceita expressão cron padrão (5 campos). O sistema executa na timezone America/Sao_Paulo.

┌─────────── minuto (0-59)
│ ┌───────── hora (0-23)
│ │ ┌─────── dia do mês (1-31)
│ │ │ ┌───── mês (1-12)
│ │ │ │ ┌─── dia da semana (0=dom, 1=seg ... 6=sáb)
│ │ │ │ │
0 10 * * 1    → toda segunda-feira às 10h
0 8  * * 1-5  → dias úteis às 8h
0 9  1 * *    → todo dia 1 do mês às 9h

Webhooks

Execute chamadas HTTP antes do envio para cada contato. Suporta as mesmas variáveis de contato ($phone, $name, $phone.treated), além das chaves de clientData.

json

{
  "webhooks": [
    {
      "url": "https://sistema.empresa.com/hooks/envio",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer token"
      },
      "body": "{\"telefone\": \"$phone\", \"paciente_id\": \"$paciente_id\"}"
    }
  ]
}

Ciclo de vida da task

WAITING → IN_PROGRESS → DONE
                      ↘ ERROR

Status	Descrição
`waiting`	Aguardando a janela de execução do cron
`in_progress`	Processando — mensagens sendo enviadas
`done`	Todos os contatos processados com sucesso
`error`	Falha durante a execução

Restrições da API Oficial

Somente templates previamente aprovados pela Meta podem ser enviados
Templates são revisados e aprovados em até 24h pelo Meta Business Manager
Evite usar linguagem promocional excessiva nos templates — pode resultar em rejeição
O número de telefone remetente deve estar vinculado a uma conta Business verificada
Para cada contato, os parâmetros devem ser fornecidos na ordem correta do template

Endpoints da API

Método	Rota	Descrição
`POST`	`/assistant/{id}/task`	Criar task
`GET`	`/assistant/{id}/task`	Listar tasks
`GET`	`/assistant/{id}/task/{task_id}`	Buscar task
`PUT`	`/assistant/{id}/task/{task_id}`	Atualizar task
`DELETE`	`/assistant/{id}/task/{task_id}`	Remover task