Greentic Documentation

概要

Telegram provider を使うと、digital worker は Telegram bot 経由でやり取りできます。次をサポートします:

テキストメッセージ
inline keyboard（button）
reply keyboard
file attachment
media（photo、video、document）
group chat

前提条件

Telegram account
Telegram bot（@BotFather で作成）

セットアップ

Telegram bot を作成する

Telegram を開いて @BotFather にメッセージを送ります:
```
/newbot
```
指示に従って進めます:
- bot の名前を入力する（例: “My Support Bot”）
- username を入力する（末尾は bot にする。例: “my_support_bot”）
BotFather は次のような bot token を返します:
```
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
```

provider を設定する

answers file を作成または更新します:

{
  "messaging-telegram": {
    "enabled": true,
    "public_base_url": "https://your-domain.ngrok-free.app",
    "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
  }
}

setup を実行する

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

runtime を起動する
Terminal window
```
gtc start ./my-bundle
```
bot をテストする

Telegram を開き、username で bot を見つけてメッセージを送ります。

設定オプション

Option	Required	Description
`enabled`	Yes	provider を有効/無効にする
`public_base_url`	Yes	webhook 用の公開 URL
`bot_token`	Yes	@BotFather から取得する bot token
`api_base_url`	No	Telegram API URL（デフォルト: `https://api.telegram.org`）

機能

テキストメッセージ

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

Markdown Formatting

Telegram は MarkdownV2 をサポートします:

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

Inline Keyboard（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

Photo を送る

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

Document を送る

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

特定メッセージへの返信

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

Button Callback の処理

user が inline keyboard の button をクリックすると、callback を受け取ります:

name: handle_callback
version: "1.0"

nodes:
  - id: check_action
    type: branch
    config:
      conditions:
        - expression: "callback_data == 'action:help'"
          next: show_help
        - expression: "callback_data == 'action:settings'"
          next: 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

Telegram provider は group chat をサポートします:

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

Group Chat ID の取得

bot を group に追加する
group でメッセージを送る
webhook payload の chat.id を確認する

または Telegram API を使います:

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

Webhook 設定

setup flow は webhook を自動設定します:

POST https://api.telegram.org/bot<TOKEN>/setWebhook
{
  "url": "https://your-domain.com/webhook/telegram/{tenant}/{team}",
  "allowed_updates": ["message", "callback_query"]
}

手動で Webhook を設定する

必要であれば、手動で設定します:

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

トラブルシューティング

Bot が応答しない

webhook status を確認する:

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

公開 URL にアクセスできることを確認する:
Terminal window
```
curl https://your-domain.ngrok-free.app/health
```
log を確認する:
Terminal window
```
gtc start ./my-bundle --verbose
```

Webhook Registration Failed

Error: 401 Unauthorized

bot token が正しく、期限切れでないことを確認してください。

メッセージを受信できない

bot が開始されていることを確認する（user が /start を送信済み）
group chat の場合は、bot が group にいることを確認する
webhook URL が公開 URL と一致していることを確認する

Rate Limiting

Telegram には rate limit があります:

1 chat あたり 1 秒に 1 message
全体で 1 秒に 30 message

適切に処理してください:

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

セキュリティ

Webhook Security

Telegram は webhook request と一緒に secret token を送信します。Greentic はこれを自動で検証します。

Input Validation

常に user input を検証してください:

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

次のステップ

Slack Provider - Slack integration を追加する
Flows Guide - 複雑な workflow を構築する
Buttons and Cards - rich UI 要素