#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?

#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

#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.