Telegram
Connect agents to Telegram bots. Receive messages from users and send AI responses.
How It Works
When you create an inbound Telegram connector, Connic registers a webhook with Telegram using your bot token. Telegram sends every update (messages, edited messages, callback queries) 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 detailsIf 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.
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
sendMessage. Useful 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 taken from the agent's JSON output first, then falls back to the default chat ID configured on the connector.
Agent Output Format
Your agent can return JSON with a text field (also accepts message or body) and optionally a chat_id (if not set on the connector). A bare string is also sent as the message text, using the connector's default chat ID. Messages are always sent with parse_mode: HTML, so HTML formatting is rendered.
{
"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 details- 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.