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

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

The token looks like: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyz

Step 2: Configure in Aerostack

Via Dashboard

1. Navigate to Bots in the sidebar
2. Click on your bot (or create a new one with platform set to Telegram)
3. 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

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:

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