Telegram-бот: webhook или long polling, secret_token и деплой на serverless
Duas maneiras de receber atualizações
A API Bot entrega mensagens recebidas de duas maneiras mutuamente exclusivas:
- Polling longo - o próprio bot chama
getUpdatescom o parâmetrotimeout, 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_connectionsemsetWebhook(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 parasetWebhook.SSL errorouConnection 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.