Telegram
Connect AI agents to Telegram bots. Receive messages from users and send intelligent responses.
Inbound Mode
Receive Telegram messages and trigger agent runs asynchronously. Every message sent to your bot fires a new agent run.
How It Works
When you create an inbound Telegram connector, Connic automatically registers a webhook with Telegram using your bot token. Telegram then sends every update (messages, edited messages, callback queries) directly to Connic as an HTTP POST. Connic verifies the request, extracts the message details, and triggers your linked agents.
Setup Instructions
Create a Bot with @BotFather
Open Telegram and message @BotFather. Send /newbot, follow the prompts, and copy your bot token (format: 123456:ABC-DEF...).
Create the Connector
In Connic, create a new Telegram connector in Inbound mode and paste your bot token. You can also optionally add a list of allowed Telegram user IDs; if left blank, the connector accepts messages from anyone who can reach the bot.
Link an Agent
Link your connector to an agent. Every Telegram message will now trigger that agent with the message payload as input.
Agent Input Payload
Your agent receives a structured payload with the most useful fields at the top level, plus the full raw Telegram Update object:
{
"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": 1700000000,
"chat_id": 987654321,
"chat_type": "private",
"from_id": 987654321,
"from_username": "johndoe",
"from_first_name": "John",
"from_last_name": "Doe"
},
"raw": {
"update_id": 123456789,
"message": { ... }
}
}Example Agent
name: telegram-assistant
model: gemini-2.5-flash
system: |
You are a Telegram assistant. Answer questions clearly and concisely.
# The incoming Telegram message is passed as the agent's input.
# input["text"] - the message text from the user
# input["chat_id"] - the Telegram chat ID (preserve this for outbound reply)
# input["message"] - full message object with sender detailsFinding Your Telegram User ID
If you want to use Allowed User IDs, an easy way to find your Telegram user ID is to send a message to your bot first, then inspect the connector run payload. Look for message.from_id in the input JSON.
Authentication
Connic uses Telegram's built-in secret_token feature. A random token is generated on connector creation and sent to Telegram via setWebhook. Every request from Telegram includes this token in the X-Telegram-Bot-Api-Secret-Token header, which Connic verifies before processing.
- Secret token header verification
- Rate limiting
- Optional Telegram user ID allowlist
- Bot token stored encrypted
Outbound Mode
When a connected agent completes, its output is sent as a Telegram message via sendMessage. Perfect for notifications, reports, and alerts.
How It Works
The outbound Telegram connector monitors completed agent runs and sends their output as a Telegram message. The chat_id is resolved from the agent's JSON output first, then falls back to the default chat ID configured on the connector.
Agent Output Format
Your agent should return JSON with a text field and optionally a chat_id (if not set on the connector). HTML formatting is supported via Telegram's parse_mode: HTML.
{
"chat_id": 987654321,
"text": "Your order #12345 is on its way! Expected delivery: tomorrow by 6pm."
}Example Agent
name: telegram-support
model: gemini-2.5-flash
system: |
You are a helpful customer support agent.
Always respond with JSON containing:
- "chat_id": the chat_id from the input
- "text": your response message
# Access incoming message:
# input["text"] - message text
# input["chat_id"] - sender's chat ID (required for reply)
# input["message"] - full message detailschat_id Resolution Order
- The
chat_idfield in the agent's JSON output - The default Chat ID configured on the connector
If neither is provided, the delivery will fail. To send replies to the user who triggered an inbound run, pass the chat_id through your agent's output.