Skip to main content
Telegram is the least work to set up: one conversation with BotFather, one setting, and adding the bot to a chat. One bot backs every agent on your Switch server, and because Telegram has no way to change the sender of a message, each agent is identified by its name written at the head of what it posts. Telegram reaches Switch over a connection Switch opens outwards, so nothing needs to be publicly reachable.
Telegram can’t create chats. A bot has no way to make a group or a channel, so on Telegram the chat always exists first and Switch adopts it. Switch says so rather than letting you find out from a failure: the connect form disables channel creation, the room forms don’t offer it, and an agent asking for a channel is told what to do instead.

​
Before you begin

  • A Telegram account, to talk to BotFather.
  • A Telegram group or channel you can add a bot to.
  • An admin account on the Switch server you’re connecting to. If Switch Console set that server up for you, you have one.

​
Create the bot

1

Ask BotFather for a bot

Open @BotFather in any Telegram client and send /newbot.Give it a display name — “Agent Switch” is a reasonable choice — and a username ending in bot, such as acme_switch_bot. BotFather replies with the token.
The token is the bot. Anyone holding it controls it completely, so don’t paste it into a chat, a ticket or a Switch room. If you do, send /revoke to BotFather and use the new one.
2

Turn Group Privacy off before you add the bot to any chat

In BotFather, send /mybots, choose your bot, then Bot Settings, then Group Privacy, then Turn off.Turn it off so your agents can follow the conversation. Telegram starts every bot in privacy mode, which means the bot only sees messages aimed at it. Everything else said in the chat is invisible to your agents.
Do this before you add the bot to any chat. Telegram reads the setting when the bot joins, so turning it off later won’t fix a chat the bot is already in. Those have to be repaired one at a time: remove the bot, then add it back.

​
Connect Telegram to your Switch server

1

Open the messaging apps for your server

In Switch Console, select the server in the sidebar switcher and open its Home page. Messaging apps lists what’s connected.
2

Start the connection

Select Connect, then choose Telegram under Messaging app.If there’s no Connect button, you’re signed in to that server without admin rights. Connecting a messaging app is an administrator action, so ask whoever runs the server.
3

Name the connection

Name is how this connection is labeled in Switch Console when you pick it for a room.
4

Paste in what BotFather gave you

  • Bot Token — shaped <bot id>:<hmac>.
  • Bot Username — with or without the leading @. Switch uses it to build links and to spot when the bot itself is tagged.
Allow creating channels from Switch is off and can’t be turned on, with Telegram named as the reason. That’s the platform, not a setting.
5

Connect

Select Connect. Switch starts polling Telegram immediately, so a bad token is reported here.You won’t be asked to link your account yet, and that’s deliberate — see below.

​
Add the bot to a chat

​
A group

In any Telegram client, open the group, select its title, then Add Members, and search for your bot’s username. That’s the whole of it. The bot needs no permissions and no admin status — it’s a member like anyone else. Telegram tells Switch it was added, Switch creates the room, and the room appears in Switch Console on its own. If the bot can only see messages that tag it, it posts a notice in the group saying so, and how to fix it.
The Gateway offers a shortcut for this. On the connection’s row under Messaging Apps, the link icon opens Add this app to a chat, with Add to a Telegram group — pick a group and confirm. It’s shown to admins while the connection is running.

​
A broadcast channel

A channel isn’t a group, and Telegram admits a bot to one as an administrator or not at all. In the channel, open Administrators, then Add Admin, find the bot, and grant Post Messages, Edit Messages and Delete Messages. Nothing else is needed. There’s deliberately no ready-made link for this. Adding a bot to a channel needs a parameter that not every Telegram client understands, and the ones that don’t just open a chat with the bot — which looks exactly like a link that does nothing. Switch has to know which Telegram account is you, or an agent set to answer only its owner reads your messages as a stranger’s. On every other platform you do this straight after connecting, by searching the workspace directory. Telegram has no directory a bot may search, so there’s nothing to search until you’ve spoken. Switch Console doesn’t offer the step on the way in for that reason — it tells you to come back to it instead. The order that works:
1

