Telegram Sentry

Bot passivo de Telegram em PHP. Tem uma única função: quando alguém manda qualquer mensagem, responde com o chat_id da conversa. Útil pra descobrir o chat_id que você precisa pra enviar notificações via API do Telegram.

A aplicação é um arquivo index.php único que se comporta diferente conforme o método HTTP:

• POST → webhook do Telegram (responde com o chat_id)
• GET ?setup=<TOKEN> → registra/atualiza o webhook na URL atual
• GET sem token → resposta neutra (OK)

Pré-requisitos

• PHP 7.4 ou superior (com extensão curl)
• Servidor web com HTTPS (Telegram não aceita webhook em HTTP)
• Apache com .htaccess habilitado (AllowOverride All) — necessário pra proteger o env.php

Se você for usar Nginx, troque o .htaccess por uma location equivalente:

location ~ ^/(env\.php|env\.lock)$ {
    deny all;
}

Passo 1 — Criar o bot no Telegram

1. Abra uma conversa com @BotFather no Telegram
2. Envie /newbot e siga as instruções (nome amigável + username terminando em bot)
3. Anote o token que o BotFather devolver — é algo como 123456789:ABCdefGhIJKlmNoPQRstuVWXyz

Opcionalmente, defina o avatar do bot com /setuserpic (use o bot-avatar.png se quiser).

Passo 2 — Subir os arquivos

Copie o conteúdo do repositório (index.php, env.lock, .htaccess) para o diretório público do seu site.

A aplicação pode rodar tanto na raiz (https://seu-site.com/) quanto num subdiretório (https://seu-site.com/sentry/). O setWebhook detecta a URL automaticamente.

Passo 3 — Gerar os segredos

Você precisa de dois segredos aleatórios:

• SETUP_TOKEN — autoriza o registro/atualização do webhook via GET
• WEBHOOK_SECRET — o Telegram devolve em cada POST, provando que veio dele

Gere ambos com:

php -r "echo bin2hex(random_bytes(16)) . PHP_EOL;"

Rode duas vezes e guarde os dois valores.

Passo 4 — Criar o env.php

No servidor, copie o template e preencha:

cp env.lock env.php

Edite env.php e preencha os três campos:

<?php

return [
    'BOT_TOKEN'      => '123456789:ABCdef...',   // do @BotFather
    'SETUP_TOKEN'    => 'seu_setup_token',       // gerado no passo 3
    'WEBHOOK_SECRET' => 'seu_webhook_secret',    // gerado no passo 3
];

O env.php está no .gitignore e nunca deve ser versionado.

Passo 5 — Registrar o webhook

Acesse uma vez no navegador (ou via curl):

https://seu-site.com/?setup=SEU_SETUP_TOKEN

A resposta é um JSON tipo:

{
    "webhook_url": "https://seu-site.com/",
    "telegram_response": {
        "ok": true,
        "result": true,
        "description": "Webhook was set"
    }
}

Se ok for true, o webhook está registrado. Se não, a mensagem de erro do Telegram aparece em description.

Passo 6 — Testar

Abra uma conversa com o seu bot no Telegram e mande qualquer mensagem (/start serve). Ele deve responder:

Seu chat_id é 123456789

Pronto. Guarde esse chat_id — é o que você usa pra mandar notificações via API do Telegram pra você mesmo.

Mudando o webhook de site

Se você mover a aplicação pra outro domínio:

1. Copie env.php (com as mesmas credenciais) pro novo servidor
2. Acesse https://novo-site.com/?setup=SEU_SETUP_TOKEN

O setWebhook sobrescreve o registro anterior automaticamente. O bot vai parar de receber do site antigo e começar a receber do novo.

Desabilitando o webhook

Se quiser desativar temporariamente, chame a API do Telegram diretamente:

curl "https://api.telegram.org/bot<BOT_TOKEN>/deleteWebhook"

Segurança

• env.php é bloqueado pelo .htaccess. Mesmo se o .htaccess falhar, o arquivo é PHP — o servidor executa e devolve nada
• O SETUP_TOKEN evita re-registro acidental por acessos aleatórios à URL
• O WEBHOOK_SECRET evita que terceiros mandem POSTs falsos simulando o Telegram
• Como toda comunicação passa por HTTPS, os segredos não trafegam em claro