Bots advanced

Escopo: transversal. Aplica-se a qualquer linguagem ou stack do projeto. Pré-requisito: bots.md: conceitos fundamentais (webhook, polling, command routing, session, rate limit).

Este guia cobre as particularidades de cada plataforma: como autenticar, quais primitivas de UI (User Interface, interface do usuário) cada uma oferece e onde estão os limites de cada gateway (ponto de entrada da plataforma).

O bot autentica via Bot Token obtido no Discord Developer Portal. O token é enviado no header Authorization: Bot <token> em todas as chamadas à API (Application Programming Interface, Interface de Programação de Aplicações) REST (Representational State Transfer, Transferência de Estado Representacional) e na conexão com o Gateway via WebSocket.

Criar Application → Add Bot → copiar token → convidar bot ao servidor com OAuth2 URL

Nunca usar o token de conta de usuário (self-bot). Isso viola os Termos de Serviço do Discord e pode resultar em banimento permanente.

O Discord usa Gateway Intents para controlar quais eventos o bot recebe. Sem declarar a intent correta, o evento não chega ao bot. Intents privilegiadas (Presence, Guild Members, Message Content) requerem aprovação manual para bots em mais de 100 servidores.

Slash commands são registrados na API do Discord antes de ficarem disponíveis. O registro pode ser global (propagação em até 1 hora) ou por servidor (instantâneo, ideal para desenvolvimento).

Definir schema do comando → POST /applications/:id/commands → Discord registra → usuário digita / → autocomplete aparece → usuário confirma → Discord envia Interaction → bot responde

A resposta a uma Interaction deve ocorrer em até 3 segundos. Para operações longas, o bot responde com deferReply e edita a resposta quando o processamento termina.

Embeds são a primitiva de mensagem rica do Discord. Substituem mensagens longas com formatação Markdown quando há múltiplos campos estruturados.

Limites de embed:

O bot autentica via Bot Token gerado pelo BotFather (@BotFather no Telegram). Todas as requisições à Bot API usam o token na URL (Uniform Resource Locator, Localizador Uniforme de Recursos): https://api.telegram.org/bot<token>/método.

/newbot no BotFather → define nome e username → BotFather entrega o token

O Telegram suporta os dois modos. Para webhook, o endpoint precisa de certificado TLS válido (self-signed é aceito com configuração extra).

Webhook:  POST https://api.telegram.org/bot<token>/setWebhook?url=<sua-url>
Polling:  GET  https://api.telegram.org/bot<token>/getUpdates?offset=<ultimo-update-id>

No polling, o parâmetro offset deve avançar a cada lote para não reprocessar eventos. O valor correto é update_id do último evento processado + 1.

O Telegram oferece dois tipos de botões:

O bot recebe o callback (retorno de interação) via evento callback_query. Após processar, deve chamar answerCallbackQuery para remover o indicador de carregamento na UI do usuário.

Em grupos e supergrupos, o bot só recebe mensagens se for mencionado (@bot) ou se a intent de leitura estiver habilitada nas configurações do BotFather.

O WhatsApp tem dois caminhos radicalmente diferentes para automação:

Para qualquer uso com usuários reais ou dados sensíveis, use a Business API oficial.

O primeiro contato com um usuário sempre exige uma Template Message aprovada pela Meta. Após o usuário responder, abre-se uma janela de 24 horas para troca livre de mensagens.

Bot envia Template → usuário responde → janela de 24h aberta → troca livre → janela fecha → novo Template necessário

O webhook da Business API envia eventos no formato:

{
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{ "from": "5511...", "text": { "body": "Olá" } }]
      }
    }]
  }]
}

O endpoint de webhook precisa responder 200 OK imediatamente. Processar a mensagem de forma síncrona no handler do webhook causa timeout. Enfileirar e processar de forma assíncrona.

A Meta envia uma requisição de verificação GET com parâmetros hub.challenge e hub.verify_token antes de ativar o webhook. O bot precisa responder com o valor de hub.challenge para confirmar propriedade do endpoint.

GET /webhook?hub.mode=subscribe&hub.verify_token=<token>&hub.challenge=<nonce>
Bot responde: 200 OK com body = hub.challenge

O app autentica via Bot Token (xoxb-...) emitido na seção OAuth & Permissions do painel da Slack. O Signing Secret (segredo de assinatura) valida que as requisições HTTP (HyperText Transfer Protocol, Protocolo de Transferência de Hipertexto) recebidas vêm da Slack. Para Socket Mode, um App-Level Token (xapp-...) com scope connections:write substitui a necessidade de URL pública.

Criar app em api.slack.com → Basic Information → Signing Secret
                           → OAuth & Permissions → Add scopes → Install app → Bot Token
                           → App-Level Tokens (para Socket Mode) → Generate → connections:write

Nunca expor o Bot Token, o Signing Secret ou o App-Level Token em código. Armazenar em variáveis de ambiente.

Block Kit é o sistema de UI interativa do Slack. Mensagens são compostas por blocos tipados; cada bloco aceita elementos interativos com um action_id único que identifica o evento de ação.

O bot recebe o evento de ação via app.action(action_id, handler). O ack() (reconhecimento) é obrigatório dentro de 3 segundos; sem ele, a Slack exibe um spinner indefinido no botão.

Declare apenas os scopes necessários em OAuth & Permissions. Scopes desnecessários ampliam a superfície de ataque e podem bloquear a aprovação em app directories.

Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.