Pré-requisitos
Antes de criar uma conexão, você precisará do seguinte da Meta:| Requisito | Onde Obter |
|---|---|
| Conta do WhatsApp Business (verificada) | Meta Business Manager |
| Token de Acesso de Usuário do Sistema | Meta Business Manager → System Users |
| ID do Número de Telefone | WhatsApp Manager → Phone Numbers |
| ID da Conta Comercial | Opcional — necessário para chamadas avançadas da Graph API |
| Templates de mensagem aprovados | Meta Business Manager → Account Tools → Message Templates |
Criando uma Conexão
O Toolkit WhatsApp está disponível tanto no Agent Builder quanto no Workflow Builder. A configuração da conexão é a mesma em ambos, mas o caminho de navegação difere.- Agent Toolkit
- Workflow Toolkit
- Abra seu agente no Agent Builder
- Vá até a aba Toolkits na barra lateral esquerda
- Encontre WhatsApp e clique em Add to Agent
- No painel do toolkit, clique em Select a Connection > Create a Connection
- Na janela pop-up que aparecer, insira um Connection Name, seu System User Access Token, Business Account ID.
- Insira seu Access Token, Business Account ID (opcional) e um Name de exibição para a conexão
- Clique em Save — a EKB validará as credenciais antes de salvar
Ferramentas Disponíveis
| Ferramenta | Descrição |
|---|---|
| Send Message | Envie uma mensagem de texto simples (até 4.096 caracteres, UTF-8) dentro da janela de sessão de 24 horas |
| Send Media | Envie uma imagem, vídeo, áudio ou documento via uma URL HTTPS pública, com legenda ou nome de arquivo opcional |
| Send Template | Envie uma mensagem de template pré-aprovada — necessária para mensagens de saída fora da janela de sessão de 24 horas |
| Custom API Call | Faça uma chamada direta para qualquer endpoint da Meta Graph API para casos de uso avançados (veja abaixo) |
Custom API Call
A ferramenta Custom API Call é a opção mais extensível. Ela permite acesso direto a endpoints da WhatsApp Graph API além do que as outras ferramentas cobrem, incluindo:- Mensagens interativas (botões, listas)
- Cartões de localização e contato
- Mensagens de catálogo de produtos
- Gerenciamento programático de templates
- Atualizações de perfil comercial
- Análises e insights de mensagens
Notas de Configuração
- Formato do número de telefone: Sempre use o formato internacional E.164 (por exemplo,
+1...,+52...). Espaços, traços ou um código de país ausente causarão falhas na entrega (erro1006). - Janela de sessão: Mensagens de texto simples e mídia só podem ser enviadas dentro de uma janela de 24 horas da última mensagem do destinatário. Fora dessa janela, use um Send Template em vez disso.
- URLs de mídia: Devem ser acessíveis publicamente via HTTPS. URLs privadas, localhost ou expiradas causarão falhas de download (erro
1011). Verifique se os tipos MIME correspondem ao conteúdo do arquivo. - Templates: Devem ser aprovados no Meta Business Manager antes do uso. A contagem e a ordem dos parâmetros devem corresponder exatamente ao template aprovado. Monitore a classificação de qualidade do seu template — uma classificação baixa pode resultar na pausa de um template (erro
131056). - Limites de taxa: A WhatsApp Business API impõe limites de mensagens por número e por dia. Para envio em massa, use filas e implemente lógica de retry com backoff exponencial.
- Segurança: Armazene tokens de acesso de forma segura e rotacione as credenciais periodicamente. Certifique-se de obter o consentimento do usuário antes de enviar mensagens de marketing.
Exemplos Práticos
- Atendimento ao Cliente: Um agente recebe uma solicitação de suporte, consulta o registro do cliente e envia uma mensagem WhatsApp com o número do ticket e próximos passos — ou usa um template de botão interativo para encaminhar o usuário para a equipe correta.
- Notificações Transacionais: Um fluxo de trabalho é acionado após um pedido e envia um template com confirmação do pedido, atualizações de envio ou notificações de pagamento.
- Entrega de Documentos: Um agente gera uma fatura ou contrato em PDF e o entrega via ferramenta Send Media com uma legenda descritiva.
- Campanhas de Broadcast: Um fluxo de trabalho itera sobre uma lista de contatos e envia um template de marketing aprovado com substituição de parâmetros personalizados.
Solução de Problemas
| Código de Erro | Sintoma | Correção |
|---|---|---|
401 / 190 | Token de acesso inválido | Regenere o token do Usuário do Sistema no Meta Business Manager e atualize a conexão |
33 | ID do Número de Telefone inválido | Verifique o Phone Number ID no WhatsApp Manager |
1006 | Formato de número de telefone inválido | Use o formato E.164 — inclua + e o código do país, sem espaços ou traços |
131005 | Template não encontrado | Confirme o nome do template e que ele existe no Meta Business Manager |
131056 | Template pausado | Verifique a classificação de qualidade do template no Meta Business Manager |
1011 | Falha no download da mídia | Use uma URL HTTPS pública e confirme que o tipo de arquivo e o tipo MIME são suportados |
- Verifique as credenciais e se a conexão é válida
- Confirme que o número de telefone do destinatário está registrado no WhatsApp
- Valide o formato da mensagem e a estrutura do payload
- Confirme o status de aprovação do template
- Verifique se os limites de taxa da API foram atingidos