Use your Telegram bot in Tookan
Create your bot, connect it to Tookan, then receive contact messages and reply from their records.
All documentationBefore you start
You need a Telegram account, administrator access to Tookan and an active Tookan application with a text question. Each Tookan account uses its own bot. Contacts must open a conversation with the bot before you can send them messages.
1. Understand how it works
Your bot is your company’s contact point in Telegram. BotFather creates it; your customers then talk to your own bot.
The contact writes in a private conversation with your bot.
Once linked and processed, the message appears in the destination application and on the contact record.
Messages are not automatically matched by name or phone number.
- Texts, photos, documents and voice messages can be received depending on your chosen destinations.
- Sending a Tookan message automatically notifies the contact on their enabled channels: email, mobile push, WhatsApp and Telegram according to their settings.
2. Create the bot and obtain its token
@BotFather is Telegram’s official bot for creating and managing bots. The @ sign marks its Telegram username. The token is the key that authorises Tookan to use your bot.
- Open BotFather
In Telegram, open the official @BotFather link below and press Start.
- Create your bot
Send /newbot to BotFather. Choose a display name such as “My company — Tookan”.
- Choose its username
Enter an available username ending in bot, such as mycompany_tookan_bot. Contacts can find your bot using this username.
- Copy the token
BotFather sends a token: a long string containing a colon. Copy only that value into Tookan’s Bot token field.
3. Connect the bot in Tookan
- Open settings
In Tookan, open Settings > Integrations > Telegram using an administrator account.
- Enter the token and destinations
Paste the bot token, choose a reception mode as explained below, and select the applications that will receive messages.
- Save and check
Click Save connection. The bot’s username and status appear on the screen. Use Check connection to review reception and processing.
| Field | What to choose |
|---|---|
| Text destination * | Choose an active application with a text question. The red star indicates that this choice is required. |
| Photo destination | Optional: choose an application with an image question. |
| Document destination | Optional: choose an application with a document question. |
| Voice message destination | Optional: choose the application that will receive audio files. |
| Do not import this type | Keep this selection for media types you do not want to receive. |
4. Choose message reception
Periodic polling
Tookan regularly asks Telegram for new messages. Choose this for a local installation or when your Tookan address is not reachable from the Internet.
Webhook
Telegram sends each new message to an Internet-accessible address of your Tookan application. Tookan builds this address and registers it automatically when you save.
What is a Tookan HTTPS address?
It is the address of your Tookan application hosted on the Internet, starting with https://. A local address such as http://tookan.front.local cannot be used. You do not need to create a page. If the public address is not configured, ask your Tookan administrator to check it.
Does a webhook display messages immediately?
The webhook passes the message to Tookan as soon as Telegram receives it. Tookan then processes it for display on the record. Scheduled processing must be active in both modes; the local installation is scheduled every minute.
5. Link a conversation to a contact
-
In Tookan
Create the link
Open a saved contact record. In its Telegram panel, click Create linking invitation.
-
With your contact
Share the link
Send the link only to the intended contact through your usual channel. They open it in Telegram and press Start.
-
In Tookan
Check the link
Reload the contact record: the conversation is linked. Under Notifications, check that Telegram notification is Yes, then save the changes.
The contact wrote to the bot without an invitation. What should I do?
In Integrations > Telegram, find the conversation under Recent conversations. Search for their record by name or email, select it, then click Link contact after checking their identity. Waiting messages can then be imported. No contact record is created automatically.
How long are unlinked messages kept?
Data awaiting a contact link is retained for up to seven days. Imported messages follow Tookan’s usual retention.
6. Test your first exchange
- Send from Telegram
Using the linked contact’s Telegram account, send a short message to your bot. Allow scheduled processing to run, then refresh Tookan.
- Check Tookan
Find the message in the text destination and on the correct contact record. If photos or voice messages are enabled, test an example too.
- Send your Tookan message
Create and send your Tookan message as usual, or use Notify contact. When Telegram notification is Yes, Tookan automatically queues Telegram delivery alongside the other enabled channels.
- Check delivery
In Telegram monitoring, check that the message becomes Sent and confirm reception in Telegram. Sent means Telegram accepted the message; it is not a read receipt.
7. Manage everyday exchanges
| Action | What happens |
|---|---|
| Telegram notification: No | The contact stays linked, but Tookan no longer sends notifications to this conversation. |
| The contact sends /stop | The contact disables Telegram notifications. /start enables them again for an already linked conversation. |
| The contact sends /help | The bot displays its usage instructions. |
| Remove link | Tookan detaches the conversation and cancels pending sends. Imported messages remain on their original contact record. |
| Disconnect bot | Tookan disables the connection and cancels pending sends. Imported messages are kept. |
- Incoming files are limited to 20 MB and outgoing files to 50 MB; only supported file formats can be imported.
- Texts, photos, documents and voice messages are supported. Videos, stickers and group conversations are not imported by this integration.
- Album photos are handled as separate messages.
- The integration receives available new messages; it does not retrieve an account’s complete personal Telegram history.
8. Resolve common problems
The token is rejected.
Copy the value from BotFather again without adding spaces. If it was replaced or revoked, save the new token for the same bot in Tookan.
A destination application is rejected.
Check that it is active, belongs to your account and contains the expected question type: text, image or document.
No message appears.
Check that the contact is writing to the correct bot and the conversation is linked to their record. In Telegram monitoring, check Last reception and Last processing, then click Check connection. If there is no recent processing, ask your administrator to check the scheduled task.
Webhook mode does not work.
Check that Tookan has a public HTTPS address accessible from the Internet. Locally, choose Periodic polling. If another webhook is reported, check other uses of this bot before changing its connection.
A photo or document is not imported.
Check that the media type has a destination, the format is supported and the file is no larger than 20 MB. After correcting a destination, use Retry failed receptions in Telegram monitoring.
A message stays pending.
Check recent processing, the contact link and whether sends are enabled. Telegram may require a delay before the next attempt; Tookan waits automatically.
Monitoring shows Uncertain delivery.
The connection may have stopped after Telegram accepted the message. Check the conversation before sending again. Tookan does not retry this send automatically, to avoid a duplicate.
The contact no longer receives replies.
Check that Telegram sends are enabled on their record. If they sent /stop, they can send /start. If they blocked the bot, they must unblock it in Telegram.
The conversation is already linked to another record.
First check which record is correct. Remove the current link before linking again. Already imported messages are not automatically transferred to another record.