Skip to content
mobius1qwe edited this page Nov 17, 2026 · 1 revision

Home > Chatbot > WhatsApp oficial e Messenger/Instagram

Chatbot no WhatsApp oficial, Messenger e Instagram (API da Meta)

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.

Preparando na Meta

  1. Em developers.facebook.com crie um app do tipo Business e adicione o produto WhatsApp (ou Messenger / Instagram).
  2. 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.
  3. 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_messaging e whatsapp_business_management (Messenger e Instagram: pages_messaging, instagram_manage_messages).
  4. App Secret: App settings > Basic. É a chave da assinatura do webhook.
  5. Webhook: em Webhooks (ou WhatsApp > Configuration) informe a URL de retorno https://seu.dominio/whatsapp (o caminho é o ChannelName do canal) e o token de verificação: um texto qualquer seu, igual ao VerifyToken do canal. Ao salvar, a Meta faz um GET e o canal responde sozinho ao desafio.
  6. Campos a assinar: WhatsApp, messages (traz mensagens, status e reações); Messenger e Instagram, messages e messaging_postbacks.
  7. 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.

Os componentes

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.

Montando

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;

O que cada canal envia

recurso WhatsApp 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.

Modelos e a janela de 24 horas

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.

Status e custos

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.

Segurança

  • O HMAC é obrigatório. Todo webhook é conferido com o AppSecret sobre o corpo cru (X-Hub-Signature-256); sem assinatura válida, ou com AppSecret vazio, 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 de ApiBase). 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ô.

Os erros da Meta

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.

Erros comuns

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

Veja também

Começar

Servidor

MQTT 🚧

E-mail 🚧

Chatbot 🚧

Cliente

Motores

Avançado

Ajuda

🚧 = em desenvolvimento, pode mudar

Clone this wiki locally