Telegram

Overview

The Telegram provider allows your digital worker to communicate via Telegram bots. It supports:

• Text messages
• Inline keyboards (buttons)
• Reply keyboards
• File attachments
• Media (photos, videos, documents)
• Group chats

Prerequisites

• A Telegram account
• A Telegram bot (created via @BotFather)

Setup

1. Create a Telegram bot

   Open Telegram and message @BotFather:

   /newbot

   Follow the prompts:

   • Enter a name for your bot (e.g., “My Support Bot”)
   • Enter a username (must end in bot, e.g., “my_support_bot”)

   BotFather will give you a bot token like:

   123456789:ABCdefGHIjklMNOpqrsTUVwxyz

2. Configure the provider

   Create or update your answers file:

   answers.json

   {
     "setup_answers": {
       "messaging-telegram": {
         "public_base_url": "https://your-domain.ngrok-free.app",
         "api_base_url": "https://api.telegram.org",
         "telegram_bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
       }
     }
   }

3. Run setup

   gtc setup --answers answers.json ./my-bundle

4. Start the runtime

   gtc start ./my-bundle

5. Test your bot

   Open Telegram, find your bot by username, and send a message!

Configuration Options

Option	Required	Description
public_base_url	Yes	Public URL for webhook
api_base_url	Yes	Telegram API URL, normally https://api.telegram.org
telegram_bot_token	Yes	Bot token from @BotFather
default_chat_id	No	Default chat id for proactive sends

Note

The setup layer also accepts the older bot_token alias and stores it as telegram_bot_token, but new answers files should use the wizard-generated key.

Network Access

Telegram uses webhooks for incoming updates and the Telegram Bot API for outgoing sends. Expose the Greentic runtime through HTTPS on port 443; local development can use a tunnel that forwards the public URL to the local runtime port.

Direction	Protocol and port	Purpose
Incoming	HTTPS 443 from Telegram to Greentic	Bot webhook updates for messages and callback queries
Outgoing	HTTPS 443 from Greentic to api.telegram.org or the configured api_base_url	setWebhook, message sends, callback answers, and Bot API reads

No Telegram-specific TCP port needs to be opened on the Greentic host. The public webhook URL must be reachable by Telegram over HTTPS.

Features

Text Messages

- id: reply
  type: reply
  config:
    message: "Hello! How can I help you today?"

Markdown Formatting

Telegram supports MarkdownV2:

- id: formatted_reply
  type: reply
  config:
    message: |
      *Bold* _Italic_ `Code`
      [Link](https://example.com)
    parse_mode: MarkdownV2

Inline Keyboards (Buttons)

- id: ask_action
  type: reply
  config:
    message: "What would you like to do?"
    buttons:
      - row:
          - label: "Get Help"
            callback_data: "action:help"
          - label: "Settings"
            callback_data: "action:settings"
      - row:
          - label: "Contact Support"
            url: "https://support.example.com"

Reply Keyboards

- id: ask_choice
  type: reply
  config:
    message: "Choose an option:"
    reply_keyboard:
      - ["Option A", "Option B"]
      - ["Option C", "Cancel"]
    resize_keyboard: true
    one_time_keyboard: true

Send Photos

- id: send_image
  type: reply
  config:
    photo:
      url: "https://example.com/image.jpg"
      caption: "Here's your image!"

Send Documents

- id: send_file
  type: reply
  config:
    document:
      url: "https://example.com/report.pdf"
      filename: "report.pdf"
      caption: "Your monthly report"

Reply to Specific Message

- id: reply_to_message
  type: reply
  config:
    message: "This is a reply to your previous message"
    reply_to_message_id: "{{original_message_id}}"

Handling Button Callbacks

When a user clicks an inline keyboard button, you receive a callback:

flows/on_callback.ygtc

name: handle_callback
version: "1.0"

nodes:
  - id: check_action
    type: branch
    config:
      conditions:
        - expression: "callback_data == 'action:help'"
          to: show_help
        - expression: "callback_data == 'action:settings'"
          to: show_settings
      default: unknown_action

  - id: show_help
    type: reply
    config:
      message: "Here's how I can help..."

  - id: show_settings
    type: reply
    config:
      message: "Settings menu..."

  - id: unknown_action
    type: reply
    config:
      message: "Unknown action"

triggers:
  - type: callback_query
    target: check_action

Group Chat Support

The Telegram provider supports group chats:

greentic.demo.yaml

tenants:
  demo:
    teams:
      support:
        channels:
          telegram-group:
            provider: messaging-telegram
            config:
              chat_id: "-1001234567890"  # Group chat ID

Note

Supergroups and channels commonly use -100... chat IDs. Basic groups and private chats use different ID shapes, so always inspect the chat.id value from an actual update.

Getting Group Chat ID

1. Add your bot to the group
2. Send a message in the group
3. Check the webhook payload for chat.id

Or use the Telegram API:

curl "https://api.telegram.org/bot<TOKEN>/getUpdates"

Webhook Configuration

The setup flow automatically configures the webhook:

POST https://api.telegram.org/bot<TOKEN>/setWebhook
{
  "url": "https://your-domain.com/v1/messaging/ingress/messaging-telegram/{tenant}/{team}",
  "allowed_updates": ["message", "callback_query"],
  "secret_token": "optional-shared-secret"
}

Manual Webhook Setup

If needed, configure manually:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/v1/messaging/ingress/messaging-telegram/demo/default",
    "allowed_updates": ["message", "callback_query"],
    "secret_token": "optional-shared-secret"
  }'

Telegram sends the configured secret_token back in the X-Telegram-Bot-Api-Secret-Token header. Configure it when your installed pack exposes that field.

Troubleshooting

Bot Not Responding

1. Check webhook status:

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

2. Verify public URL is accessible:

   curl https://your-domain.ngrok-free.app/health

3. Check logs:

   gtc start ./my-bundle --verbose

Webhook Registration Failed

Error: 401 Unauthorized

Verify your bot token is correct and not expired.

Messages Not Being Received

1. Ensure the bot has been started (user sent /start)
2. Check if the bot is in the group (for group chats)
3. Verify webhook URL matches your public URL

Rate Limiting

Telegram has rate limits:

• 1 message per second per chat
• 30 messages per second overall

Handle rate limits gracefully:

- id: reply
  type: reply
  config:
    message: "Response"
    retry_on_429: true
    max_retries: 3

Security

Caution

Never expose your bot token. Keep it in secure secrets storage.

Webhook Security

Telegram sends a secret token with webhook requests. Greentic validates this automatically.

Input Validation

Always validate user input:

- id: validate
  type: script
  config:
    script: |
      if message.len() > 4096 {
        return error("Message too long")
      }
      message

Next Steps

• Slack Provider - Add Slack integration
• Flows Guide - Build complex workflows
• Buttons and Cards - Rich UI elements