A Telegram chat widget is a chat button on your website that opens a conversation with your Telegram bot in one click. To add it with BotSailor:
- Connect your Telegram bot to BotSailor with a BotFather token.
- Go to Engagement → Chat Entry and click Create.
- Set the action to t.me short link and customize the logo, colours, messages, position and button.
- Build the bot flow so visitors get an opening message when they start the chat.
- Save everything, then click the Embed Code icon.
- Paste the JavaScript just before the closing
</body>tag, or use the direct Telegram link or QR code instead. - Test the widget in an incognito window on desktop and mobile.
A Telegram chat widget is a clickable chat button on your website. When a visitor clicks it, they start a conversation with your Telegram bot directly, without searching for the bot manually. In this guide, a local ice cream shop will add a Telegram chat widget for its website so customers can ask about flavours and orders through Telegram.
With BotSailor, you can customize the widget’s logo, welcome message, position, colours, button text, pre-filled message, and opening behaviour. BotSailor also gives you a JavaScript embed code, a direct Telegram link, and a QR code, so this Telegram widget for your website is a simple Telegram website integration that needs no coding apart from pasting one script.
Prerequisites
Before you add a Telegram live chat widget to your website, make sure you have the following:
- ● A BotSailor account.
- ● A Telegram bot created with BotFather and connected to BotSailor using its bot token. Once connected, the bot appears inside the Chatbot Manager.
- ● Access to your website’s HTML, so you can paste the embed code.
- ● The Telegram app or Telegram web, to test the widget.
Important
You must connect your Telegram bot to BotSailor before you create the widget. If you have not done this yet, Step 1 shows you how.
Step-by-Step Instructions
Here is the complete process at a glance:
Note
Chatbot Manager → Connect Telegram Bot → Select Bot → Engagement → Chat Entry → Create → Configure Action Button → Customize Chat Widget → Configure Bot Flow → Save Setup → Open Embed Code → Copy and Install Code
Step 1: Connect Your Telegram Bot to BotSailor
Open your BotSailor dashboard and go to the Chatbot Manager or Telegram bot connection section. Select an existing Telegram bot or connect a new one. To connect a new bot, follow these steps:
- 1 Open Telegram and search for BotFather.
- 2 Send the /newbot command.
- 3 Enter a name and username for your bot.
- 4 Copy the bot token provided by BotFather.
- 5 Return to BotSailor.
- 6 Open the Telegram bot connection section.
- 7 Paste the token and click Connect.
After the connection is successful, your Telegram bot should appear in the Bots/Accounts list. BotSailor uses the BotFather token to connect and manage the Telegram bot from its dashboard.
Step 2: Open the Telegram Chat Widget Section
After connecting the bot, open the BotSailor Chat Widget section.
- 1 Go to Chatbot Manager.
- 2 Select your connected Telegram bot from the Bots/Accounts list.
- 3 Open the Engagement tab.
- 4 Select Chat Entry.
- 5 Find the Chat Widget area.
- 6 Click the Create button in the upper-right corner.
This opens the visual flow builder, where you can configure the widget and its behaviour.
Step 3: Configure the Action Button
Inside the visual flow builder, set up how the chat button behaves.
- 1 Click the Actions node to open the Configure Action Button panel.
- 2 Under Action Type, select Actions → t.me short link.
The t.me short link action creates a direct link to your Telegram bot. When visitors click the chat button, Telegram opens through the app or web interface and starts the connected bot conversation. You can then configure the following settings:
- ● Upload your chat widget logo in PNG or JPG format.
- ● Choose the chatbox header background colour.
- ● Choose the chatbox header text colour.
- ● Enter a display name, such as Telegram Support.
- ● Write a short welcome message.
- ● Add a pre-filled message for visitors.
- ● Choose the widget position, such as Right Bottom.
- ● Decide whether the widget should open automatically.
- ● Adjust the horizontal and vertical offsets.
- ● Enter the button text, such as Start Chat.
- ● Customize the button background and text colours.
- ● Configure the hover colours and button size.
- ● Enter a unique reference name for the widget.
Here is the recommended widget content for this example. Display name:
Welcome message:
Pre-filled message:
Button text:
Position:
Reference:
Important
Use a short reference without unnecessary spaces. The reference helps you identify the widget later inside your BotSailor account.
Step 4: Configure the Telegram Bot Flow
After configuring the chat widget appearance, define what happens when a visitor clicks the widget and starts the bot. Click the connected Start Bot Flow node. The configuration panel will open on the left side. Use the following bot flow title, which is clear, professional, and easy to identify later:
You may also use a more specific title based on your business, such as:
In the bot-flow settings:
- 1 Enter the bot-flow title.
- 2 Configure any required labels, sequences, lists, or team assignments.
- 3 Add the first message visitors should receive.
- 4 Connect additional message nodes when more replies or options are needed.
- 5 Make sure the Action Button node is connected to the Start Bot Flow node.
- 6 Click Save Changes.
BotSailor’s visual Flow Builder lets you create chatbot conversations through connected nodes without requiring coding. Here is an example opening bot message:
You can follow this message with quick-reply options such as:
- ● Product Information
- ● Pricing
- ● Order Support
- ● Talk to an Agent
Step 5: Save the Complete Chat Widget Setup
Review all your settings before completing the widget. Make sure that:
- ● The correct Telegram bot is selected.
- ● The action is set to t.me short link.
- ● The logo and colours are correct.
- ● The welcome and pre-filled messages are added.
- ● The widget position is selected.
- ● The button text and colours are configured.
- ● A unique reference has been entered.
- ● The Action Button is connected to the bot flow.
- ● The bot-flow title and opening message are saved.
- 1 Click Save Changes inside each configuration panel.
- 2 Click the main Save button in the upper-right corner of the Flow Builder.
Important
BotSailor requires the configuration to be saved before the widget’s embed options can be used.
Step 6: Return to the Engagement Section
After saving the widget, return to your selected Telegram bot.
- 1 Go to Chatbot Manager.
- 2 Select your Telegram bot.
- 3 Open the Engagement tab.
- 4 Select Chat Entry.
- 5 Find your new widget in the Chat Widget list.
- 6 Under Actions, click the Embed Code</> icon.
Your newly created widget now appears in the list. You should see its unique ID, reference name, last updated date, and available action icons.
Step 7: Copy the Telegram Chat Widget Embed Code
When you click the Embed Code icon, a new window appears containing three options: JavaScript Embed Code, Telegram Link, and QR Code.
Option 1: JavaScript Embed Code. Copy the JavaScript code and paste it into your website’s HTML, preferably just before the closing </body> tag. BotSailor recommends this so the widget loads properly without delaying the main page content. Save and publish the page after installing the code. The code will look similar to this:
Important
Use the exact code generated inside your own BotSailor account. Do not copy the example code from another widget.
Option 2: Telegram Link. You can also use a Telegram widget without adding JavaScript to your website. BotSailor generates a direct Telegram link similar to:
You can place this link on a button, social media post, email, landing page, or digital advertisement.
Option 3: QR Code. The generated QR code can be used in:
- ● Printed flyers
- ● Business cards
- ● Product packaging
- ● Posters
- ● Event banners
- ● Social-media graphics
When someone scans it, Telegram opens the connected bot.
Step 8: Publish and Test the Widget
After adding the JavaScript code to your website:
- 1 Save or update the website page.
- 2 Clear the website cache, when applicable.
- 3 Open the website in a private or incognito window.
- 4 Confirm that the Telegram chat button appears in the selected position.
- 5 Click the button.
- 6 Check whether the welcome message and Telegram link work.
- 7 Test the widget on both desktop and mobile devices.
- 8 Send a test message and verify that the configured bot flow begins correctly.
Your Telegram chat widget is now ready to help website visitors contact your business through Telegram.
Success Verification
Your Telegram website integration is working correctly if the following are true:
- ● The Telegram chat button appears on your website in the position you selected.
- ● The widget shows your logo, display name, welcome message, and button text.
- ● Clicking the button opens your Telegram bot through the app or web interface.
- ● The opening message from your bot flow is received.
- ● The widget works on both desktop and mobile devices.
Remember
Always test in a private or incognito window after installing the code, so an old cached version of your page does not hide the widget.
Troubleshooting
The Telegram chat widget does not appear on my website
Possible cause: The embed code was not saved into the page, the page was not published, or the website is showing a cached version.
Solution:
- 1 Paste the JavaScript code into your website’s HTML, just before the closing </body> tag.
- 2 Save and publish the page.
- 3 Clear the website cache.
- 4 Reload the page in a private or incognito window.
The Embed Code options are not available
Possible cause: The widget configuration was not saved completely.
Solution: Return to the Flow Builder, click Save Changes inside each configuration panel, then click the main Save button in the upper-right corner. After that, open the widget again from Chat Entry.
The widget appears, but the bot flow does not start
Possible cause: The Action Button node is not connected to the Start Bot Flow node, or the flow was not saved.
Solution:
- 1 Open the widget in the Flow Builder.
- 2 Make sure the Action Button node is connected to the Start Bot Flow node.
- 3 Confirm the bot-flow title and opening message are filled in.
- 4 Click Save Changes, then the main Save button.
The widget loads the wrong bot or behaves like another widget
Possible cause: The embed code was copied from another widget or another bot.
Solution: Open Chatbot Manager → your Telegram bot → Engagement → Chat Entry, click the Embed Code icon of the correct widget, and paste the code generated there.
My Telegram bot is not available when I create the widget
Possible cause: The bot has not been connected to BotSailor yet.
Solution: Follow Step 1 to create the bot with BotFather, copy the token, and connect it in BotSailor. Then select the bot from the Bots/Accounts list.
Next Steps
Now that your Telegram chat widget is live, you can go further:
- ●Use the Telegram link: place the direct link on a website button, social media post, email, landing page, or digital advertisement.
- ●Use the QR code: add it to flyers, business cards, packaging, posters, event banners, or social-media graphics.
- ●Expand your bot flow: follow the opening message with quick-reply options such as Product Information, Pricing, Order Support, and Talk to an Agent.
- ●Customize the widget: adjust colours, position, button size, and messages at any time from Chat Entry.
