Telegram Integration#

Connect your Telegram bot to Outeract for automated messaging, group interactions, and inline keyboards.

Overview#

Prerequisites#

• Telegram account
• Bot created via @BotFather
• Bot token

Setup Guide#

Step 1: Create a Telegram Bot#

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts:
   • Choose a name for your bot (e.g., “My Business Bot”)
   • Choose a username (must end in ‘bot’, e.g., mybusiness_bot)
4. BotFather will give you a bot token
   • Format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
   • Keep this secret!
5. Save the token for the next step

Step 2: Configure Bot Settings (Optional)#

Talk to @BotFather to customize your bot:

**Recommended**: Disable privacy mode (`/setprivacy`) to receive all messages in groups.

Step 3: Create Platform Connection in Outeract#

mutation {
  createPlatformConnection(
    platformName: TELEGRAM
    name: "My Telegram Bot"
    config: {
      bot_token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  ) {
    id
    webhookUrl
  }
}

Step 4: Set Up Webhook#

Configure Telegram to send events to Outeract:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "<YOUR_WEBHOOK_URL>"}'

Replace:

• <YOUR_BOT_TOKEN> with your bot token
• <YOUR_WEBHOOK_URL> with the webhook URL from step 3

Expected response:

{"ok": true, "result": true, "description": "Webhook was set"}

Step 5: Verify Webhook#

Check your webhook status:

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

Step 6: Test Your Bot#

1. Find your bot in Telegram (search for @your_bot_username)
2. Click “Start” or send /start
3. Send a test message
4. Verify the message appears in Outeract

Supported Features#

Message Types#

Bot Capabilities#

• Private chats (1-on-1 conversations)
• Group chats (with privacy mode disabled)
• Channels (if bot is admin)
• Inline keyboards and buttons
• Commands (e.g., /start, /help)

Sending Messages#

Basic Text Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_telegram_123"
    toExternalId: "123456789"  # Telegram user ID
    message: "Hello from Outeract!"
  ) {
    id
    status {
      success
      externalMessageId
    }
  }
}

Message with Formatting#

Telegram supports Markdown and HTML:

mutation {
  sendMessage(
    platformConnectionId: "pc_telegram_123"
    toExternalId: "123456789"
    message: "*Bold* _italic_ `code` [link](https://example.com)"
  ) {
    id
  }
}

Send with File#

mutation {
  sendMessage(
    platformConnectionId: "pc_telegram_123"
    toExternalId: "123456789"
    message: "Check out this file"
    fileIds: ["file_xyz789"]
  ) {
    id
  }
}

Privacy Modes#

Privacy Mode Enabled (Default)#

Bot only receives:

• Messages that start with /
• Replies to bot’s messages
• Messages in private chats

Limitation: Doesn’t see all group messages

Privacy Mode Disabled#

Bot receives all messages in groups.

Recommended for full chatbot functionality.

To change: Send /setprivacy to @BotFather

Group Chat Setup#

To use your bot in a group:

1. Create or open a Telegram group
2. Click group name → “Add members”
3. Search for your bot (@your_bot_username)
4. Add the bot to the group
5. Recommended: Make the bot an admin for full functionality

External ID Format#

Telegram uses numeric user IDs:

Rate Limits#

Webhook Events#

Message Received#

{
  "event_id": "evt_abc123",
  "event_type": "message.inbound",
  "payload": {
    "message": {
      "text": "Hello!",
      "role": "user"
    },
    "platform": "telegram",
    "external_message_id": "12345"
  },
  "edges": {
    "sent_by": {
      "platform_user_id": "pu_xyz",
      "external_id": "123456789"
    }
  }
}

Troubleshooting#

“Bot token is invalid”#

• Verify you copied the entire token from BotFather
• Check for extra spaces or characters
• Token format: 123456789:ABC...

“Webhook not receiving messages”#

• Verify webhook is set: Check getWebhookInfo
• Ensure webhook URL is publicly accessible
• Must use HTTPS (not HTTP)
• Check for firewall restrictions

“Bot not responding in groups”#

• Disable privacy mode via BotFather (/setprivacy)
• Make sure bot is a member of the group
• Check if bot has permission to send messages

“File sending fails”#

• Telegram has a 50MB file size limit
• Ensure file is accessible
• Check network connectivity

“Messages delayed”#

• Telegram webhook may have delays during high traffic
• Check Telegram’s status page
• Verify your server isn’t rate-limited

Security Best Practices#

• Never share your bot token publicly
• Webhooks must use HTTPS
• Validate webhook source IPs (Telegram publishes IP ranges)
• Always verify webhook payloads

Advanced Features#

Inline Keyboards#

Send interactive buttons with messages. Define in your webhook handler and include in outbound messages.

Bot Commands#

Auto-complete commands when users type /:

Set via /setcommands in BotFather:

start - Start the bot
help - Get help
settings - Configure settings

Deep Links#

Create links that open your bot with parameters:

https://t.me/your_bot?start=parameter

Resources#

• Telegram Bot API Documentation
• BotFather
• Telegram Bot Support