Telegram bot integration

Create a Telegram bot

1. Open Telegram and search for @BotFather.
2. Start a chat with BotFather and send /newbot.
3. Choose a display name and a username for your bot. The username must end in bot, for example AcmeSupportBot.
4. BotFather answers with an API token. Copy it, you need it in the next step.

Important: keep the token private. Anyone who has it can control your bot.

Connect the bot to Deskwoot

1. Go to Settings > Inboxes and pick Telegram under Add a channel.
2. Enter an Inbox Name and paste the token into Bot Token.
3. Click Create Inbox.

Deskwoot links the bot to Telegram right away. If Telegram does not accept the token, you see why and no inbox is created. The last step, Inbox Created, shows under Group messages whether the bot reads every message in groups (see below).

The agents you add under Collaborators in the inbox settings are the ones round robin hands its conversations to. See Auto assignment and round robin.

Private chats

When someone writes to your bot, the chat shows up as a conversation in your inbox, with that person as the contact. Your team answers in Deskwoot and the reply reaches them in Telegram. Your replies can carry text and files: images, videos, audio and documents. When Fynn answers, a line such as "Fynn, the AI assistant of Acme" stands above his first reply, see How customers see that Fynn is an AI.

Telegram only lets a bot write to people who started a chat with it, so the customer always writes first.

Telegram groups

Add your bot to a Telegram group and the group becomes one conversation in your inbox, with the group's name as the contact. Your customers and your own staff can all write there.

• Who wrote what. Every message shows the name of the member who wrote it. Click the name or the round picture next to it to open the member's card: their name, their @handle (a link to their Telegram profile) and their Telegram ID. The arrow next to the name opens their contact in a new tab.
• A contact for every member. Each person who writes in the group gets their own contact, the same one Deskwoot uses when they write to your bot in a private chat. On older messages a member may not have a contact yet. The card then offers Save as contact, which needs the permission to manage contacts (the standard Agent role has it).
• Reply to one message. Move the pointer over a message and click Reply. A bar above the reply box says Replying to Anna, and your answer arrives in Telegram as a reply to that message. Cancel reply (the x in the bar) removes it.
• Quotes from customers. When someone in Telegram replies to an earlier message, Deskwoot shows the quoted message above theirs. Click the quote to jump to it.
• Your AI bot only answers when asked. Your team sees every group message the bot receives, but Fynn answers only a message that mentions your bot (for example @AcmeSupportBot) or replies to one of Fynn's own messages. A reply to an agent's message does not count, even though agents answer through the same bot. No other automatic message, such as an out of office reply or a satisfaction survey, goes into a group.

Reply works in private Telegram chats too. In the iPhone and Android app, long press a message and pick Reply. Tap a member's name to see their details, with Open contact or Save as contact.

Let the bot read every group message

Telegram's privacy mode is on for a new bot. With it on, a bot in a group only receives messages that mention it, commands and replies to its own messages, so your team would miss most of the group. To receive every message, do one of these:

• Turn privacy mode off. In Telegram, open @BotFather and send /setprivacy. Pick your bot and choose Disable. Then remove the bot from each group and add it again, so the change applies there.
• Make the bot an admin of the group. Admins receive every message.

To see where your bot stands, go to Settings > Inboxes, click Configure next to your Telegram inbox and open the Configuration tab. Under Group messages it says Reads all group messages, or that only some group messages reach Deskwoot, together with the steps above. After you change the setting in BotFather, click Check again.

Telegram handles on contacts

A contact keeps its Telegram @handle under Social links on the contact page, with a button that opens the Telegram profile. When you pick a contact in the dashboard, for example for a new message or to merge two contacts, and in the contact search of the app, you can find them by their handle, typed with or without the @.

• When a contact has chatted with your bot or written in one of its groups, Telegram fills in the handle (if the person has one) and the Telegram ID. The field says Filled in from Telegram. and cannot be changed.
• Any other contact takes a handle you type into the Telegram field, also when you add a new contact. Save with Update contact. A handle has 5 to 32 letters, digits or underscores.

Troubleshooting

