WhatsApp Business

ACTIVEVersão 1.0.0Meta

Envie mensagens pela WhatsApp Business Cloud API (Meta) a partir dos seus processos.

Ver como JSON

Pré-requisitos

• um app no Meta for Developers com WhatsApp Cloud API ativo;
• um número de telefone comercial verificado;
• permissão no iBPMS para criar ou selecionar conexões;
• um token de acesso válido.

whatsapp.json

{
  "schemaVersion": 1,
  "key": "whatsapp",
  "name": "WhatsApp Business",
  "description": "Envie mensagens pela WhatsApp Business Cloud API (Meta) a partir dos seus processos.",
  "category": "communication",
  "vendor": "Meta",
  "version": "1.0.0",
  "status": "ACTIVE",
  "credentials": [
    {
      "type": "BEARER_TOKEN",
      "secretLabel": "Token de acesso",
      "secretPlaceholder": "EAAG...",
      "helpText": "Pegue o token de acesso do seu app no painel do WhatsApp Cloud API (Meta for Developers).",
      "helpUrl": "https://developers.facebook.com/apps"
    }
  ],
  "actions": [
    {
      "key": "message.send",
      "name": "Enviar mensagem de texto",
      "description": "Envia uma mensagem de texto para um número via WhatsApp Business Cloud API.",
      "inputs": [
        {
          "key": "phoneNumberId",
          "label": "ID do número (Phone Number ID)",
          "type": "TEXT",
          "required": true,
          "description": "ID do número da WhatsApp Business (Meta) que envia a mensagem."
        },
        {
          "key": "to",
          "label": "Destinatário",
          "type": "TEXT",
          "required": true,
          "description": "Número no formato internacional, ex.: 5511999998888."
        },
        {
          "key": "message",
          "label": "Mensagem",
          "type": "TEXT",
          "required": true,
          "description": "Aceita expressões do processo, ex.: {{ process.protocol }}."
        }
      ],
      "outputs": [
        {
          "key": "messages",
          "label": "Messages",
          "type": "OUTPUT",
          "required": false
        },
        {
          "key": "contacts",
          "label": "Contacts",
          "type": "OUTPUT",
          "required": false
        }
      ]
    }
  ],
  "triggers": [
    {
      "key": "message.received",
      "name": "Mensagem recebida",
      "description": "Dispara quando chega uma mensagem no número da WhatsApp Business. Inscrição MANUAL: no painel da Meta (WhatsApp → Configuration), cole a URL de callback e use o verify token exibido no nó.",
      "mode": "PUSH",
      "exclusiveByConnection": true,
      "inputs": [],
      "events": [
        {
          "type": "MESSAGE_STATUS_CHANGED"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "TEXT"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "IMAGE"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "AUDIO"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "VIDEO"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "DOCUMENT"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "LOCATION"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "OTHER"
        }
      ]
    }
  ]
}

Obtendo o token de acesso

1. Abra seu app no painel do Meta for Developers.
2. Vá até a seção do WhatsApp Cloud API.
3. Copie o token de acesso e cole no campo de credencial do iBPMS.

Proteja a credencial

Guarde o segredo apenas no campo de credencial do iBPMS. Não o coloque em regras, Markdown, capturas de tela ou logs.

Credenciais

Credencial

Token de acesso

BEARER_TOKEN

Pegue o token de acesso do seu app no painel do WhatsApp Cloud API (Meta for Developers).

Campo	Formato esperado
Token de acesso	EAAG...

Abrir guia do provedor

Ações disponíveis

Ação

Enviar mensagem de texto

message.send

Envia uma mensagem de texto para um número via WhatsApp Business Cloud API.

Entradas

Campo	Tipo	Obrigatório	Descrição
phoneNumberIdID do número (Phone Number ID)	TEXT	Sim	ID do número da WhatsApp Business (Meta) que envia a mensagem.
toDestinatário	TEXT	Sim	Número no formato internacional, ex.: 5511999998888.
messageMensagem	TEXT	Sim	Aceita expressões do processo, ex.: {{ process.protocol }}.

Saídas

Campo	Tipo	Obrigatório	Descrição
messagesMessages	OUTPUT	Não	—
contactsContacts	OUTPUT	Não	—

Chamada

{
  "connection": "whatsapp-producao",
  "operation": "message.send",
  "inputs": {
    "phoneNumberId": "+5511999999999",
    "to": "{{ context.to }}",
    "message": "{{ context.message }}"
  }
}

Resposta

{
  "messages": "…",
  "contacts": "…"
}

Triggers disponíveis

Trigger

Mensagem recebida

PUSHConexão exclusiva

Dispara quando chega uma mensagem no número da WhatsApp Business. Inscrição MANUAL: no painel da Meta (WhatsApp → Configuration), cole a URL de callback e use o verify token exibido no nó.

Configuração

Este trigger não exige configuração adicional.

Eventos normalizados

• MESSAGE_STATUS_CHANGED
• MESSAGE_RECEIVED · TEXT
• MESSAGE_RECEIVED · IMAGE
• MESSAGE_RECEIVED · AUDIO
• MESSAGE_RECEIVED · VIDEO
• MESSAGE_RECEIVED · DOCUMENT
• MESSAGE_RECEIVED · LOCATION
• MESSAGE_RECEIVED · OTHER

Evento recebido

{
  "event": "MESSAGE_STATUS_CHANGED",
  "data": {
    "chave": "valor"
  }
}

Limitações

• o trigger de mensagem recebida é exclusivo por conexão;
• tokens temporários do painel expiram: para produção, use um token de longa duração;
• mensagens iniciadas pela empresa fora da janela de atendimento exigem template aprovado pela Meta;
• as políticas e os limites de envio da Meta continuam se aplicando.

Erros comuns

Sintoma	Possível causa	Correção
Token expirado	Uso de token temporário do painel	Gere um token de longa duração e atualize a credencial.
Mensagem não entregue	Fora da janela de 24h sem template	Use um template aprovado para iniciar a conversa.
Número inválido	Destinatário sem código do país	Envie o número no formato internacional.

Veja também

• Todos os conectores
• Integrações
• Solução de problemas