Telegram

Telegram channel

Let people message your service desk through a Telegram bot. Each conversation becomes a ticket, and analysts answer from the same reply box they use for WhatsApp.

Contributed by Andrew Turbay (@turbay-a) in PR #159, and shipped in 2.10.0. How it works underneath, and what changed when it was merged: Telegram channel - Developer Guide.

---

Why Telegram

In much of the world Telegram, not WhatsApp, is how people message. And it is simpler to run than WhatsApp:

	Telegram	WhatsApp
Cost	Free	Per conversation (Twilio or Meta)
Getting started	A bot is live the moment @BotFather creates it	Business verification, a number, a provider account
Replying later	Any time - no window	Only within 24 hours of the customer's last message, then a pre-approved template
Who is writing	A chat number; the bot asks for their phone	Their phone number

---

Setting it up

You need two things: a bot, and an https:// address that Telegram can reach.

1. Create the bot. In Telegram, message @BotFather, send /newbot, and follow the prompts. It gives you a token like 123456789:AAH.... Keep it private - anyone with it can act as your bot.
2. Tickets → Settings → Messaging → Add channel. Choose provider Telegram.
   • Bot token: paste the token.
   • Secret token: click Generate. This is a password you choose, not something Telegram gives you. Telegram sends it back with every message, which proves the message really came from Telegram.
   • Company (multi-company installs): which company this bot's tickets belong to.
3. Save. The channel now has a webhook address.
4. Click Connect. FreeITSM tells Telegram to deliver this bot's messages to that address, with your secret token. Your bot token never leaves the server.

That's it - message your bot from Telegram and a ticket appears.

Telegram only delivers to https://. The Public base URL on the Messaging tab must be an https address that the internet can reach. Testing on a laptop? Run a tunnel such as ngrok http 80 and use the https address it gives you. The WhatsApp page has more on tunnels and self-hosting.

Test on the channel runs three checks: the bot token works, the webhook address is reachable from the internet, and a pretend message turns into a ticket (it is deleted again straight away, and nothing is sent to Telegram).

---

How conversations work

• A person's first message opens a ticket with the Telegram origin. Later messages go into their ticket for as long as it isn't closed, whatever its status (a status such as Resolved that doesn't count as closed keeps the conversation going). Once it is closed, the next message opens a new ticket.
• Each bot is its own conversation. If you run a bot per company, someone who messages two of them has two separate tickets, one in each company.
• No 24-hour window. You can answer a Telegram chat whenever you like.
• The bot speaks their language. The bot's own messages (asking for a phone number, saying thank you) are sent in the language their Telegram app is set to, when FreeITSM has it.
• Ratings. With Ask chat customers in their chat on (Tickets → Settings → CSAT), the satisfaction question arrives with buttons 1–5. Once one is tapped, the buttons are replaced by the answer: "You rated this 4 out of 5 - thank you."
• Pictures, documents, voice notes and videos they send arrive as attachments on the ticket, checked like any other attachment.

---

Who is this?

Telegram does not tell us a person's phone number or email. So:

1. Their first message is raised under a temporary contact named after their Telegram profile. The ticket is never held up.
2. The bot asks them, once, to tap Share phone number. That button hands over the number on their Telegram account, which Telegram has verified.
3. FreeITSM looks for that number in the phone and mobile fields of people in the bot's company:

What it finds	What happens
Exactly one person	The chat is linked to them. Its tickets from this bot move to them, and the temporary contact is removed.
Nobody	The temporary contact stays, and keeps the number in its mobile field.
More than one person (a shared switchboard number, say)	Nobody is guessed. The temporary contact stays.

Every outcome is written to the ticket's Audit window, for example Requester: Telegram chat 111 → Alice Real - matched by the phone number they shared.

Once a chat is linked to someone, it stays linked. If they share a different number later, nothing changes and nobody else's tickets are touched - the audit window just notes it.

Numbers must match digit for digit. Telegram sends international numbers (447700900123). A record written in national form (07700 900123) will not match, because turning one into the other needs the country. Storing numbers in international form (+44 7700 900123) gives the best results.

What the person sees is the same either way: a short thanks from the bot. It never says whether an account was found.

---

Sending files

On a Telegram or WhatsApp ticket, Attach in the reply box sends a picture or document to the customer. Anything typed in the box goes with it as a caption. The file is checked like any other attachment, keeps its name, and appears in the ticket's thread. If the provider refuses it, nothing is left behind in the thread.

---

Troubleshooting

Connect says "Telegram only delivers to an https:// address". Set the Public base URL on the Messaging tab to your https address (or tunnel), save, and Connect again.

Connect says "Authentication failed - check the Bot token". The token is wrong or was revoked. Get it again from @BotFather (/mybots → your bot → API Token), paste it, save, Connect.

Connect says to save first. You typed a new token or secret. Save the channel, then Connect - Connect always uses what is saved.

Messages don't arrive. Run Test on the channel. If reachability fails, Telegram cannot reach your address either. If you changed the secret token, click Connect again so Telegram has the new one.

The rating buttons shimmer and nothing happens. The bot was connected by a version before 3.1.0, which asked Telegram for messages only, so button presses are never sent to FreeITSM. Click Connect once more. Test on the channel tells you when this is needed. Presses made before that are lost; the customer just taps again.

Someone wasn't matched. Check their record holds the same number in international form, and that they are in the bot's company. If two people share the number, neither is matched on purpose.

---

Related

• Telegram channel - Developer Guide
• WhatsApp channel · Web chat · Slack