Skip to main content
connic

Telegram

Run a Telegram bot on a connic agent. Messages, photos and voice notes start a run, and the agent replies in the same chat.

Modes
Inbound, Outbound
Set up in
Dashboard or connectors/*.yaml
Documentation
Telegram docs
Publisher
By connic

Every message to the bot starts a run

Paste the token from @BotFather. connic checks it, registers the webhook with Telegram and starts every linked agent for each message, edited message or button press.

Webhook included
connic registers the webhook and checks Telegram's secret token on every request. A webhook from another service is replaced, and its URL goes to the connector logs.
Fields the agent needs
text and chat_id sit at the top level, sender details in message, and the full update in raw. A button press puts its callback data in text.
Allowlist
List Telegram user IDs on the connector, and updates from anyone else are logged and ignored.
telegram-payload.json
{
  "update_id": 731542210,
  "text": "Where is my order ord_8812?",
  "chat_id": 418273645,
  "message": {
    "message_id": 52,
    "text": "Where is my order ord_8812?",
    "date": 1792140000,
    "chat_id": 418273645,
    "chat_type": "private",
    "chat_title": null,
    "from_id": 418273645,
    "from_username": "jana_w",
    "from_first_name": "Jana",
    "from_last_name": null
  },
  "raw": {
    "update_id": 731542210,
    "message": { ... }
  }
}

Photos, voice notes and documents included

connic downloads photos, voice messages, audio, videos, documents and animations from Telegram and hands them to the agent with the message.

Limits
Up to 10 files per message or album, with 10 MiB per file and 10 MiB in total. Photos arrive in their largest size.
One album, one run
connic collects an album until no new item arrives for two seconds, then starts one run per linked agent with all captions in text.
Skipped files
A file over a limit is skipped with its reason in file_issues, and the message still starts a run unless the agent link requires files.
telegram-payload.json
{
  "text": "Receipts from Tuesday's trip",
  "chat_id": 418273645,
  "media_group_id": "13581274910",
  "files": [
    {
      "name": "photo-52.jpg",
      "mime_type": "image/jpeg",
      "data": "/9j/4AAQSkZJRgABAQ...",
      "size": 214380
    },
    {
      "name": "photo-53.jpg",
      "mime_type": "image/jpeg",
      "data": "/9j/4AAQSkZJRgABAQ...",
      "size": 198112
    }
  ],
  "messages": [ ... ],
  "raw_updates": [ ... ]
}

Keep the bot next to your agents

Declare it in connectors/. The bot token comes from a Variable, so it never sits in the file, and connic generates the webhook secret on the first deploy. Set the Variable per environment to give each environment its own bot.

connectors/support-bot.yaml
type: telegram
mode: inbound
name: Support bot
config:
  bot_token: ${TELEGRAM_BOT_TOKEN}
agents:
  - support-bot
create: connectors/support-bot.yaml (telegram)

Reply in the same chat

An outbound Telegram connector sends the agent's text through sendMessage. HTML tags format it, so bold text and links render in the chat.

Back to the sender
Leave chat_id out, and the reply goes to the connector's Default Chat ID or, without one, back to the chat the message came from.
Alerts to a group
Set a Default Chat ID, and runs started by schedules or other connectors post there too.
One conversation per chat
Key the agent's session on input.chat_id, and each chat keeps its own history.
agents/support-bot.yaml
version: "1.0"
name: support-bot
description: Answers customer questions in Telegram.
model: connic/gpt-5.6-terra
system_prompt: |
  Answer in two or three sentences.
  Format with <b> and <a> tags only.
session:
  key: input.chat_id
output.json
{
  "text": "Order <b>ord_8812</b> left our warehouse today."
}

Where Telegram fits

Pick a setup to see what the bot receives, which agent runs and what it sends back.

Customers message your bot, and the agent answers in the same chat.

Customer in Telegram
Inbound Telegram
support-bot
Reply in the chat
telegram-payload.json
{
  "text": "Can I still change my delivery address?",
  "chat_id": 418273645,
  "message": {
    "message_id": 77,
    "chat_type": "private",
    "from_id": 418273645,
    "from_first_name": "Sam"
  }
}
output.json
{
  "text": "Yes, until the order ships. Send me the new address."
}

Your team sends photos of receipts, and the agent confirms the amounts it logged.

Field team
Inbound Telegram
expense-logger
Confirmation in the chat
telegram-payload.json
{
  "text": "Taxi to the client",
  "chat_id": 529104733,
  "files": [
    {
      "name": "photo.jpg",
      "mime_type": "image/jpeg",
      "data": "/9j/4AAQSkZJRgABAQ...",
      "size": 214380
    }
  ]
}
output.json
{
  "text": "Logged <b>EUR 38.40</b> for the taxi on Oct 13."
}

Send the bot a voice note and get a written summary with the to-dos back.

Voice note
Inbound Telegram
voice-notes
Summary in the chat
telegram-payload.json
{
  "text": "",
  "chat_id": 529104733,
  "files": [
    {
      "name": "voice.ogg",
      "mime_type": "audio/ogg",
      "data": "T2dnUwACAAAAAAAAAAD...",
      "size": 61248
    }
  ]
}
output.json
{
  "text": "<b>To-do</b>: send the Example GmbH quote by Friday."
}

Your monitoring posts each alert, and the agent sends a short summary to the on-call group.

Monitoring
Inbound webhook
alert-summary
Message to the on-call group
alert.json
{
  "alert": "checkout-api error rate above 5%",
  "severity": "critical",
  "started_at": "2026-10-13T02:14:00Z",
  "dashboard": "https://monitoring.example.com/d/checkout"
}
output.json
{
  "text": "<b>checkout-api</b> errors at 7% since 02:14 UTC."
}

Telegram FAQ

Create the bot with @BotFather, paste its token into an inbound Telegram connector and link an agent. connic checks the token and registers the webhook with Telegram, so there is no bot server or polling loop to run. For a working starting point, use the Telegram Personal Assistant template.

Yes. Link the same agent to an outbound Telegram connector as well. If that connector has no Default Chat ID, the reply goes back to the chat the message came from. The agent can also set chat_id itself.

Yes. Add allowed Telegram user IDs to the inbound connector, and updates from anyone else are ignored. To find an ID, message the bot and read message.from_id in the run payload.

No. A bot can feed only one active inbound connector, across all environments. Create a second bot for staging and read each token from a Variable of its environment.