Telegram

Connect your Aerostack bot to Telegram. Messages sent to your Telegram bot are forwarded to Aerostack via webhook, processed through the bot engine, and responses are sent back automatically.

Prerequisites

An Aerostack account with an existing bot (or create one during setup)
A Telegram account

Step 1: Create a Telegram Bot

Open Telegram and search for @BotFather
Send /newbot
Choose a display name (e.g., “Acme Support”)
Choose a username (must end in bot, e.g., acme_support_bot)
BotFather will respond with your bot token

The token looks like: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyz

Step 2: Configure in Aerostack

Via Dashboard

Navigate to Bots in the sidebar
Click on your bot (or create a new one with platform set to Telegram)
In the Platform Configuration section, enter:
- Bot Token — the token from BotFather
- Webhook Secret — any random string (e.g., my-secret-abc123)

Via API

# Create a new bot
curl -X POST https://api.aerostack.dev/api/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telegram Support Bot",
    "platform": "telegram",
    "workspace_id": "YOUR_WORKSPACE_ID",
    "system_prompt": "You are a helpful customer support assistant.",
    "platform_config": {
      "bot_token": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyz",
      "webhook_secret": "my-secret-abc123"
    }
  }'

Or update an existing bot’s platform config:

curl -X PATCH https://api.aerostack.dev/api/bots/YOUR_BOT_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_config": {
      "bot_token": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyz",
      "webhook_secret": "my-secret-abc123"
    }
  }'

Step 3: Activate

Activating registers the webhook URL with Telegram automatically via the Bot API setWebhook method.

Via Dashboard

Click the Activate button on your bot’s detail page.

Via API

curl -X POST https://api.aerostack.dev/api/bots/YOUR_BOT_ID/activate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "status": "active",
  "webhook_url": "https://api.aerostack.dev/api/bots/webhook/telegram/bt_a1b2c3d4e5f6g7h8i9j0"
}

The webhook URL format is:

https://api.aerostack.dev/api/bots/webhook/telegram/:botId

Step 4: Test

Send a message to your Telegram bot. You should see a response within a few seconds.

You can also use the Aerostack test endpoint to verify the bot engine works independently of Telegram:

curl -X POST https://api.aerostack.dev/api/bots/YOUR_BOT_ID/test \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hello, what can you do?" }'

Platform Config Fields

Field	Required	Description
`bot_token`	Yes	Token from BotFather
`webhook_secret`	Recommended	Secret token for webhook verification. Sent as `X-Telegram-Bot-Api-Secret-Token` header.
`allowed_chat_types`	No	Array of allowed chat types (e.g., `["private", "group"]`)
`respond_in_groups`	No	Whether to respond in group chats (default: depends on `group_trigger`)
`group_trigger`	No	When to respond in groups: `mention` (default), `reply`, or `always`

Webhook Verification

When webhook_secret is set, Aerostack verifies incoming webhooks by checking the X-Telegram-Bot-Api-Secret-Token header against your configured secret.

Group Chat Behavior

By default, the bot responds in groups only when mentioned (e.g., @your_bot_name) or when a /command is used. You can change this with the group_trigger setting:

Trigger	Behavior
`mention` (default)	Responds to @mentions and /commands only
`reply`	Responds to @mentions, /commands, and direct replies
`always`	Responds to every message in the group

Message Limits

Telegram enforces a 4096 character limit per message. If the bot’s response exceeds this, Aerostack automatically splits it into multiple messages at whitespace boundaries.

Pausing and Deleting

Pause: Unregisters the Telegram webhook. The bot stops receiving messages but retains its configuration.

curl -X POST https://api.aerostack.dev/api/bots/YOUR_BOT_ID/pause \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete: Unregisters the webhook (best effort) and deletes the bot, all conversations, messages, and analytics.

curl -X DELETE https://api.aerostack.dev/api/bots/YOUR_BOT_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Troubleshooting

Issue	Solution
Bot not responding	Check that status is `active` and webhook is registered. Verify your bot token is correct.
”Unauthorized” from Telegram	Your bot token may have been revoked. Use `/revoke` with BotFather to get a new one, then update your bot’s platform config.
Duplicate responses	Ensure only one webhook is registered. Check that no other service is using the same bot token.
Bot responds in DMs but not groups	Set `group_trigger` to `reply` or `always` in your platform config.