Embed Web Chat on Your Site

Guide

1. 1

   Add a web chat bot

   Open your application and add a bot, then choose Web Chat as the platform.

   Unlike Telegram, there is nothing to request and nothing to paste. There is no BotFather step, no token, and no approval. The bot exists as soon as you create it.

   While creating it, you can set the display name shown in the widget header and a welcome message that sends itself when someone opens the chat for the first time. Both can be changed later.

2. 2

   Open the Install tab

   Go to the bot settings and open the Install tab. This tab appears only for web chat bots.

   You will find three ready-to-use options here, and a few settings worth filling in before you publish:

   • Display Name — the name in the widget header
   • Welcome Message — sent automatically when the chat is first opened
   • Notification Message — a dismissible banner under the header, with a setting for whether it shows once ever or once per new device
   • Share Message — the text pre-filled when someone shares your chat link
   • An option to open the chat automatically when the bot sends a new message, instead of only showing an unread badge
3. 3

   Choose how it appears on your site

   Option A — the floating bubble (most sites want this)

   Copy the JavaScript Widget snippet with Copy JS snippet and paste it before the closing </body> tag of your site. It looks like this:

   <script>
     (function() {
       var s = document.createElement('script');
       s.src = 'https://dashboard.flowcastle.ai/webchat-widget.js';
       s.setAttribute('data-bot-api-key', 'YOUR_BOT_API_KEY');
       s.setAttribute('data-api-base-url', 'https://dashboard.flowcastle.ai');
       document.head.appendChild(s);
     })();
   </script>
   

   This puts a chat button in the bottom-right corner of every page the snippet appears on.

   Copy the snippet from the Install tab rather than from this page. The real one already contains your bot key, and if you have connected a custom domain it points at your domain instead of ours.

   Option B — an inline frame

   Use Copy iFrame snippet when the chat should sit inside the page — on a support page, for example — instead of floating over it:

   <iframe
     src="https://dashboard.flowcastle.ai/webchat/YOUR_BOT_API_KEY?embedded=1"
     style="width:480px;height:600px;border:none;"
     allow="notifications"
   ></iframe>
   

   The width in the snippet follows the Embedded width setting on the Appearance tab (360, 480, 600, 800 pixels, or full width), so set that first and copy the snippet afterwards.

   Option C — a standalone page

   Every web chat bot has its own full-screen address, shown as Standalone Chat URL. Nothing to install: link to it from an email, a button, or a QR code.

   That page can also be installed as a web app, so a visitor can keep it on a phone home screen and receive push notifications. You can set the page title and meta description for it on the same tab.

4. 4

   Make it look like your site

   Open the Appearance tab. You can set:

   • Light, dark, or automatic colour mode
   • Accent colour, user and bot message colours, chat background colour or background image
   • Bot avatar and favicon
   • Popup width for the floating widget, and the embedded width used by the iframe snippet
   • Corner radius

   Changes apply to the live widget — you do not need to paste the snippet again after changing the design.

5. 5

   Test it

   Open the standalone chat URL in a private browser window. A private window matters: your normal browser remembers you as a returning visitor, so you would not see what a first-time visitor sees.

   Check that the welcome message arrives, buttons respond, and any human handoff step opens a conversation in your inbox.

   Optional: use your own domain

   By default the widget loads from FlowCastle. To serve it from your own subdomain instead, enter the hostname — for example chat.example.com — on the Install tab, create the CNAME record shown, then click Verify DNS and TLS.

   Two things to know:

   • Subdomains only. An apex domain such as example.com cannot be used.
   • DNS and certificate issuance can take up to 24 hours, though it is usually much faster. Use the verify button to check the current status.

   One custom domain per bot; setting a new one replaces the previous one.

   Things that behave differently from Telegram

   • Payments do not run in web chat. A flow step that takes payment works in Telegram, not in the widget. Link website visitors to your existing checkout instead.
   • Telegram Mini App buttons are ignored by the widget.
   • The floating button position is fixed at the bottom-right corner.
   • Visitors can upload photos and files up to 50 MB.

   What to read next

   The Web Chat Widget page explains how one flow serves both Telegram and your website. If you have not built the flow itself yet, start with How To Add Your First Node.