Integrating Telegram with grammY

I’ve spent a lot of time dealing with the headaches of manual Telegram API implementations. Managing multipart/form-data for media or trying to handle rate limits without a proper client usually leads to brittle code and missed messages. It is frustrating when you just want to focus on your bot’s logic but end up fighting with the transport layer.

We decided to fix this by moving to grammY as our sole Telegram client. It handles the heavy lifting of the Bot API, including middleware and error handling, so you don’t have to hand-roll fetch calls. I recommend this approach because it gives you a type-safe context and better media helpers right out of the box.

What You’ll Need

You will need these configuration keys from the source documentation to get started:

• channels.telegram.botToken
• channels.telegram.dmPolicy
• channels.telegram.groups
• channels.telegram.allowFrom
• channels.telegram.groupAllowFrom
• channels.telegram.groupPolicy
• channels.telegram.mediaMaxMb
• channels.telegram.linkPreview
• channels.telegram.proxy
• channels.telegram.webhookSecret
• channels.telegram.webhookUrl
• channels.telegram.streamMode

Quick Start

Setting up the grammY integration takes just a few steps. The gateway handles the complexity of switching between long-polling and webhooks automatically.

1. Set your Token: Add your botToken to the configuration. This allows the monitorTelegramProvider to build the grammY Bot instance.
2. Configure the Gateway: If you want to use webhooks, set both webhookUrl and webhookSecret. If these are missing, the bot defaults to long-polling. The webhook-set.ts utility handles the setWebhook and deleteWebhook calls for you.
3. Define Access Policies: Use dmPolicy for private chats and groupPolicy for groups. You can restrict access using allowFrom and groupAllowFrom lists to ensure your agent only responds to authorized users.
4. Enable Advanced Features: If you are using Bot API 9.3 or higher, you can set streamMode to use sendMessageDraft in private topic chats. You can also set mediaMaxMb to manage the size of files the bot downloads via getFile.

Troubleshooting

If you run into issues, here are the two most common points to check based on our current implementation:

• Rate Limits (429 Errors): If you hit Telegram’s rate limits, the grammY throttler is enabled by default to manage outbound requests. We are looking into making additional grammY plugins optional if these limits persist.
• Webhook Port Issues: The webhook listen port is currently fixed to 8787. If your environment requires a different port, you may need to wire it specifically through the gateway.

结尾

If you need help with a specific configuration or get stuck, check out the AI Setup Assistant.

What’s Next

• Telegram Gateway Documentation
• Configuration Reference