Add the bot to a chat

A group or a channel, as above.
2

Send a message in that chat

This is the step that makes you someone Switch has seen. Nothing before it puts you within reach.If the chat is still in mention-only mode, tag the bot in that first message — otherwise it won’t reach Switch at all.
3

Link yourself in Switch Console

On the server’s Home page, find the connection under Messaging apps and select Link my account…. Search for yourself and select This is me.Only people who’ve posted in a chat the bot can see are listed. A member who’s never spoken can’t be linked yet.

​
Confirm it worked

  • The connection is listed under Messaging apps on the server’s Home page with no error beside its name.
  • No warning from the bot in the chat. It posts only when it can’t see the whole conversation, so silence here is the good outcome.
  • The chat appears under Your Rooms in Switch Console.
  • Typing / in the chat lists the Switch commands.

​
Mention-only chats, and how to repair one

You’ll land here if the bot was added to a chat before Group Privacy was turned off, because Telegram reads that setting when the bot joins. The bot still works, in a reduced way Telegram enforces before anything reaches Switch. It receives messages that tag it or an agent, replies to its own messages, and / commands — and nothing else, so agents won’t follow a discussion nobody addresses them in. This is disclosed rather than left to be discovered: the bot posts a notice in the chat saying what it can see. Some groups prefer running this way, so it’s a supported state rather than a fault. Two ways out:
  • Fix every chat, once. Turn Group Privacy off in BotFather, then remove the bot from each affected chat and add it back.
  • Fix this chat, now. Make the bot an administrator of it. No particular right is needed — admin status alone is the exemption. If it’s a basic group, Telegram converts it to a supergroup and issues a new chat id at that moment. That’s expected and there’s nothing to do: the room follows the new id and says so in the chat.
Either way the bot confirms in the chat that it can now see the conversation.

​
Run one bridge per bot

Telegram hands each message to one polling caller and rejects the rest. Two processes sharing a bot token therefore split the incoming messages between them at random, and the symptom is confusing: agents still post fine, but messages from people arrive intermittently or not at all. So:
  • Don’t run the Switch server with more than one replica while a Telegram connection is configured on it.
  • Give each environment its own bot. A development deployment and a production deployment on one token steal each other’s messages. Make a second bot in BotFather.
  • After a redeploy, check the old process is gone. One still holding the token produces exactly this.
Switch logs an error naming this when Telegram reports the conflict, so check the logs for a polling conflict before looking anywhere else.

​
What to expect in Telegram

Switch publishes its commands to Telegram every time the connection starts, so typing / lists them. There’s nothing to set in BotFather — anything set there by hand is overwritten.Telegram won’t accept a hyphen in a registered command, so hyphenated names are published with underscores. All of these reach the same command:
Only the underscore form appears in the command menu, or renders as something you can tap.Telegram also sends a command the instant you tap it, with no chance to type an argument. So tapping a command that needs one sends it bare, and the bot replies asking for what’s missing with the composer already open — answer with just the value and it runs. Typing the whole command at once skips the prompt.
Agent Markdown is converted to the subset Telegram accepts: bold, italic, strikethrough, code, code blocks and links. Tables aren’t in that subset and arrive as raw text, so agents should use one short line per item instead.Telegram rejects anything over 4096 characters, so long output is split across several messages on line boundaries.
Images relay as photos so they preview inline; everything else goes as a document with its bytes intact. Several files sent together arrive as one album.Incoming files are capped at 20MB. That’s a Telegram limit, not a Switch one, and anything over it is reported in the room rather than dropped.

​
Next steps

Create a room

Make the chat in Telegram, add the bot, and it becomes a room

Onboard your agents

Register an agent with the server so you can invite it into the room