Mensagem Ativa — Evolution

Mensagens ativas permitem enviar mensagens proativas para uma lista de contatos via WhatsApp. Quando usada com a integração Evolution, você pode enviar texto livre, imagens, vídeos, documentos e listas interativas — sem depender de templates aprovados.

Pré-requisitos

Instância Evolution criada e conectada no painel Verboo
assistantID do assistente
integrationID da instância Evolution

Como obter o integrationID

Liste as instâncias Evolution do assistente para encontrar o id da instância desejada:

http

GET /evolution-instance
Authorization: Bearer {token}

json

[
  {
    "id": 456,
    "uuid": "abc123...",
    "assistantID": 123,
    "active": true,
    "tags": ["clientes"]
  }
]

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": 456,
  "integrationType": "EVOLUTION",
  "triggerType": "CRONJOB",
  "triggerData": "0 9 * * 1-5",
  "type": "MULTIPLE_MESSAGES",
  "data": {
    "title": "Campanha de Segunda — Clínicas",
    "contacts": [
      {
        "to": "5585999990001",
        "name": "Ana Souza",
        "clientData": {
          "plano": "premium",
          "origem": "whatsapp"
        }
      },
      {
        "to": "5511988880002",
        "name": "Carlos Lima"
      }
    ],
    "messages": [
      {
        "text": "Olá $nome! Temos uma novidade especial para você hoje.",
        "delay": 0
      },
      {
        "text": "Confira nossa oferta exclusiva 👇",
        "image": "https://cdn.empresa.com/banner.png",
        "delay": 2000
      }
    ],
    "delayBetweenMessages": {
      "minSecs": 30,
      "maxSecs": 90
    },
    "maxMessagesPerDay": 500,
    "webhooks": [
      {
        "url": "https://crm.empresa.com/hooks/mensagem-enviada",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer meu_token"
        },
        "body": "{\"telefone\": \"$phone\", \"nome\": \"$name\"}"
      }
    ]
  }
}

Campos do payload

Raiz

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

`data`

Campo	Tipo	Obrigatório	Descrição
`title`	string	não	Nome interno da campanha
`contacts`	array	sim	Lista de destinatários
`messages`	array	sim	Sequência de mensagens a enviar
`delayBetweenMessages`	object	não	Intervalo aleatório entre contatos
`maxMessagesPerDay`	number	não	Limite diário de envios
`webhooks`	array	não	Chamadas HTTP antes/depois do envio

`contacts[]`

Campo	Tipo	Obrigatório	Descrição
`to`	string	sim	Número de telefone (somente dígitos, código do país obrigatório)
`name`	string	não	Nome do contato (usado em variáveis `$nome`, `$name`)
`clientData`	object	não	Dados extras armazenados na sessão do contato

`messages[]`

Campo	Tipo	Obrigatório	Descrição
`text`	string	não	Texto da mensagem (suporta variáveis)
`textAlternatives`	string[]	não	Alternativas de texto — uma é escolhida aleatoriamente
`image`	string	não	URL de imagem (.jpg, .png, .gif)
`video`	string	não	URL de vídeo (.mp4)
`document`	string	não	URL de documento (.pdf, .docx, etc.)
`list`	object	não	Mensagem de lista interativa (ver abaixo)
`delay`	number	não	Delay em milissegundos antes de enviar esta mensagem

`delayBetweenMessages`

Campo	Tipo	Descrição
`minSecs`	number	Mínimo de segundos entre contatos
`maxSecs`	number	Máximo de segundos entre contatos

Tipos de mensagem

Texto simples

json

{
  "text": "Olá $nome, tudo bem?"
}

Texto com alternativas (A/B)

O sistema escolhe aleatoriamente entre text e textAlternatives:

json

{
  "text": "Olá $nome! Como posso te ajudar hoje?",
  "textAlternatives": [
    "Oi $nome! Em que posso ajudar?",
    "E aí, $nome? Precisa de algo?"
  ]
}

Imagem com legenda

json

{
  "text": "Confira nosso catálogo atualizado!",
  "image": "https://cdn.empresa.com/catalogo-2025.png"
}

Vídeo com legenda

json

{
  "text": "Assista ao tutorial completo:",
  "video": "https://cdn.empresa.com/tutorial.mp4"
}

Documento

json

{
  "text": "Segue a proposta em PDF:",
  "document": "https://cdn.empresa.com/proposta.pdf"
}

Lista interativa

json

{
  "text": "Escolha uma opção:",
  "list": {
    "title": "Menu de Atendimento",
    "description": "Selecione o assunto do seu contato",
    "buttonText": "Ver opções",
    "footerText": "Verboo Atendimento",
    "sections": [
      {
        "title": "Suporte",
        "rows": [
          {
            "rowID": "suporte_tecnico",
            "title": "Suporte Técnico",
            "description": "Problemas com o sistema"
          },
          {
            "rowID": "suporte_financeiro",
            "title": "Financeiro",
            "description": "Boletos e pagamentos"
          }
        ]
      },
      {
        "title": "Vendas",
        "rows": [
          {
            "rowID": "planos",
            "title": "Conhecer Planos",
            "description": "Preços e funcionalidades"
          }
        ]
      }
    ]
  }
}

Variáveis de substituição

Use $variavel em qualquer campo text, textAlternatives, URLs de webhook e body de webhook.

Variáveis de contato

Variável	Descrição
`$nome` / `$name`	Nome completo do contato
`$firstName` / `$first_name` / `$primeiroNome`	Primeiro nome
`$phone`	Número de telefone original
`$phone.treated`	Número formatado (somente dígitos)
`$phone.evolution`	Número no formato JID do Evolution (`5585...@s.whatsapp.net`)

Variáveis de assistente (webhooks)

Variável	Descrição
`$assistant.id`	ID do assistente

ClientData

Qualquer chave enviada em clientData do contato fica disponível como variável:

json

// contacts[].clientData
{ "plano": "premium", "origem": "facebook" }

// No texto
"Seu plano $plano veio de $origem."

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 9 * * 1-5   → toda semana, de seg a sex, às 9h
0 8 * * 1     → toda segunda-feira às 8h
0 14 1 * *    → todo dia 1 do mês às 14h

Webhooks

Execute chamadas HTTP antes ou depois do envio para cada contato.

json

{
  "webhooks": [
    {
      "url": "https://crm.empresa.com/hooks/pre-envio",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer $token_crm",
        "Content-Type": "application/json"
      },
      "body": "{\"telefone\": \"$phone\", \"nome\": \"$nome\", \"assistente\": \"$assistant.id\"}"
    }
  ]
}

Os webhooks são disparados antes do envio de mensagens para cada contato. Até 5 webhooks são executados em paralelo.

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

Logs de execução

Após concluída, a task contém logs por contato:

json

[
  {
    "created_at": "2025-03-10T09:00:05Z",
    "success": true,
    "composing_times_secs": [1200, 2400]
  },
  {
    "created_at": "2025-03-10T09:01:12Z",
    "success": false,
    "error": "contact not registered on WhatsApp"
  }
]

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