WhatsApp

1. Visão Geral

O WhatsApp é representado por três componentes distintos na plataforma, todos usando a API WhatsApp Cloud (Meta):

• whatsapp — envia mensagens (texto, template, mídia, localização ou contato).
• whatsapp-in — recebe mensagens via webhook (gatilho de entrada).
• whatsapp-upload-media — envia um arquivo de mídia para os servidores da Meta, retornando um ID que pode ser usado depois no envio de mensagens de mídia.

Use whatsapp para notificar clientes, whatsapp-in para reagir a mensagens recebidas, e whatsapp-upload-media quando for enviar o mesmo arquivo de mídia várias vezes (evitando reenviar o arquivo em cada mensagem).

⚠️ CONFIRMAR: no código-fonte atual, o componente registrado com o nome whatsapp-in carrega, na prática, a mesma implementação do componente whatsapp (envio), não a lógica de recebimento via webhook. Antes de usar whatsapp-in como gatilho de entrada, vale confirmar com o time responsável se esse comportamento já foi corrigido, pois como documentado no código-fonte parece ser um erro de registro do componente.

2. Pré-requisitos

• Uma conta WhatsApp Business configurada na plataforma da Meta (Cloud API).
• Um número de telefone registrado (phoneNumberId).
• Um token de acesso (accessToken) da API WhatsApp Cloud.

3. Autenticação e Conexão

Campo	Obrigatório	Tipo	Descrição	Exemplo
phoneNumberId	Sim	Texto	ID do número de telefone WhatsApp Business.	"123456789012345"
accessToken	Sim	Texto	Token de acesso da API WhatsApp Cloud.	Um token da Meta
apiVersion	Não	Texto	Versão da Graph API usada. Valor padrão: "v21.0".	"v21.0"
alternativeUri	Não	Texto	URI alternativa/base customizada da API (para testes ou proxies).	—

4. Configuração / Operações Suportadas

whatsapp — enviar mensagem

Campo	Obrigatório	Tipo	Descrição	Exemplo
messageType	Sim	Texto: TEXT, TEMPLATE, MEDIA, LOCATION, CONTACT	Tipo de mensagem a enviar.	"TEXT"
phoneNumberRecipient	Sim	Texto	Número de telefone do destinatário.	"5511999998888"

TEXT: message (obrigatório) — o texto a enviar.

TEMPLATE: templateName (obrigatório), language (opcional, padrão "en_US"), components (opcional, JSON com os parâmetros do template).

MEDIA: mediaType (obrigatório), caption (opcional), e exatamente um entre link (URL pública da mídia) ou wppId (ID de uma mídia já enviada via whatsapp-upload-media); fileName (obrigatório se mediaType for documento).

LOCATION: locationName, locationAddress, latitude, longitude (todos obrigatórios).

CONTACT: contacts (obrigatório, JSON com os dados de um ou mais contatos: nome, telefones, e-mails, endereços).

whatsapp-upload-media — enviar um arquivo de mídia

Campo	Obrigatório	Tipo	Descrição	Exemplo
fileName	Sim	Texto	Nome da propriedade da mensagem onde está o arquivo a enviar.	"comprovante"
contentType	Sim	Texto	Tipo MIME do arquivo.	"application/pdf"

5. Exemplos Práticos

Exemplo simples: enviar uma mensagem de texto simples.

Entrada:

{
  "cliente": { "telefone": "5511999998888" }
}

Configuração do componente:

{
  "componentName": "whatsapp",
  "configurations": {
    "phoneNumberId": "123456789012345",
    "accessToken": "{$.secrets.whatsappToken}",
    "messageType": "TEXT",
    "phoneNumberRecipient": "{$.body.cliente.telefone}",
    "message": "Seu pedido foi confirmado!"
  }
}

Resposta:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999998888", "wa_id": "5511999998888" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

Exemplo avançado: enviar um documento em PDF já anexado à mensagem, usando um template com parâmetros.

Entrada:

{
  "cliente": { "telefone": "5511999998888", "nome": "Maria Silva" }
}

Configuração do componente:

{
  "componentName": "whatsapp",
  "configurations": {
    "phoneNumberId": "123456789012345",
    "accessToken": "{$.secrets.whatsappToken}",
    "messageType": "TEMPLATE",
    "phoneNumberRecipient": "{$.body.cliente.telefone}",
    "templateName": "confirmacao_pedido",
    "language": "pt_BR",
    "components": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"{$.body.cliente.nome}\"}]}]"
  }
}

Resposta:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999998888", "wa_id": "5511999998888" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"Phone number ID is empty." / "Phone number recipient is empty." / "Access token is empty."	Campos básicos de conexão/destinatário não preenchidos.	Preencher phoneNumberId, phoneNumberRecipient e accessToken.
"Message is null"	Tipo TEXT usado sem preencher message.	Preencher message.
"Template name is null"	Tipo TEMPLATE usado sem preencher templateName.	Preencher templateName.
"Whatsapp ID or Link must be informed."	Tipo MEDIA usado sem link nem wppId (ou com os dois ao mesmo tempo).	Preencher exatamente um dos dois campos.
"Message Type [valor] not found"	O campo messageType não corresponde a nenhum tipo suportado.	Usar TEXT, TEMPLATE, MEDIA, LOCATION ou CONTACT.
Corpo de resposta contém {"error": "..."} mesmo com o fluxo continuando normalmente	A API do WhatsApp retornou um erro (token inválido, número não autorizado, limite de mensagens), mas o componente não interrompe o fluxo nesse caso.	Verificar o conteúdo de error na resposta e tratar esse caso explicitamente no fluxo (por exemplo, com um Choice).