Chat Widget
The Chat Widget settings (titled Live Chat Appearance in the app) let you install Flowcall's chat widget on your website and control how it looks and greets visitors. Use this page to get the embed snippet and to tune colors, copy, and branding.
A live preview on the right updates instantly as you edit. Your appearance changes are staged: a Save Changes bar appears at the bottom whenever you have unsaved edits, and nothing is published until you click it. Discard reverts to the last saved version. A few actions — generating a token, uploading a logo, and Reset to Default — act on their own.
At the top of the page:
- Copy Chat Widget URL / open link — once a token exists, copy a hosted widget URL (or open it in a new tab) to share the chat directly without embedding.
- Reset to Default — restores all widget customizations to their defaults and deletes any uploaded logos. You're asked to confirm; this can't be undone.
Website integration
This card gives you what you need to embed the widget on your site.
-
Public Access Token — a token accepted only by the embedded chat widget APIs. If none exists yet, click Generate Token to create one. Once generated, use the copy button to copy it.
-
Website install snippet — expand this to see a ready-to-paste
<script>snippet with your account ID and token already filled in. It has two tabs:- HTML — a
<script>tag to paste just before your page's closing</body>tag. - JavaScript — the same loader without the
<script>tag, for adding to your site's own JavaScript bundle or script file (for example in a single-page app).
Copy Code copies the snippet from the selected tab.
- HTML — a
JavaScript SDK in a website or app WebView
Open Settings → Chat Widget → Website Integration → Website install snippet and copy the HTML or JavaScript tab for the selected brand account. The snippet loads the browser UMD bundle from:
https://storage.googleapis.com/ai-chat-1c879.appspot.com/public/chat-widget.umd.js
It resolves the constructor as window.Fc.ChatWidget, with window.ChatWidget.ChatWidget as a fallback. Use the account ID and Public Access Token from that account's snippet. Do not put the separate secret API access token from Integrations & API in a website or app.
The SDK runs in a browser document. In a native app, load it in an app-owned HTML page inside a WebView with JavaScript enabled. Add the supported customer identifier to the constructor options within the copied loader (the snippet includes a commented-out phone line to fill in):
var widget = new ChatWidgetConstructor({
accountId: 'YOUR_ACCOUNT_ID',
authToken: 'YOUR_PUBLIC_WIDGET_TOKEN',
phone: '+12025550123', // synthetic example; supply the signed-in user's phone
onMessageReceived: function (message) {
if (message.isIntermediate) return;
// App-owned integration: replace with your WebView bridge or badge handler.
handleChatReply({
messageId: message.messageId,
text: message.message && message.message.body,
type: message.type,
createdAt: message.createdAt,
});
},
});
handleChatReply is an application function you implement, not a Flowcall SDK method. Install your WebView bridge before creating the widget, then use this callback to forward a reply to the app. The app decides whether to show a badge or trigger its own local notification. You can call widget.open() to open the chat.
Send a customer message from your app
The install snippet stores the widget instance as window.fcChatWidget. Call window.fcChatWidget.sendMessage(text) to send a customer message from a button or another action in your website or app. For example, a Track this order button on an order detail screen can send the order ID so the customer does not need to type it:
// `window.fcChatWidget` is set by the install snippet once the bundle loads.
document.getElementById('track-order').addEventListener('click', async function () {
if (!window.fcChatWidget) return; // the widget bundle hasn't loaded yet
var sent = await window.fcChatWidget.sendMessage('Track order ID ABCD');
if (!sent) {
// Let the customer complete any required details, then retry the action.
console.log('Message could not be sent. Check the chat and try again.');
}
});
sendMessage(text) opens the chat automatically, waits for widget settings and chat initialization, and sends the text as the current customer in the current conversation. The message appears in the chat and triggers onMessageSend, just like a typed message. window.fcChatWidget exists only after the bundle loads and the snippet constructs the widget, so check for it before calling. If you assign the instance elsewhere, keep that reference instead. You can call the method immediately after constructing the widget.
The returned Promise<boolean> resolves to true when the server accepts the message; it does not wait for an AI or team reply. It resolves to false for empty text, missing send configuration, a destroyed widget, a failed send, or when the chat is blocked by required customer details or is starting a new session. A blocked message is not queued or automatically resent: complete the required details and invoke the action again. Failed requests appear with a failed status in the chat. onMessageSend fires when the message is added, before server acceptance.
Use the updated widget bundle containing sendMessage; update any self-hosted or cached copy. This method is available on a JavaScript SDK instance in the same document. A parent page embedding the hosted widget in an iframe does not have direct access to that instance.
Hosted URL and iframe
Use Copy Chat Widget URL at the top of Settings → Chat Widget. The URL includes the selected account's public widget token:
https://dashboard.flowcall.co/chat/YOUR_ACCOUNT_ID?accessToken=YOUR_PUBLIC_WIDGET_TOKEN
Open it directly in an app WebView, or embed it in a web page:
<iframe
title="Customer support"
src="https://dashboard.flowcall.co/chat/YOUR_ACCOUNT_ID?accessToken=YOUR_PUBLIC_WIDGET_TOKEN&phone=%2B12025550123"
style="width: 100%; height: 100dvh; border: 0"
></iframe>
The phone is synthetic. Construct dynamic URLs with URL and URLSearchParams so + and other special characters are encoded correctly:
var chatUrl = new URL('https://dashboard.flowcall.co/chat/YOUR_ACCOUNT_ID');
chatUrl.searchParams.set('accessToken', 'YOUR_PUBLIC_WIDGET_TOKEN');
chatUrl.searchParams.set('phone', '+12025550123');
// Use chatUrl.toString() as the WebView URL or iframe src.
The hosted page opens the widget automatically. It does not expose onMessageReceived to the enclosing app or iframe parent and does not forward replies through postMessage. For client-side callbacks, use the SDK in an app-owned page. For a hosted URL integration, use the notification webhook to notify your backend.
Supported customer identifiers and authentication
| Identifier | SDK option | Hosted URL parameter | Behavior |
|---|---|---|---|
| Phone | phone | phone | Sends a customer phone during chat initialization. Prefer an international number with country code. |
| Shopify customer ID | shopifyCustomerId | shopifyCustomerId (legacy alias: customerID) | Looks up a Shopify-linked customer. Use only when applicable to your account and customer. |
| No direct constructor option | No supported email parameter | Email can be collected through the configured Customer Details Form; it cannot currently be passed directly during SDK or hosted-page initialization. |
Phone and Shopify customer ID identify or match a customer record; they are not proof of customer authentication. The public widget token authorizes the account's widget APIs, not the signed-in user's identity. This integration has no documented customer identity signature, HMAC, or SSO token option. Passing a phone does not bypass an OTP step required by your support workflow.
The Customer Details Form omits fields already present on the resolved customer and may still request missing required fields. A supplied phone can therefore avoid asking for that phone again, but does not guarantee that every form or workflow question disappears. Existing browser/WebView chat cookies are restored first, before matching supplied identifiers. Do not assume that changing phone with updateConfig switches users; verify logout, account changes, and WebView cookie isolation in your app.
For sensitive account or order actions, keep the workflow's identity verification. If you need email initialization or trusted sign-in handoff, agree that integration with Flowcall before relying on it. Avoid recording customer identity URLs in analytics or logs.
Development and testing
The SDK accepts env: 'prod', env: 'dev', or env: 'testing'; the hosted URL accepts the same values as env. Omitted env uses production behavior. staging is not a supported value. The non-production values create tester conversations and select development or draft instructions; they use the same service endpoints and public widget token. They do not establish a separate staging deployment or change external integration credentials.
Confirm the intended brand account and test setup before testing. Do not label a production snippet as a staging script just because it runs on a staging website. The AI and instruction notification paths exclude tester conversations, so they are not a complete end-to-end notification webhook test.
Listening for chat messages
Bundle version requirement: Use the current public UMD bundle for onMessageReceived. If you self-host or cache a copy of the widget bundle, update that copy before relying on this callback.
The widget can notify your page's JavaScript when messages are sent or received — for example to show a badge, send an analytics event, or trigger your own notification. Add either callback to the options passed to ChatWidget in the install snippet (both snippet tabs include a commented-out onMessageReceived example):
var widget = new ChatWidgetConstructor({
accountId: 'YOUR_ACCOUNT_ID',
authToken: 'YOUR_PUBLIC_WIDGET_TOKEN',
onMessageReceived: function (message) {
if (message.isIntermediate) return; // skip interim "searching..." replies
console.log('New message:', message.message && message.message.body);
},
onMessageSend: function (message) {
console.log('Visitor sent:', message);
},
});
onMessageReceived— called once for each new reply from your AI agent or team. It isn't called for chat history loaded when the widget opens or for the welcome message. Interim replies (such as Searching products…) are included withisIntermediate: true, so you can ignore them if you only want final replies.onMessageSend— called when the visitor sends a message, attachment, or form response.
Both callbacks receive a message object. Useful fields include messageId, type (such as text, image, or document), message.body (the text), from, and createdAt. Media data may be in image, video, or document; text may be absent. This is a chat message payload, not the notification webhook's customer identity payload. In particular, do not rely on it to contain a customer email or phone: socket replies currently set phone to an empty string. Associate the callback with the app's current customer session yourself.
onMessageReceived runs when the widget processes a new socket reply or recovers a new agent message by polling. Messages already in that widget instance are deduplicated by messageId; this is not a durable exactly-once guarantee across reloads or devices. A throwing onMessageReceived callback is logged without breaking message rendering.
The callback can run while the launcher is closed, provided the page and socket are still active. Background or suspended WebViews may delay it; reconciliation runs on reconnect and when the page becomes visible. Neither callback registers browser push notifications or native background delivery. For notifications while the WebView is inactive, route the notification webhook to your backend and use your app's push service. If you use both callback and webhook paths, decide in your app/backend how to avoid duplicate alerts.
Position
- Position — which corner of the page the widget sits in: Bottom Right, Bottom Left, Top Right, or Top Left.
Corners
- Corners — the edge style for the widget's surfaces and controls: Rounded (soft corners) or Flat (square edges).
Colors
- Primary Color — used for the header, buttons, and the visitor's own messages. Set it with the color picker or by typing a hex value.
- Accent Color — used for highlights, icons, and interactive elements. By default it's locked to your primary color and generated from it automatically. Click the lock button to unlock and set a custom accent; relocking regenerates it from the primary color.
Header
- Title — the widget's header title (e.g. Chat Support).
- Subtitle — a short status line under the title (e.g. Online).
- Brand Logo — an image shown as the header avatar. PNG is recommended; it's resized to 64×64px. Upload, change, or remove it.
Welcome message
- Message — the first message visitors see when they open the chat.
- Quick Reply Buttons — suggested responses shown as tappable buttons. Type button text and press Enter to add each one; remove one by clicking its tag.
Customer details form
Collects visitor identity within live chat. Toggle the card on to enable it, then configure:
- Ask for details — when the form appears: Before visitor can chat or After first visitor message.
- Form title and Form subtitle — the heading and explanatory text shown above the form.
- Fields — for Name, Email, and Phone, choose whether each is Shown and whether it's Required. At least one field must stay enabled.
- Contact method — either Optional, or Either email or phone required (which forces both email and phone to be shown so the visitor can supply one).
When the details match an existing customer, the visitor continues as that customer, for example after switching to a new device. If their first message is only a greeting and they have no task in progress and no open ticket, they see the welcome message and its buttons again. Otherwise the conversation carries on where it left off.
Widget button
- Icon Style — the floating launcher icon that opens the chat: Chat Bubble, Message, Support, or Custom Logo.
- Custom Logo — shown only when Icon Style is Custom Logo. Upload your own launcher image (PNG recommended, resized to 64×64px); change or remove it as needed.
Branding
- Show Branding — shows or hides the widget footer text, including any custom text.
- Custom Footer Text — when Show Branding is enabled, enter your own text to replace 'Powered by Flowcall'. The text appears in the live preview and the widget footer. Leave it blank to use the default Flowcall branding. Custom footer text is displayed as plain text, without links or HTML formatting.
Saving
Edit freely and watch the Live Preview update in real time. When you're happy, click Save Changes in the bar at the bottom to publish, or Discard to revert to the last saved version.