Repository navigation
chatbot whatsapp
Home > Chatbot > WhatsApp oficial e Messenger/Instagram
Important
Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.
Warning
Testado só contra uma Graph API falsa. Falta o teste real, com o número de teste da Meta, ainda por fazer. Até lá, trate os detalhes da plataforma (limites, códigos de erro, preços) como conferidos na documentação, não na prática.
Nível: avançado
Em uma frase: TRALChatWhatsApp (WhatsApp Cloud API) e TRALChatMeta (Messenger e
Instagram) são os canais oficiais da Meta do chatbot: recebem por webhook com
assinatura X-Hub-Signature-256 e enviam pela Graph API (versão v27.0 por padrão).
Você vai precisar: os pacotes RALModuleChatPackage e RALModuleChatMetaPackage
(e o RALModuleChatMetaDsgn na IDE; requerem PascalRAL), um cliente RAL com HTTPS, um
servidor RAL com endereço HTTPS público para o webhook (HTTPS) e um app na Meta.
Não há polling: a Meta só entrega por webhook.
Note
Para volume, esta é a alternativa oficial aos gateways não oficiais, que podem banir o número.
- Em developers.facebook.com crie um app do tipo Business e adicione o produto WhatsApp (ou Messenger / Instagram).
- Número de teste (WhatsApp): em WhatsApp > API Setup a Meta dá um número de teste e o Phone number id (não é o telefone) e o WhatsApp Business Account id. Cadastre os telefones que podem receber mensagens do número de teste.
-
Token permanente: o token da tela de teste expira em horas. Em Business Settings >
System users crie um usuário do sistema, atribua o app e gere um token com os
escopos
whatsapp_business_messagingewhatsapp_business_management(Messenger e Instagram:pages_messaging,instagram_manage_messages). - App Secret: App settings > Basic. É a chave da assinatura do webhook.
-
Webhook: em Webhooks (ou WhatsApp > Configuration) informe a URL de
retorno
https://seu.dominio/whatsapp(o caminho é oChannelNamedo canal) e o token de verificação: um texto qualquer seu, igual aoVerifyTokendo canal. Ao salvar, a Meta faz umGETe o canal responde sozinho ao desafio. -
Campos a assinar: WhatsApp,
messages(traz mensagens, status e reações); Messenger e Instagram,messagesemessaging_postbacks. - Um app em modo de desenvolvimento só conversa com quem tem papel no app; para o público é preciso a revisão da Meta.
O verbo "Webhook settings…" (clique direito no componente, na IDE) mostra o texto
para preencher o app: a URL, o token de verificação e os campos. No código,
WebhookInstructions('https://seu.dominio') devolve o mesmo texto. O verbo "Test
token" (TestToken) pergunta à Meta de quem é o token e mostra a conta.
| componente | paleta | para |
|---|---|---|
TRALChatWhatsApp |
RAL - Modules | WhatsApp Cloud API (ChannelName padrão whatsapp) |
TRALChatMeta |
RAL - Modules | Messenger e Instagram (ChannelName padrão meta) |
Propriedades comuns (TRALChatGraphChannel):
| propriedade | para |
|---|---|
Token / TokenSource / TokenName
|
o token de acesso, como nos outros canais (o token) |
AppSecret |
chave do HMAC do X-Hub-Signature-256; vazio recusa todo webhook |
VerifyToken |
o texto do GET de verificação; vazio recusa a verificação |
ApiBase |
https://graph.facebook.com; outro endereço aponta o canal para um servidor de teste (ou graph.instagram.com no login do Instagram) |
ApiVersion |
v27.0; vazio usa a versão do app |
Client / EngineType
|
o cliente RAL que chama a API (deixe o BaseURL dele vazio) ou o motor do cliente próprio |
MaxDownloadSize |
maior arquivo baixado da Meta (100 MB) |
TRALChatWhatsApp: PhoneNumberId (de onde sai a mensagem; um webhook de outro número
do mesmo app é ignorado), BusinessAccountId, OnStatus e OnReaction.
TRALChatMeta: PageId (a Página ou a conta do Instagram; vazio envia para
me/messages), Platform (mpAuto, mpMessenger, mpInstagram; mpAuto lê do
webhook e DetectedPlatform diz qual) e HumanAgent.
uses RALChatMessage, RALChatChannel, RALChatBot, RALChatWebhook, RALChatWhatsApp;
FBot := TRALChatBot.Create(Self);
FBot.OnMessage := ChegouMensagem;
FBot.OnCallback := EscolheuBotao;
FWhats := TRALChatWhatsApp.Create(Self);
FWhats.TokenSource := tsEnvironment;
FWhats.TokenName := 'WHATSAPP_TOKEN';
FWhats.AppSecret := GetEnvironmentVariable('META_APP_SECRET');
FWhats.VerifyToken := GetEnvironmentVariable('META_VERIFY_TOKEN');
FWhats.PhoneNumberId := '123456789012345';
FWhats.OnStatus := StatusDaMensagem;
FWhats.OnReaction := Reagiu;
FWhats.Bot := FBot;
FBot.Channels.Add.Channel := FWhats;
FWebhook := TRALChatWebhookModule.Create(Self);
FWebhook.Bot := FBot;
FWebhook.Server := FServidor; // rota /whatsapp (GET e POST)Os eventos:
procedure TForm1.ChegouMensagem(Sender: TObject; AChannel: TRALChatChannel;
AMessage: TRALChatMessage);
var
vResp: TRALChatMessage;
begin
if AMessage.Kind <> ckText then
Exit;
vResp := TRALChatMessage.Create;
try
vResp.Text := 'Quer ver o seu pedido?';
vResp.AddButton('sim', 'Sim'); // até 3: botões; 4 a 10: lista
vResp.AddButton('nao', 'Não');
FBot.Reply(AMessage, vResp);
finally
vResp.Free;
end;
end;
procedure TForm1.EscolheuBotao(Sender: TObject; AChannel: TRALChatChannel;
AMessage: TRALChatMessage);
begin
if AMessage.CallbackData = 'sim' then
FBot.Reply(AMessage, 'Pedido 1234: saiu para entrega.');
end;
procedure TForm1.StatusDaMensagem(Sender: TObject; const AStatus: TRALChatWhatsAppStatus);
begin
// roda na thread do webhook, antes da resposta à Meta: seja rápido
if AStatus.Status = 'failed' then
Log(Format('%s falhou: %d %s', [AStatus.MessageId, AStatus.ErrorCode, AStatus.ErrorText]));
end;
procedure TForm1.Reagiu(Sender: TObject; const AFrom, AMessageId, AEmoji: StringRAL);
begin
// AEmoji vazio = a pessoa tirou a reação
end;Note
No Free Pascal em modo objfpc atribua os eventos com @ (FBot.OnMessage := @ChegouMensagem); no modo Delphi e no Delphi, sem @.
Messenger e Instagram são iguais, trocando o canal:
FMeta := TRALChatMeta.Create(Self);
FMeta.TokenSource := tsEnvironment;
FMeta.TokenName := 'META_PAGE_TOKEN';
FMeta.AppSecret := GetEnvironmentVariable('META_APP_SECRET');
FMeta.VerifyToken := GetEnvironmentVariable('META_VERIFY_TOKEN');
FMeta.PageId := '1234567890';
FMeta.Platform := mpAuto; // a mesma classe serve os dois
FMeta.Bot := FBot;
FBot.Channels.Add.Channel := FMeta;| recurso | Messenger / Instagram | |
|---|---|---|
| texto | até 4096 caracteres | até 2000 (Messenger) ou 1000 (Instagram) |
| botões | até 3 como botões de resposta; 4 a 10 viram lista; mais que 10 viram texto numerado | respostas rápidas (quick replies), até 13 |
| mídia | por link ou por envio (UploadMedia, id válido por 30 dias) |
anexo por endereço, id ou envio |
| localização, contatos | sim | não |
| reações |
ReactionMessage (enviar) e OnReaction (receber) |
não |
| "digitando" e lido | MarkRead(id, ATyping) |
SendTyping do robô e MarkSeen(id)
|
MarkRead marca a mensagem recebida como lida (tique azul) e, com ATyping, mostra
"digitando" por até 25 segundos ou até a próxima mensagem; é síncrono.
Limites de mídia do WhatsApp: imagem 5 MB, áudio e vídeo 16 MB, documento 100 MB. Os
limites de envio do canal (Rates) seguem a Meta: 80 mensagens por segundo por número e,
por par número-usuário, 1 a cada 6 segundos com rajada de 45.
No WhatsApp, a janela de atendimento abre quando o usuário escreve e se renova a cada mensagem dele. Dentro dela vão texto, mídia, botões, listas, localização e reações. Fora dela só vai um modelo (template) aprovado pela Meta; o envio comum falha com o erro 131047.
var
vMsg: TRALChatMessage;
begin
vMsg := TRALChatWhatsApp.TemplateMessage('5511999990000', 'pedido_enviado', 'pt_BR',
['Maria', '1234']); // parâmetros {{1}}, {{2}} do corpo
try
FBot.Send('whatsapp', vMsg); // ou SendWait para ter o id
finally
vMsg.Free;
end;
end;ReactionMessage(ATo, AMessageId, AEmoji) monta a reação do mesmo jeito (emoji vazio
remove). Os modelos são criados e aprovados no painel da Meta (ou por BusinessAccountId
nas suas próprias chamadas); o nome e o idioma precisam ser os do modelo aprovado.
No Messenger e no Instagram a janela também é de 24 horas. Com HumanAgent := True o
canal envia com a etiqueta HUMAN_AGENT (uma pessoa respondendo, até 7 dias depois da
mensagem do usuário); sem ela, fora da janela a Meta recusa.
OnStatus recebe cada status de uma mensagem enviada: sent, delivered, read ou
failed, com Category (marketing, utility, authentication ou service), Billable
(se é cobrada) e, nas falhas, ErrorCode e ErrorText.
A cobrança do WhatsApp é por mensagem entregue (desde 07/2025), pela categoria:
mensagem do usuário para a empresa é grátis, e as mensagens de serviço dentro da janela
têm uma cota grátis por mês e número, e são cobradas acima dela. Confira os valores
atuais em preços da Meta; o
OnStatus é o jeito de somar o que o seu robô gasta.
-
O HMAC é obrigatório. Todo webhook é conferido com o
AppSecretsobre o corpo cru (X-Hub-Signature-256); sem assinatura válida, ou comAppSecretvazio, recebe 401 e não chega ao robô. A página da Meta diz que a assinatura é opcional; o RAL a exige. - O token de verificação é comparado em tempo constante; vazio recusa o
GET. -
Mídia só de hosts da Meta, e só por https (
graph.facebook.com,graph.instagram.com,*.fbcdn.net,*.fbsbx.com,*.whatsapp.net,*.cdninstagram.com, além do host deApiBase). Um endereço de arquivo de outro lugar no webhook é recusado, para o webhook não servir de ponte para outro servidor. - Token, App Secret e token de verificação nunca aparecem em log nem em erro; ponha-os no ambiente, não no .dfm/.lfm.
- Uma notificação reenviada pela Meta não chega duas vezes ao robô.
O canal lê o erro da Graph API e decide: esperar e tentar de novo (limites 4, 17, 32,
613, 80007 e 130429; falhas passageiras 1, 2, 131000, 131016 e 133004; resposta 5xx),
ou falhar com texto claro (131047 e 190). O par número-usuário com excesso (131056)
espera 4 elevado ao número de falhas seguidas, em segundos. O resultado chega a OnSent
ou, esgotadas as tentativas, a OnSendFailed.
| sintoma | causa | o que fazer |
|---|---|---|
| a Meta não aceita a URL do webhook |
VerifyToken diferente do digitado na Meta, ou HTTPS inválido |
confira o texto e o certificado (certificado automático) |
| webhook responde 401 |
AppSecret vazio ou errado |
o App Secret do app, não o token |
| mensagens não chegam | campo messages não assinado, ou app sem o número/Página ligado |
assine os campos e confira o PhoneNumberId
|
| 131047 ao enviar | o usuário não escreveu nas últimas 24 h |
TemplateMessage com um modelo aprovado |
| 131056 | muitas mensagens para o mesmo usuário | o canal espera sozinho; reduza o ritmo |
| 190 ou 401 do envio | token expirado (o de teste dura horas) ou revogado | token permanente do usuário do sistema |
| 131030 | número que ainda não está na lista do número de teste | cadastre o telefone na Meta |
| mídia recusada | endereço fora dos hosts da Meta | é a proteção; envie por upload ou link da Meta |
| Instagram corta o texto | limite de 1.000 caracteres | divida a mensagem |
Começar
Servidor
- Rotas e parâmetros
- Rotas avançadas: tipos, grupos, versões 🚧
- Ler o pedido e responder
- Objetos no corpo 🚧
- Resposta em fluxo 🚧
- Plugins 🚧
- Serviços (contêiner de dependências) 🚧
- Barramento de eventos 🚧
- Tarefas em segundo plano 🚧
- Recursos com estado 🚧
- Autenticação
- Banco de dados (DBWare)
- Servir site e arquivos
- JSON-RPC 2.0 🚧
- GraphQL 🚧
- Servidor MCP (IA) 🚧
-
Protocol Buffers 🚧
- gRPC 🚧
- WebSocket 🚧
- Hubs (WebSocket) 🚧
- SignalR 🚧
- Swagger e Postman
- Servidor SOAP 🚧
- WS-Security 🚧
- HTTPS
- Criptografia ponto a ponto
- Segurança para produção
- Colocar no ar
- Desempenho
- Testes em memória 🚧
MQTT 🚧
- O que é e quando usar 🚧
- Cliente MQTT 🚧
- Broker MQTT 🚧
- MQTT-SN 🚧
- Ponte REST 🚧
- Segurança 🚧
- Rede ruim 🚧
E-mail 🚧
- Mensagens 🚧
- Enviar 🚧
- Enviar por REST e ação 🚧
- Receber 🚧
- Ler a caixa postal 🚧
- Verificar o que chega 🚧
- Servir caixas postais 🚧
- S/MIME 🚧
- OpenPGP 🚧
Chatbot 🚧
- O robô e os canais 🚧
- Telegram 🚧
- WhatsApp oficial, Messenger e Instagram 🚧
- Gateways REST (WhatsApp não oficial) 🚧
- Discord 🚧
- Slack 🚧
- Microsoft Teams 🚧
- Conversa em etapas 🚧
Cliente
Motores
- Qual motor escolher?
- Compatibilidade
- Recursos
- QUIC
- Motor NgHttp2 (HTTP/2) 🚧
- Motor XSocket 🚧
- Motor AdvancedHTTP (experimental) 🚧
Avançado
Ajuda
- Problemas comuns
- Atualizar o Indy
- Várias versões do Delphi
- Vídeos e guias
- Módulos de terceiros
- Licenças
- Contribuir
- Roadmap e changelog
🚧 = em desenvolvimento, pode mudar