Telegram

Set up

1. 1

   In Telegram, message @BotFather, send /newbot, follow the prompts, and copy the bot token, such as 123456:ABC-DEF....

2. 2

   Open the agent. In Connector Flow, click Add inbound connector for inbound or Add outbound connector for outbound. Then click Create New Connector and choose Telegram.

3. 3

   Choose the mode, Inbound (Receive Messages) or Outbound (Send Messages), and paste the Bot Token. For inbound, optionally enter Allowed User IDs. For outbound, optionally enter a Default Chat ID.

4. 4

   Click Create. connic checks the token with Telegram. An inbound connector registers its webhook with Telegram, so there is nothing to set up there. For outbound, choose how the agent uses the connector and click Link connector.

type: telegram
mode: inbound
config:
  bot_token: ${TELEGRAM_BOT_TOKEN}
  allowed_user_ids: ["123456789", "987654321"]
agents:
  - telegram-assistant

type: telegram
mode: outbound
config:
  bot_token: ${TELEGRAM_BOT_TOKEN}
  chat_id: -1001234567890
agents:
  - name: telegram-assistant
    outbound: { usage: automatic }

Configuration

The fields of a Telegram connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.

Agent input

Modes: Inbound

An inbound connector starts a run for every linked agent with each message, edited message, and callback query the bot receives. An edited message arrives like a new one, with the edited text. The payload has the most useful fields at the top level and the full Telegram update under raw:

{
  "update_id": 123456789,
  "text": "What is the status of my order?",
  "chat_id": 987654321,
  "message": {
    "message_id": 42,
    "text": "What is the status of my order?",
    "date": 1760000000,
    "chat_id": 987654321,
    "chat_type": "private",
    "chat_title": null,
    "from_id": 987654321,
    "from_username": "janedoe",
    "from_first_name": "Jane",
    "from_last_name": "Doe"
  },
  "raw": {
    "update_id": 123456789,
    "message": { ... }
  }
}

text is the message text or the caption of a media message. For a callback query, such as a press on an inline keyboard button, text holds the button's callback data and callback_query replaces message:

{
  "update_id": 123456790,
  "text": "order_status",
  "chat_id": 987654321,
  "callback_query": {
    "id": "4382bfdwdsb323b2d9",
    "data": "order_status",
    "chat_id": 987654321,
    "from_id": 987654321,
    "from_username": "janedoe"
  },
  "raw": { ... }
}

With Allowed User IDs set, updates from other senders get 200 and start no run; the connector's runs list them with user_not_allowed and the sender_user_id. To find a user's ID, have them message the bot and read message.from_id in the run's input, or sender_user_id in the connector's runs while an allowlist is set.

Bot webhook

Modes: Inbound

When an inbound connector is created, connic registers its webhook URL with Telegram for messages, edited messages, and callback queries, together with a generated secret token. Telegram sends the token in the X-Telegram-Bot-Api-Secret-Token header, and connic rejects requests without it with 401. connic registers the webhook again when the bot token changes or the connector switches to inbound, and removes it when the connector switches to outbound or you delete it.

A bot has one webhook. If the bot already has one from another service, connic replaces it and writes the previous URL to the connector logs and to the project's audit log, which keeps it after the connector is deleted. A bot that another connic connector receives updates for can't be connected; remove that connector first. Two inbound connectors in code can't use the same bot either, even in different environments. Outbound connectors don't register a webhook, so they can use the same bot as an inbound connector.

Outbound delivery

Modes: Outbound

An outbound Telegram connector sends one message through the bot with sendMessage each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage.

The chat comes from chat_id in the output or payload, then the connector's Default Chat ID, then the chat of the Telegram update that started the run. Without any of these, the send fails with missing_chat_id. A bot can only message users who have started a chat with it and groups or channels it has been added to.

connic sends every message with parse_mode: HTML, so Telegram renders tags such as <b> and <a>. Escape <, >, and & that aren't part of a tag as HTML entities, or Telegram rejects the message.

{
  "chat_id": 987654321,
  "text": "Your order <b>#12345</b> is on its way."
}

{
  "text": "Your order <b>#12345</b> is on its way.",
  "chat_id": "987654321"
}

Limits and errors

Inbound requests with a missing or wrong secret token get 401 and appear in the connector logs. An update that connic can't read gets 400 and appears in the connector's runs as failed.