Telegram

Connect your agent to Telegram so users can chat with it via a bot. The Pai sidecar injects the real bot token on every Telegram API call; the agent holds only a placeholder.

Get credentials

1. Open Telegram and search for @BotFather.
2. Send /newbot.
3. Choose a display name and a username (must end in bot).
4. BotFather replies with your token — a string like 7123456789:AAH1bGc....

Setup

Store the token, then create a Provider:

# 1. Store the token in a Pai secret
pai add secret telegram-token --from-literal token=7123456789:AAH1bGc...

# 2. Create the Provider
pai apply -f - <<EOF
apiVersion: pai.io/v1
kind: Provider
metadata:
  name: telegram-bot
spec:
  type: telegram
  host: api.telegram.org
  auth:
    type: bot-token
    secretRef: telegram-token
    secretKey: token
    agentEnvVar: TELEGRAM_BOT_TOKEN
  policy:
    allow: ["*"]
  audit:
    logRequests: true
EOF

The agentEnvVar field injects a placeholder TELEGRAM_BOT_TOKEN env var into the agent — enough for Telegram client libraries to initialise. The sidecar replaces it with the real token on every outbound request.

Supported actions

Telegram actions are the Bot API method names. Common ones:

Action	Bot API method
sendMessage	Post a message to a chat
sendPhoto, sendDocument, sendVideo	Send media
getUpdates	Long-poll for new messages
answerCallbackQuery	Respond to inline-keyboard callbacks
editMessageText	Edit a previously sent message
deleteMessage	Delete a message
banChatMember, unbanChatMember	Moderation
getChat, getChatMember	Read chat metadata

Full list in the Telegram Bot API docs.

Attach to an agent

spec:
  providers:
    - telegram-bot

Once the agent is running, send /start to your bot in Telegram and verify traffic is flowing:

pai status my-agent
# Providers:
#   - telegram-bot (telegram / api.telegram.org) — 5 requests today

Access control

policy.allow / policy.deny gate which Bot API methods agents can call. Restrict to a safe subset:

policy:
  allow:
    - sendMessage
    - getUpdates
    - sendPhoto
    - answerCallbackQuery
  deny:
    - deleteMessage
    - banChatMember

See the Policy reference for the full field list, HTTP-level rules, and audit mode.