Telegram Integration

This guide walks through connecting an AI agent to Telegram via the Pai Provider system. Once configured, users can chat with the agent directly in Telegram, and the agent can send messages, photos, and documents.

How it works

Telegram integration in Pai uses the Provider Proxy (sidecar) to intercept and credential-inject all calls to api.telegram.org:

User (Telegram app)
    |
    v
Telegram Cloud
    |
    v
Agent Container (polls getUpdates or receives webhook)
    |  (DNS: api.telegram.org --> 127.0.0.1)
    |  (iptables: port 443 --> 8443)
    v
Sidecar Proxy
    |-- injects bot token as Bearer header
    |-- logs API call for audit
    v
api.telegram.org (real endpoint)

The agent never holds the real bot token. It uses a dummy token value injected via the TELEGRAM_BOT_TOKEN environment variable, and the sidecar replaces it with the real token on every request.

Step 1: Create a Telegram bot

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Choose a name for your bot (e.g., "My Pai Agent")
4. Choose a username (must end in bot, e.g., my_pai_agent_bot)
5. BotFather will respond with your bot token -- a string like 7123456789:AAH1bGc...

Save this token securely. You will need it in the next step.

Step 2: Store the bot token as a secret

pai add secret telegram-token --from-literal token=7123456789:AAH1bGcXYZ...

Step 3: Create the Provider

Create a file called telegram-provider.yaml:

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

Apply it:

pai apply -f telegram-provider.yaml

Or use the CLI shorthand:

pai add service telegram-bot \
  --provider telegram \
  --secret-token telegram-token

Key fields explained:

Field	Purpose
type: telegram	Activates the Telegram provider plugin in the sidecar
host: api.telegram.org	Hostname to intercept via DNS hijacking
auth.type: bot-token	Tells the sidecar how to inject the credential
auth.secretRef: telegram-token	Kubernetes Secret holding the real bot token
auth.secretKey: token	Key within the Secret
auth.agentEnvVar: TELEGRAM_BOT_TOKEN	Env var injected into the agent container with a dummy value so the agent's Telegram library initializes correctly

Step 4: Reference the provider in your agent

Add the Provider to your AgentWorkload:

apiVersion: pai.io/v1
kind: AgentWorkload
metadata:
  name: my-agent
spec:
  image: ghcr.io/pai-platform/openclaw:latest
  runAsUser: 1000
  modelBindings:
    - gemini-flash
  providers:
    - telegram-bot
  inbound:
    port: 3000
  configFiles:
    - path: /home/node/.openclaw/openclaw.json
      content: |
        {
          "channels": ["telegram"],
          "defaultModel": "gemini-flash"
        }

Deploy:

pai apply -f my-agent.yaml

Step 5: Pair the bot with the agent

Once the agent is running, open Telegram and:

1. Search for your bot by its username (e.g., @my_pai_agent_bot)
2. Tap Start or send /start
3. Send a message -- the agent will respond through the Telegram bot

The agent polls getUpdates from the Telegram API. Every call goes through the sidecar, which:

• Intercepts the HTTPS connection to api.telegram.org
• Replaces the dummy bot token with the real token from the Kubernetes Secret
• Forwards the request to Telegram
• Returns the response to the agent

Step 6: Verify the integration

Check that the agent is communicating with Telegram:

pai status my-agent

# Services:
#   - telegram-bot (telegram / api.telegram.org) -- 12 requests today

View the audit log:

pai events my-agent

# LAST SEEN   TYPE     REASON              OBJECT                  MESSAGE
# 30s         Normal   ServiceCall         AgentWorkload/my-agent  telegram-bot: getUpdates (allowed)
# 25s         Normal   ServiceCall         AgentWorkload/my-agent  telegram-bot: sendMessage (allowed)

Troubleshooting

Bot not responding

1. Check that the agent is running:

   pai status my-agent

2. Check the logs for errors:

   pai logs my-agent --tail 50

3. Verify the secret exists and has the correct key:

   pai get secrets

4. Verify the Provider is attached:

   pai get services

"Unauthorized" errors in logs

The bot token may be incorrect. Delete and recreate the secret:

pai delete secret telegram-token
pai add secret telegram-token --from-literal token=CORRECT_TOKEN_HERE

Then restart the agent:

pai delete agent my-agent
pai create -f my-agent.yaml

Bot responds in web UI but not Telegram

Ensure "telegram" is listed in the channels array in the agent's config file:

configFiles:
  - path: /home/node/.openclaw/openclaw.json
    content: |
      {
        "channels": ["web", "telegram"],
        "defaultModel": "gemini-flash"
      }

Security notes

• The real bot token is stored in a Kubernetes Secret and mounted only in the sidecar container
• The agent container receives a dummy token value via TELEGRAM_BOT_TOKEN -- enough for the Telegram library to initialize, but not valid for API calls
• All Telegram API calls are logged in the audit trail with timestamps, method names, and outcomes
• The sidecar can optionally enforce policy on Telegram methods (e.g., allow sendMessage but deny deleteMessage)