• Only some group messages arrive: privacy mode is still on, or the bot was not removed from the group and added again after you turned it off. See "Let the bot read every group message" above.
• No messages arrive at all: if you made a new token in BotFather after connecting (/revoke), the inbox stops receiving messages. The token of an existing inbox cannot be changed. Delete the old Telegram inbox under Settings > Inboxes (its conversations stay in Deskwoot) and connect the new token as a new Telegram inbox.
• "This Telegram bot is already connected to another Deskwoot inbox": Telegram sends a bot's messages to one inbox only. Remove the bot from that inbox first, or create a new bot with @BotFather.
• The bot was connected to another service before: a Telegram bot sends its messages to one webhook only. Connecting it to Deskwoot replaces the webhook of the other service, so that service stops receiving the bot's messages. If the other service sets its webhook again later, messages stop reaching Deskwoot.

Tips

• Give your bot a clear name that matches your brand, so customers recognize it.
• Set a description and a profile photo in BotFather with /setdescription and /setuserpic.
• Use labels and assignment to organize Telegram conversations next to your other channels.

Frequently asked questions

Why do I only see some group messages?

Telegram's privacy mode is on for your bot, so in a group it only receives messages that mention it, commands and replies to its own messages. Turn it off in @BotFather (/setprivacy, pick the bot, Disable), then remove the bot from each group and add it again. Or make the bot an admin of the group. Group messages in the inbox's Configuration tab shows the privacy setting; click Check again after a change. A bot that is an admin of a group receives every message there even while privacy mode is on. Messages from before the change do not come back.

Can I reply to one message in a group?

Yes. Move the pointer over the message and click Reply, or in the app long press it and pick Reply. Your answer arrives in Telegram as a reply to that message. This works for messages from customers and for your team's messages that went out, in groups and in private chats. If the message was deleted in Telegram in the meantime, your answer still goes out, just without the quote.

How do I see who wrote a message in a group?

The member's name stands above each of their messages. Click it to open their card with their @handle, their Telegram ID and the arrow that opens their contact. In the app, tap the name.

Does every group member become a contact?

Every person who writes in the group does, and it is the same contact Deskwoot uses when they write to your bot directly. Other bots and admins who write anonymously as the group get no contact. Older messages may show Save as contact on the member's card instead.

Does Fynn answer in Telegram groups?

Only when a message mentions your bot or replies to one of Fynn's own messages. Everything else in the group reaches your team without an automatic answer. In a private chat Fynn answers as on your other channels.

Can I see a group member's phone number?

No. Telegram never gives a member's phone number to a bot. A phone number only shows when the member's contact in Deskwoot already has one.

Which kinds of messages come through?

Text, photos, videos, audio files, voice messages and documents, with their captions. Stickers, locations, polls and round video messages do not reach Deskwoot, and a message someone edits later in Telegram does not change in Deskwoot. Your replies can include text, images, videos, audio and documents. Voice messages and audio files are transcribed automatically, so Fynn can answer them and your team can read them, see Fynn and voice messages.

What if a reply does not reach the customer?

The reply shows Delivery failed. with Telegram's reason, for example when the customer blocked the bot. When your text arrived but a file did not, one click sends only the missing file again, see When a reply is not delivered.

Is there a cost per Telegram message?

No. Telegram does not charge for its bot API. When Fynn answers, it counts as an AI conversation in Deskwoot, the same as on every other channel.

How do I create a Telegram bot?

Open Telegram, search for @BotFather, send /newbot and follow the prompts. At the end BotFather sends you an API token. Paste it into Deskwoot.

What if my bot username is taken?

Telegram bot usernames are unique and end in "bot". Try a variation such as AcmeSupportBot, AcmeHelpBot or AcmeChatBot and take one that is free.

Can I connect several Telegram bots?

Yes. Each bot becomes its own inbox, which helps with separate brands, product lines or languages. One bot can only be connected to one Deskwoot inbox.

What if I make a new bot token after connecting?

The inbox stops working with the old token, and the token of an existing inbox cannot be changed. Delete the old Telegram inbox under Settings > Inboxes (its conversations stay in Deskwoot), then connect the new token as a new Telegram inbox. Use /revoke in BotFather only when you really need to.

Can the bot start a conversation on Telegram?

No. Telegram requires the person to write to the bot first. After that your team can answer them at any time, with no time window.

Will old Telegram messages be imported?

No. Telegram does not give bots the messages from before they joined a chat. Only messages sent after you connected the bot (and, in a group, after the bot was added) show up in Deskwoot.

What if the bot stops working?

The usual causes are a revoked token, a bot deleted in BotFather, or a bot that Telegram blocked for breaking its rules. Check your bot under /mybots in BotFather. If you make a new token, connect it as a new Telegram inbox as described above.

Can I change the bot's profile picture and description?

Yes, in BotFather with /setdescription, /setuserpic and /setname. People see them when they first open your bot.