Telegram Integration

Overview

Telegram is optional on every Wiro agent. By default your agents already support two built-in messaging channels out of the box:

• Web chat — chat with the agent directly from the wiro.ai dashboard with no extra setup.
• Messaging API — your own application sends and receives messages programmatically via Agent Messaging, with real-time streaming over Agent WebSocket or HTTP callbacks via Agent Webhooks.

Adding a Telegram bot gives you a third, complementary channel — useful when you want to:

• Push operator notifications (campaign alerts, new leads, error reports) to a private chat or team group on your phone.
• Give off-dashboard access to team members who don't log into wiro.ai but still want to message the agent.
• Pipe scheduled status reports from cron skills into a shared Telegram channel.

You can skip this integration entirely — agents keep working through web chat and the API regardless. Telegram activates automatically only after both bottoken and allowedusers are configured.

Availability

Prerequisites

• A Wiro API key — Authentication.
• A deployed agent — Agent Overview.
• A Telegram account.

Setup

Step 1: Create a Telegram bot

1. In Telegram, start a chat with @BotFather.
2. Send /newbot.
3. Choose a display name and a username (must end in bot, e.g. @mycompany_agent_bot).
4. BotFather returns a Bot Token like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Copy it.

Step 2: Collect allowed user IDs

Each allowed user must message the bot first.

1. User sends any message to the bot.
2. Open https://api.telegram.org/bot<BOT_TOKEN>/getUpdates in a browser.
3. Find the message.from.id value in the response — that's the Telegram user ID (numeric).

Alternative: each user can DM @userinfobot in Telegram to get their own ID.

Step 3: Save Telegram credentials on the UserAgent

curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "fields": [
      {
        "credentialkey": "telegram",
        "fieldname": "bottoken",
        "fieldvalue": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
      },
      {
        "credentialkey": "telegram",
        "fieldname": "allowedusers",
        "fieldvalue": ["761381461", "987654321"]
      },
      {
        "credentialkey": "telegram",
        "fieldname": "groups",
        "fieldvalue": [
          {
            "chatid": "-1001234567890",
            "allowedusers": ["761381461"]
          }
        ]
      }
    ]
  }'

Send allowedusers and groups as native JSON arrays. groups is optional; omit it when the bot should be usable only in direct messages.

If you are deploying a new agent, place the complete telegram group in credentials. Do not send an enabledchannels switch or chat-mode field to POST /UserAgent/Deploy; change Chat Mode after deployment with POST /UserAgent/UpdateSettings.

Step 4: Verify the applied state

curl -X POST "https://api.wiro.ai/v1/UserAgent/Detail" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "guid": "your-useragent-guid" }'

Confirm that enabledChannels contains "telegram" and that its communicationChannels row reports enabled: true, configured: true, and an empty missingfields array.

Credential Fields

Chat Mode

teamsessionmode is the agent's single Chat Mode setting, not a Telegram credential. Set it after deployment with POST /UserAgent/UpdateSettings. The same value also controls team members' Wiro web-chat history.

Group conversations remain scoped to their own group and never merge into the direct-message conversation.

Access Behavior

• Direct messages are accepted only from IDs in the top-level allowedusers.
• Group messages are accepted only in configured groups[].chatid rooms and from that room's approved users.
• Group turns must mention the bot.
• Usernames and display names are never authorization values.
• Clear either bottoken or allowedusers with CredentialUpsert to disable Telegram; completing both reactivates it.

Troubleshooting

• Bot doesn't respond: Verify bottoken is correct and the sender's Telegram user ID is in allowedusers.
• "Unauthorized" (401) from Telegram API: BotFather regenerated the token, invalidating the old one. Create a new token and update.
• Rate limits: Telegram bots are limited to ~30 messages/second globally. For burst broadcasts, plan around this.
• Bot works in DMs but not a group: Add the negative group chat ID and sender ID to the same groups[] row, then mention the bot.
• Collaborative mode confusion: Call UserAgent/UpdateSettings with teamsessionmode: "collaborative".

Related

• Agent Credentials & OAuth
• Agent Overview
• Agent Skills
• Telegram Bot API docs