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#

html
<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#

html
<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#

html
<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>