v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:11:00.000Z▲ 0 upvotes

Telegram-бот: webhook или long polling, secret_token и деплой на serverless

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

Duas maneiras de receber atualizações

A API Bot entrega mensagens recebidas de duas maneiras mutuamente exclusivas:

  • Polling longo - o próprio bot chama getUpdates com o parâmetro timeout, o Telegram mantém a solicitação aberta até que as atualizações apareçam. É necessário um processo em execução constante; não são necessárias portas de entrada.
  • Webhook - O Telegram envia cada atualização com uma solicitação POST para o seu endereço HTTPS. O processo pode não estar em execução o tempo todo, portanto a opção é sem servidor.

Eles não funcionam ao mesmo tempo: enquanto o webhook está instalado, getUpdates retorna um erro 409 Conflict. Este é um motivo comum pelo qual “o bot parou de responder” quando uma cópia local foi iniciada no servidor no modo de pesquisa.

| | Votação longa | Webhook | |---|---|---| | Onde correr | VPS, contêiner, local | sem servidor, qualquer servidor HTTPS | | Endereço público | não é necessário | HTTPS na porta 443, 80, 88 ou 8443 | | Desenvolvimento | simples, funciona por causa do NAT | preciso de um túnel para depuração local | | Processo simples | atualizações estão esperando na fila | Telegram repete entrega |

Para desenvolvimento e um bot em um VPS, a pesquisa longa é mais fácil. Para implantação em Vercel, Cloudflare Workers ou em um webhook somente de função.

Webhook com secret_token

A URL do webhook não pode ser considerada secreta. Sem verificação, qualquer pessoa que o reconheça enviará uma atualização falsa em nome de qualquer usuário. O parâmetro secret_token ao instalar um webhook resolve isso: o Telegram irá transmiti-lo no cabeçalho X-Telegram-Bot-Api-Secret-Token de cada solicitação.

SECRET=$(openssl rand -hex 32)   # допустимы A-Z, a-z, 0-9, _ и -, до 256 символов

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -d "url=https://example.com/api/telegram" \
  -d "secret_token=${SECRET}" \
  -d 'allowed_updates=["message","callback_query"]' \
  -d "drop_pending_updates=true"

allowed_updates limita os tipos de eventos que chegam ao webhook - menos chamadas de função desnecessárias. drop_pending_updates joga fora a fila acumulada para que o bot após a implantação não responda a centenas de mensagens antigas.

Manipulador em Next.js

// app/api/telegram/route.ts
import { timingSafeEqual } from "node:crypto";
import { db } from "@/lib/db";

const TOKEN = process.env.TELEGRAM_BOT_TOKEN!;
const SECRET = process.env.TELEGRAM_WEBHOOK_SECRET!;

function validSecret(header: string | null) {
  if (!header) return false;
  const a = Buffer.from(header), b = Buffer.from(SECRET);
  return a.length === b.length && timingSafeEqual(a, b);
}

async function tg(method: string, body: unknown) {
  const res = await fetch(`https://api.telegram.org/bot${TOKEN}/${method}`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) console.error("telegram", method, res.status, await res.text());
}

export async function POST(req: Request) {
  if (!validSecret(req.headers.get("x-telegram-bot-api-secret-token"))) {
    return new Response("forbidden", { status: 403 });
  }

  const update = await req.json();

  const first = await db.query(
    "INSERT INTO tg_updates (update_id) VALUES ($1) ON CONFLICT DO NOTHING",
    [update.update_id]
  );
  if (first.rowCount === 0) return new Response("ok");

  const msg = update.message;
  if (msg?.text === "/start") {
    await tg("sendMessage", { chat_id: msg.chat.id, text: "Привет! Пришлите номер заказа." });
  } else if (msg?.text) {
    await tg("sendMessage", { chat_id: msg.chat.id, text: await lookupOrder(msg.text) });
  }

  return new Response("ok");
}

Por que assim:

  • O segredo é verificado primeiro e através de timingSafeEqual.
  • Desduplicação por `update_id`. Caso a resposta não chegue no prazo ou não seja devolvida 2xx, o Telegram repetirá a entrega. Sem desduplicação, o usuário receberá duas respostas ou dois pedidos criados.
  • Sempre 200 após o processamento, mesmo que a mensagem não seja reconhecida. Um status incorreto causará novas tentativas e a fila de atualização ficará travada.
  • Token do bot no URL. Não registre URLs completos de solicitações na API do Bot: o token terminará nos logs. No exemplo, apenas o método e o status são registrados.

Você também pode responder diretamente no corpo da resposta do webhook, retornando JSON com o campo method (por exemplo, {"method":"sendMessage","chat_id":...,"text":"..."}). Isso salva uma solicitação de saída, mas você não saberá se a mensagem foi entregue.

Recursos sem servidor

  • Tempo de execução. Se o processamento for longo (chamada LLM, geração de arquivo), a função pode não atender ao limite da plataforma e o Telegram considerará a entrega malsucedida. Responda rapidamente com 200 e mova o trabalho para uma fila ou tarefa em segundo plano e envie o resultado via sendMessage.
  • Paralelismo. O parâmetro max_connections em setWebhook (de 1 a 100, padrão 40) define quantas solicitações simultâneas o Telegram envia. A ordem das mensagens do mesmo usuário não é garantida durante o processamento paralelo. Se o bot estiver conduzindo um diálogo passo a passo, armazene o estado no banco de dados e leve em consideração as corridas.
  • Início a frio. A primeira mensagem após o tempo ocioso é processada mais lentamente. Para bots, isso geralmente é aceitável.

Diagnóstico

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getWebhookInfo"

A resposta contém pending_update_count (quantas atualizações estão aguardando para serem entregues), last_error_date e last_error_message. Erros típicos:

  • Wrong response from the webhook: 403 Forbidden - o segredo nas variáveis de ambiente não corresponde ao passado para setWebhook.
  • SSL error ou Connection refused - um endereço indisponível ou um certificado no qual o Telegram não confia.
  • Aumentando pending_update_count - o manipulador responde com erro ou está fora do tempo.

Quando permanecer em pesquisas longas

Se o bot reside em seu próprio servidor, a carga é leve e você não deseja publicar um endpoint HTTPS, a pesquisa longa é confiável e simples. Bibliotecas como GrammY e Telegraf suportam ambos os modos, e a transição leva várias linhas.

Обсуждение (0)

Ещё на vbcd4u.com