> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Telegram integration The Telegram integration provides two independent connection types: - **Agent bot**: bind a Sharkly Agent as a Telegram bot and chat with it in direct messages, groups, and topics. - **Task assistant**: one system assistant per Space. Bind it from the Telegram integration page, then it can turn conversation context into Tasks in a group, and look up and update that Space's Tasks. Both connect with a bot token created via @BotFather. They can be used at the same time, but each must be configured separately. A task assistant is not an ordinary Agent: it does not appear in Agent lists, assignment pickers, or in-app chat. ## What do you need before connecting? | Requirement | Notes | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Telegram bot | Open @BotFather in Telegram, send /newbot, enter a display name and a bot-prefixed username in turn, and take the bot token. | | Privacy Mode off (optional) | For the bot to receive ordinary group messages that do not mention it, send /setprivacy to @BotFather, pick this bot, and choose Disable — then remove and re-add the bot to the group. Making the bot a group administrator works too. | | Group administrator (optional) | Telegram only delivers reaction events to bots that are group administrators. To use reaction triggers, promote the bot first. | | Agent | Binding an Agent bot requires a Sharkly Agent. Create one first if you have none. | ## Where do you start? - After entering an Organization, open **Integrations** and go to the Telegram page; - Or open an Agent's detail page and configure it in the **Integrations** tab — this binds that Agent directly. ## Connect an Agent bot 1. Open the **Connect Telegram** dialog. 2. Pick the Agent to bind. 3. Paste the bot token from @BotFather. 4. Click connect; the binding completes once the token is validated. 5. Use **Add to group** on the settings page to add the bot to a group, or **Open chat** to message it directly. The bot must be in a group before it can send and receive group messages. After binding, each trigger can be turned on individually in the Agent's integration settings. ## Bind a task assistant 1. Open **Integrations** and go to the **Task assistant** section of the Telegram page. 2. Find a Space you have joined and choose **Bind Telegram**. 3. Pick the Runtime that runs this Space's task assistant. 4. Paste the bot token and add the bot to the target group. Each Space can have only one task assistant, and it uses the same settings structure as an Agent duplicate: the Space row's **···** menu offers **Settings**, **Unbind**, and **Remove assistant**. **Settings** opens the same settings panel an Agent uses — computer and Runtime, default model, instructions, Skills, and more. **Description** and **Instructions** inherit the admin console's **Task assistant template** by default and sync automatically when the template changes; once edited on the assistant they are marked **Overridden** and keep their own value, and **Reset to inherit** returns them to the template. A shipped template (the built-in Telegram task-creation instructions) is provided out of the box, and organization admins maintain it on the admin console's **Task assistant template** page. ## How do you use it in Telegram? ### Direct messages Message the bot directly in Telegram to chat with the bound Agent. The first direct message creates the corresponding Agent session; later messages in the same chat continue that session. ### Mention the bot in a group @-mention the bot in a group with your question or instruction — this is the default trigger. The Agent's reply carries the chat context of nearby messages; a mention inside a topic (forum thread) is answered in that topic. ### Optional: reaction and message triggers In the Agent's integration settings you can turn each trigger on individually. Switch names follow the live page; the common ones are: - **Group mentions** (default); - **Emoji reaction trigger**: adding a chosen reaction to a message triggers the Agent with that message's surrounding context. Telegram only delivers reaction events to bots that are group administrators, so promote the bot first. The bot can only process messages received after the service started (up to 100 recent messages per chat, within 24 hours); for older messages it replies that it cannot read them; - **Any-message trigger**: every message in the selected groups triggers the Agent, with no mention needed. Privacy Mode must be off first (or the bot must be a group administrator); a group appears in the list only after the bot has been added and someone posts a message in it. You can also enable **Trigger on messages in forum topics**. Telegram does not support stopping a working Agent with a reaction; to stop it, click Stop in Sharkly. ### Start a fresh session with /new Use `/new` in a conversation with the bot to start a new Agent session without the previous context. ### Sending files Files in the Agent's replies return to the same Telegram chat: images are sent as photo messages and other files as documents; each file can be up to 50 MB and one reply can carry at most 10 files. Files beyond the limits are called out in the reply. ## Manage and disconnect The Telegram page lists connected bots with their bound Agent, groups, and current status, and lets you retry or disconnect. After disconnecting, that Agent no longer sends or receives messages through the bot; existing Sharkly sessions and history are not deleted. ## Connection states | State | Notes | | --------------------------- | ---------------------------------------------------------------------------------------------------------- | | Token rejected | Telegram rejected the bot token. Regenerate it via @BotFather and connect again. | | Message processing failed | A message that repeatedly fails is skipped so later messages are not blocked; ask the sender to resend it. | | Command menu publish failed | The `/new` command menu was not published to Telegram. Click **Retry** to publish it again. | ## FAQ ### The bot cannot see ordinary group messages. What now? Confirm Privacy Mode is off (@BotFather, /setprivacy, Disable) — the bot must be removed from the group and re-added for the change to take effect — or make the bot a group administrator. None of this is needed if you only @-mention the bot. ### The target group is missing from the group list? Add the bot to the Telegram group, then post a message in the group — the group then appears in the selectable list. Telegram does not let bots enumerate their groups; a message is the clue. ### Do Telegram messages become Sharkly Tasks? The Agent bot does not turn messages into Tasks by itself. To turn a group discussion into a Task, use the Space's task assistant: @-mention it in the group and it creates a Task from the chat context; you can then keep querying and updating Tasks in Telegram.