04 / Chat widget
Widget JavaScript API
Every configuration option and method of the Synaplan chat widget, with copy-ready examples.
On this page 5
Embed#
<script type="module">
import SynaplanWidget from 'https://web.synaplan.com/widget.js'
SynaplanWidget.init({
widgetId: 'YOUR_WIDGET_ID',
primaryColor: '#1a1ae8'
})
</script>
Replace YOUR_WIDGET_ID with the ID from Widgets in your Synaplan dashboard (it starts with wdg_). Options set in the dashboard apply automatically; options passed to init() override them on this page.
Configuration options#
| Option | Type | Default | Description |
|---|---|---|---|
widgetId |
string | required | Widget ID from the dashboard |
position |
string | 'bottom-right' |
bottom-right, bottom-left, top-right, top-left |
primaryColor |
string | '#007bff' |
Primary brand colour (hex) |
iconColor |
string | '#ffffff' |
Button icon colour |
buttonIcon |
string | 'chat' |
chat, headset, help, robot, message, support |
buttonIconUrl |
string | — | Custom icon URL (overrides buttonIcon) |
defaultTheme |
string | 'light' |
light or dark |
detectTheme |
boolean | false |
Follow the host page theme |
autoOpen |
boolean | false |
Open the chat on page load |
autoMessage |
string | 'Hello! How can I help you today?' |
Greeting message |
widgetTitle |
string | 'Chat Support' |
Chat header title |
messageLimit |
number | 50 |
Maximum messages per session |
allowFileUpload |
boolean | false |
Enable file uploads |
fileUploadLimit |
number | 3 |
Maximum files per message |
maxFileSize |
number | 10 |
Maximum file size in MB |
lazy |
boolean | true |
Load the chat UI on the first click |
fullscreenMode |
boolean | false |
Start in fullscreen |
allowFullscreen |
boolean | false |
Allow the fullscreen toggle |
hideButton |
boolean | false |
Hide the button (API control only) |
apiUrl |
string | auto | Override the API URL |
externalUserId |
string | — | Your own user ID, passed through to Synaplan |
privacyPolicyUrl |
string | — | Privacy policy link shown in the chat |
allowedDomains |
string[] | [] |
Restrict the widget to these domains |
JavaScript methods#
| Method | Description |
|---|---|
SynaplanWidget.init(config) |
Initialise the widget with a configuration |
SynaplanWidget.open() |
Open the chat panel |
SynaplanWidget.close() |
Close the chat panel |
SynaplanWidget.startNewChat() |
Start a new conversation |
SynaplanWidget.destroy() |
Remove the widget from the page |
Try open(), close() and startNewChat() live on the Inline Widget Demo.
Example: full configuration#
<script type="module">
import SynaplanWidget from 'https://web.synaplan.com/widget.js'
SynaplanWidget.init({
widgetId: 'wdg_095ab093966991158f9957f42ae8b4f2',
position: 'bottom-right',
primaryColor: '#1a1ae8',
iconColor: '#ffffff',
defaultTheme: 'dark',
autoOpen: false,
autoMessage: 'Hi! How can I help?',
messageLimit: 50,
allowFileUpload: true,
fileUploadLimit: 3,
maxFileSize: 10,
lazy: true
})
</script>
Example: programmatic control#
<button id="my-chat-btn">Chat with us</button>
<script type="module">
import SynaplanWidget from 'https://web.synaplan.com/widget.js'
SynaplanWidget.init({
widgetId: 'wdg_...',
hideButton: true
})
document.getElementById('my-chat-btn')
.addEventListener('click', () => SynaplanWidget.open())
</script>