Telegram

How It Works

When an inbound Telegram connector is created, Connic registers a webhook with Telegram using the bot token. Telegram sends message, edited-message, and callback-query updates to the connector. Connic verifies each request, extracts the update details, and triggers linked agents.

Setup Instructions

Agent Input Payload

The 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": { ... }
  }
}

Media Messages

Photos, voice messages, audio, videos, video notes, documents, and animations are downloaded when available. The largest photo size is used. Each downloaded item appears in files with name, mime_type, base64-encoded data, and byte size.

Example Agent

name: telegram-assistant
model: connic/gpt-5.6-terra
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 details

How It Works

Automatic outbound connectors send a completed run's final output and can be limited to selected inputs. Agent-tool and middleware outbound connectors send only when called. Connic resolves the destination and formats the Telegram API request without exposing the bot token or stored chat ID.

Agent-tool and Middleware Outbound Connectors

An agent-tool outbound connector exposes an editable tool name, defaulting to send_to_<connector_name>. Call a middleware outbound connector by its configured name through send_connector. Both use the payload schema below. text is required; chat_id accepts a string or integer and is optional when another route is available.

{
  "text": "Your order #12345 is on its way!",
  "chat_id": 987654321
}

Automatic Output Format

Existing automatic outbound connectors keep the legacy behavior and remain enabled for all runs. The agent can return JSON with a text field (also accepts message or body) and optionally a chat_id. A bare string is also sent as the message text. The resolution order below applies to both forms. 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."
}

Automatic-Link Agent Example

name: telegram-support
model: connic/gpt-5.6-terra
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