O Roberty suporta dois provedores para a integração com o WhatsApp:
- Meta Cloud API (recomendado) — direto com a Meta, sem intermediários.
- Twilio — para quem já usa a infraestrutura da Twilio.
Acesse pelo ícone Configurações → aba Integrações → card WhatsApp.
Habilitar a integração
Ative o toggle no card do WhatsApp. Os campos de configuração ficam visíveis após a ativação.
Ativar o toggle não é suficiente. Enquanto os campos abaixo (Phone Number ID, Access Token, App Secret e Verify Token, no caso da Meta Cloud API) estiverem vazios, a integração aparece como "ativada" mas o webhook da Meta sempre falha na verificação — é a causa mais comum do erro "Não foi possível validar a URL de callback ou o token de verificação" no painel do Meta for Developers. Preencha os 4 campos e espere o indicador de salvamento antes de clicar em Verify and Save na Meta.
Como funciona
- O provedor envia um webhook quando uma mensagem chega.
- O Roberty valida a assinatura (quando disponível) e resolve o agente.
- O agente é executado e a resposta é enviada de volta pela API de saída do provedor.
O endpoint base é:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID>
Use o botão Copiar ID, no topo da aba Integrações, para obter o AGENT_ID.
Provedor
Selecione o provedor de envio de mensagens:
| Provedor | Quando usar |
|---|---|
| Meta Cloud API | Integração direta com o WhatsApp Business via Meta — recomendado para a maioria dos casos |
| Twilio | Quando a sua organização já utiliza o Twilio como provedor de mensageria |
Provedor: Meta Cloud API
Campos de configuração
| Campo | Descrição |
|---|---|
| Phone Number ID | Identificador do número de telefone registrado na Meta |
| Access Token | Permanent access token gerado no Meta Developer Portal |
| App Secret | App secret da aplicação Meta (habilita validação HMAC das requisições) |
| Verify Token | String de verificação — deve ser a mesma configurada no webhook da Meta |
Pré-requisitos
- Uma conta no Meta for Developers.
- Um app do tipo Business com o produto WhatsApp ativado.
- Um número de telefone de teste (ou produção) vinculado ao app.
1. Configurar o agente no Roberty primeiro
Antes de ir para a Meta, preencha os 4 campos aqui no Roberty. Isso evita o erro de handshake, porque a Meta só valida o webhook se o Verify Token já estiver salvo no agente no momento em que você clicar em "Verify and Save" do lado da Meta.
| Campo | Onde encontrar na Meta | Tutorial oficial (link direto para a seção) |
|---|---|---|
| Phone Number ID | Painel do app → WhatsApp → Configuração da API ("API Setup"). Aparece embaixo do número selecionado em "De" ("From"). | Get Started — Step 3. Send and receive messages |
| Access Token (permanente) | Não use o token temporário que aparece na tela de "Configuração da API" (expira em 24h). Gere um permanente: Configurações do Business → Usuários → Usuários do sistema → criar usuário do sistema → Gerar novo token, com permissões whatsapp_business_messaging e whatsapp_business_management, expiração Nunca. Depois, vincule esse usuário à conta do WhatsApp Business em Contas → Contas do WhatsApp → Adicionar pessoas. | Get Started — Step 5. Create a system user and generate a permanent access token |
| App Secret | Painel do app → Configurações do app → Básico ("Settings → Basic") → campo "Chave secreta do app" ("App Secret") → Mostrar (pede confirmação de senha). | App Dashboard — App Secret |
| Verify Token | Não vem da Meta — é uma string que você mesmo escolhe (ex.: gerada com openssl rand -hex 24). Precisa ser idêntica nos dois lados: aqui no Roberty e no campo "Verificar token" do webhook da Meta (próximo passo). | Webhooks — Verification Requests |
Preencha os 4 campos e aguarde o indicador de salvamento do Studio antes de seguir para o próximo passo.
2. Configurar o webhook na Meta
No painel do app, em WhatsApp → Configuration → Webhook:
- Callback URL:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID> - Verify Token: cole exatamente o mesmo valor que você já salvou no campo Verify Token do Roberty no passo anterior.
- Clique em Verify and Save. O Roberty responde ao challenge automaticamente se o Verify Token bater com o que estiver configurado no agente.
Depois, em Webhook fields, assine pelo menos messages.
Validação de segurança
Se App Secret estiver configurado, a Meta envia o header X-Hub-Signature-256: sha256=<hmac> e o Roberty recomputa HMAC-SHA256(appSecret, rawBody) e compara com timingSafeEqual.
Se App Secret estiver em branco, a validação é desativada — não recomendado em produção.
Provedor: Twilio
Campos de configuração
| Campo | Descrição |
|---|---|
| Account SID | Account SID da sua conta Twilio |
| Auth Token | Auth Token da sua conta Twilio |
Pré-requisitos
- Uma conta Twilio com um número de WhatsApp habilitado (Sandbox ou Sender aprovado).
- Número de envio configurado (ex.:
whatsapp:+14155238886).
1. Configurar o webhook na Twilio
No console Twilio, em Messaging → Settings → WhatsApp Senders (ou no Sandbox), configure:
- When a message comes in:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID>(método POST). - Content-Type:
application/x-www-form-urlencoded(padrão da Twilio).
2. Configurar o agente no Roberty
Selecione o provedor Twilio e preencha Account SID e Auth Token.
A versão atual não valida o header X-Twilio-Signature. Recomendamos restringir o endpoint por IP ou usar uma rota dedicada por agente e não expor o AGENT_ID publicamente.
Resolução de problemas
| Sintoma | Causa provável |
|---|---|
| Meta mostra "Não foi possível validar a URL de callback ou o token de verificação", mesmo com o toggle do WhatsApp ativado no Roberty | Os campos Phone Number ID / Access Token / App Secret / Verify Token estão vazios no Roberty — ativar o toggle não preenche nada automaticamente. Preencha os 4 campos (ver tabela acima), espere salvar e só então clique em Verify and Save na Meta. |
| Handshake da Meta falha (mesmo com os campos preenchidos) | verifyToken no agente não bate exatamente com o informado no webhook — cheque espaço ou quebra de linha extra ao colar a string em qualquer um dos dois lados. |
401 Invalid signature (Meta) | appSecret incorreto, ou raw body não preservado. |
| Mensagem chega mas o agente não responde | Provedor configurado errado (ex.: Meta recebendo payload form-encoded da Twilio). |
| Twilio recebe mensagem duplicada | A Twilio reentrega em caso de timeout. |