Integrations · Telegram

Use your Telegram bot in Tookan

Create your bot, connect it to Tookan, then receive contact messages and reply from their records.

All documentation

Before 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.

A contact message arrives in Tookan
Your Telegram bot

The contact writes in a private conversation with your bot.

The Tookan contact record

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.

  1. Open BotFather

    In Telegram, open the official @BotFather link below and press Start.

  2. Create your bot

    Send /newbot to BotFather. Choose a display name such as “My company — Tookan”.

  3. Choose its username

    Enter an available username ending in bot, such as mycompany_tookan_bot. Contacts can find your bot using this username.

  4. 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

  1. Open settings

    In Tookan, open Settings > Integrations > Telegram using an administrator account.

  2. Enter the token and destinations

    Paste the bot token, choose a reception mode as explained below, and select the applications that will receive messages.

  3. Save and check

    Click Save connection. The bot’s username and status appear on the screen. Use Check connection to review reception and processing.

FieldWhat to choose
Text destination *Choose an active application with a text question. The red star indicates that this choice is required.
Photo destinationOptional: choose an application with an image question.
Document destinationOptional: choose an application with a document question.
Voice message destinationOptional: choose the application that will receive audio files.
Do not import this typeKeep this selection for media types you do not want to receive.

Open Telegram settings

4. Choose message reception

Works locally

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.

Public HTTPS address

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

  1. In Tookan

    Create the link

    Open a saved contact record. In its Telegram panel, click Create linking invitation.

  2. 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.

  3. 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

Check connection and exchanges

7. Manage everyday exchanges

ActionWhat happens
Telegram notification: NoThe contact stays linked, but Tookan no longer sends notifications to this conversation.
The contact sends /stopThe contact disables Telegram notifications. /start enables them again for an already linked conversation.
The contact sends /helpThe bot displays its usage instructions.
Remove linkTookan detaches the conversation and cancels pending sends. Imported messages remain on their original contact record.
Disconnect botTookan 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.