Telegram API

Pastebox can send notifications to Telegram chats when pastes are created.

Environment Variables

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Bot API token from @BotFather
TELEGRAM_WEBHOOK_SECRET	Recommended	Secret for webhook verification (any random string)

Generate a webhook secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Creating a Telegram Bot

1. Open Telegram and find @BotFather
2. Send /newbot and follow the prompts — choose a name and username for your bot
3. BotFather will reply with an API token like 123456789:ABCdef...
4. Set it in your environment:

# Docker Compose (Coolify)
TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_WEBHOOK_SECRET=your-random-secret-here

# .env file (manual deployment)
TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_WEBHOOK_SECRET=your-random-secret-here

# Ansible vault
vault_telegram_bot_token: "123456789:ABCdef..."
vault_telegram_webhook_secret: "your-random-secret-here"

5. Restart the application for the token to take effect

Setting Up the Webhook

After deploying, register the webhook with Telegram so the bot can receive messages:

curl -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/api/v1/telegram/webhook",
    "secret_token": "<TELEGRAM_WEBHOOK_SECRET>"
  }'

Verify the webhook is set correctly:

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getWebhookInfo"

To remove the webhook (e.g. for debugging):

curl -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/deleteWebhook"

Bot Commands

The bot responds to the following commands:

Command	Description
/start	Show welcome message with usage instructions
/link <token>	Link the current chat using a one-time token

Any other /command will display a help message with available commands.

Linking Flow

1. Generate a linking token via POST /api/v1/telegram/tokens
2. Open a chat with the bot in Telegram (or add it to a group)
3. Send /link <token> to the bot
4. The bot confirms linking — you will now receive notifications in this chat
5. Verify via GET /api/v1/telegram/destinations

API Endpoints

Webhook (Telegram → Pastebox)

POST /api/v1/telegram/webhook

Receives updates from Telegram Bot API. Do not call manually — this is configured via setWebhook and called by Telegram servers.

The X-Telegram-Bot-Api-Secret-Token header is validated against TELEGRAM_WEBHOOK_SECRET if configured.

Always returns 200 to prevent Telegram from retrying.

Create Linking Token

POST /api/v1/telegram/tokens

Requires X-Api-Key. Returns a one-time token to link a Telegram chat.

Response 201

{
  "token": "5a92dcb07c7e8f3243dd9bd2a7ab0ca0",
  "instructions": "Send this to the Pastebox bot: /link 5a92dcb07c7e8f3243dd9bd2a7ab0ca0",
  "expiresInMinutes": 15
}

List Destinations

GET /api/v1/telegram/destinations

Requires X-Api-Key. Returns all linked Telegram chats for the authenticated user.

Response 200

{
  "destinations": [
    {
      "id": 1,
      "userId": 1,
      "chatId": "123456789",
      "chatTitle": "My Group",
      "isActive": true,
      "createdAt": "2026-02-09T00:00:00.000Z"
    }
  ]
}

Delete Destination

DELETE /api/v1/telegram/destinations/:id

Requires X-Api-Key. Unlinks a Telegram chat from notifications.

Response 200

{
  "deleted": true
}

Response 404

{
  "error": "Destination not found"
}

Troubleshooting

Bot doesn't respond to /link

1. Check that the webhook is set: GET https://api.telegram.org/bot<TOKEN>/getWebhookInfo
2. Verify url points to https://your-domain.com/api/v1/telegram/webhook
3. Ensure TELEGRAM_BOT_TOKEN is set correctly on the server
4. Check server logs for webhook request errors

Token is invalid or expired

• Tokens expire after 15 minutes
• Each token can only be used once
• Generate a new token via POST /api/v1/telegram/tokens

Webhook returns 403

• Ensure TELEGRAM_WEBHOOK_SECRET on the server matches the secret_token used in setWebhook

No notifications after linking

• Verify the destination is active: GET /api/v1/telegram/destinations
• Check that the worker process is running (start:worker)
• Check the notification_queue table for pending/failed messages