chatbot gateway

Home > Chatbot > Gateways REST

Chatbot por gateway REST (Evolution API, WPPConnect, Z-API)

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Nível: intermediário

Em uma frase: TRALChatGateway liga o robô a um gateway REST de WhatsApp não oficial (Evolution API, WPPConnect Server, Z-API) ou a qualquer outro serviço que mande e receba mensagens por JSON, configurado no Object Inspector.

Você vai precisar: o pacote RALModuleChatPackage, um cliente RAL (motor de cliente ligado ao programa), o gateway rodando e um TRALChatWebhookModule no servidor para receber.

Warning

Os gateways de WhatsApp não oficiais violam os termos do WhatsApp: o número pode ser banido, mais ainda com envio em massa. Use um número reserva. Por isso os limites de envio vêm baixos (1 mensagem por segundo, 1 a cada 3 segundos por conversa); aumente por sua conta e risco em Rates.

Perfis prontos

Profile preenche endereços, cabeçalhos e campos do gateway escolhido:

perfil	gateway	autenticação do envio	prova do webhook
gpEvolution	Evolution API v2	cabeçalho apikey	segredo num cabeçalho (configure nos headers do webhook da instância)
gpWPPConnect	WPPConnect Server	Bearer com o token da sessão	nenhuma: só por lista de IPs (AllowedIPs)
gpZAPI	Z-API	Client-Token	Client-Token
gpCustom	qualquer outro	o que você configurar	o que você configurar

  FGateway := TRALChatGateway.Create(Self);
  FGateway.Profile := gpEvolution;
  FGateway.BaseUrl := 'http://localhost:8080';
  FGateway.Instance := 'minha-instancia';
  FGateway.TokenSource := tsEnvironment;          // a apikey da instância
  FGateway.TokenName := 'EVOLUTION_APIKEY';
  FGateway.Verification.Secret := GetEnvironmentVariable('EVOLUTION_WEBHOOK_SECRET');
  FGateway.Bot := FBot;
  FBot.Channels.Add.Channel := FGateway;

No gateway, aponte o webhook para a rota do canal no TRALChatWebhookModule (/gateway, ou o ChannelName que você der).

Conferindo quem chama o webhook

Verification.Mode:

• gvSecret: um segredo num cabeçalho (HeaderName), comparado em tempo constante.
• gvHMAC: assinatura HMAC do corpo (SHA-1, SHA-256 ou SHA-512, em hex ou base64, com Prefix e, se o gateway mandar, o horário em TimestampHeader e Template).
• gvIPList: só os endereços de AllowedIPs (IP exato ou faixa IPv4 10.0.0.0/8); atrás de um proxy, IPHeader (X-Forwarded-For).
• gvNone: aceita tudo e avisa no OnLog a cada pedido. Só para testes.

Sem o segredo ou a lista preenchidos, todo webhook é recusado (401): um gateway mal configurado não deixa qualquer um falar pelo seu robô.

Um gateway que não tem perfil

Tudo que o perfil preenche fica editável:

• Outgoing: um endereço por tipo de mensagem (Text, Image, Document, Audio, Video, Location, Contact, Buttons, List, Typing, Edit, Delete), cada um com Url, Method e Body. No Body, marcadores entre chaves viram valores JSON já escapados: {chat}, {text}, {caption}, {media}, {mime}, {filename}, {latitude}, {longitude}, {buttons}, {rows}... Na Url, {instance} e os demais entram codificados. Um tipo sem endereço vira texto pelo Fallback do robô.
• AuthHeader/AuthValue (com {token}), Headers extras.
• Incoming: os caminhos no JSON do webhook (TextPath, ChatIdPath, EventIdPath, SenderNamePath, MediaUrlPath...), vários separados por ponto e vírgula (vale o primeiro que existir); KindRules diz o tipo da mensagem por regras caminho|valor|tipo; EventPath/EventValues filtram os eventos que interessam; FromMePath ignora o que o próprio número mandou.
• Mídia que chega por URL só é baixada do endereço do gateway e de MediaHosts, até MaxDownloadSize; o token nunca vai para outro endereço.

O que conferir no gateway real

Os perfis foram montados a partir da documentação pública de cada gateway; os envios de texto, mídia, localização e lista são os mais seguros. Botões, edição e remoção mudam entre versões dos gateways: se um deles falhar, ajuste o Url/Body daquele tipo em Outgoing.

Erros comuns

sintoma	causa	o que fazer
webhook responde 401	o gateway não manda o segredo, ou o IP não está na lista	configure o cabeçalho no gateway, ou use gvIPList
aviso "sem verificação" no log a cada pedido	gvNone	só em teste; em produção, segredo ou lista de IPs
envio dá 401/403	token ou Instance errado	confira a apikey/token da instância
número banido	envio em massa por gateway não oficial	API oficial (WhatsApp Cloud) para volume

Veja também

• Chatbot, Telegram, conversa em etapas