Telegram

The Telegram channel receives messages sent to a bot created with BotFather. Each inbox can route new conversations to an AI agent or leave them with human support.

SquadOS processes regular messages in private chats and groups: text, captions, photos, voice messages, audio, and documents. Channel posts, edited messages, videos, and stickers do not start processing.

Before connecting

You need a Telegram bot and the token issued by BotFather:

1. In Telegram, open @BotFather.
2. Send /newbot.
3. Provide a display name and a username ending in bot.
4. Copy the token returned by BotFather. Treat it like a password: anyone with this value can control the bot.

Also prepare the inbox destination:

• for AI support, the agent must be active;
• for human support, someone must monitor the inbox under Conversations.

The same bot cannot be connected to two active SquadOS inboxes at the same time, even if the inboxes belong to different organizations.

Connect through the inbox

1. In the admin panel, open Inboxes.
2. Click New inbox.
3. Choose Telegram — the option is described as Connect a bot created with @BotFather.
4. Paste the value into Bot Token and click Connect Bot.
5. After validation, click Continue.
6. Under Default destination, choose human support or an active agent.
7. Name the inbox and finish the wizard.

SquadOS first validates the token with Telegram and registers the webhook. The inbox is created only after Telegram accepts that external configuration. If the bot already belongs to another active inbox, disconnect it there before trying again.

Test incoming messages

1. Open the bot from the @username shown in the connection or search for that username in Telegram.
2. Start the private chat and send a test message.
3. Under Conversations, confirm that the message appeared in the correct inbox.
4. If the destination is an active agent, also confirm the reply in Telegram. If the destination is human, the conversation is created without invoking AI.

The /start command is a common way to start a private chat, but it is not required by the SquadOS pipeline: any regular message delivered by Telegram can be processed.

Using the bot in groups

Add the bot to the group. With Telegram’s default privacy mode, it may receive only commands, replies, and messages that mention it. If your operation requires every group message, change Group Privacy in BotFather (/mybots → bot → Bot Settings → Group Privacy) and validate the behavior in the group itself.

Everyone in a group shares the same Chat ID and therefore the same group identity and conversation in SquadOS.

Information and token changes

On the connected integration, open Information. The Telegram — Trigger information window shows the bot and lets you:

• open its @username in Telegram;
• reveal or hide the Bot Token;
• replace the token and Save.

The change is revalidated with Telegram. If it fails, treat the channel as unverified: restore a valid token and repeat an incoming-message test before resuming operation.

Send from an automation

The Chat ID is automatically stored as the contact identity when a message arrives through the bot. For an automation to talk to that contact, use Pick contact, Get the contact’s conversation, and Send message. The editor does not provide a generic field for pasting an arbitrary Chat ID.

See Telegram Chat IDs in SquadOS and Automation actions.

Disconnect

Disconnecting removes the bot webhook and removes the inbox from the active list. If it has no conversations, the inbox may be deleted; when history exists, it is retained as removed so conversation references remain intact. The token remains valid in Telegram until you revoke it in BotFather.

After disconnecting, send a new test message only after reconnecting and confirming the new inbox.

Common issues

• Failed to connect the bot. Check the token. — confirm that the complete value was copied and still belongs to the bot in BotFather.
• Bot already connected — the same @username belongs to another active inbox; disconnect that inbox before reusing it.
• Private message does not arrive — confirm that the chat with the bot was started and that the bot is not blocked.
• Group message does not arrive — confirm that the bot belongs to the group, mention it during the test, and review Group Privacy.
• Channel post or edited message does not appear — the current channel does not process these update types.
• The conversation appears but the AI does not reply — check the default destination and whether the assigned agent is active. A human-destination inbox does not invoke the agent.