Website Integration

syrup widget can be embedded into any website by inserting a <script> tag in the HTML <head> section as follows:

<script async src="https://tastesyrup.com/syrup.js"
  data-id="syrup"
  data-token="SYRUP_TOKEN"
  data-autorun="true"
  data-button-position="right-bottom"
  data-button-lefttext="LIVE"
  data-button-righttext="ASSISTANCE"
  data-button-showicon="true"
  data-request-userinfo="true"
  data-show-pin="true">
</script>

The async attribute makes the website load faster by asynchronously retrieving the syrup script.

Settings

data-id

Must be “syrup”. Required for internal purposes.

data-token

A string token that identifies a specific syrup widget (obtained when the widget is created). Required.

data-autorun

Whether the widget should automatically run upon page load. If “false” the website is responsible of running it by calling syrup.run() (see below).

When “true”, syrup automatically displays a built-in main button (the button the user must click to open the chat).

By default it is “false”.

data-button-position

The position of the built-in main button. Valid values are “right-bottom” (default value) and “right-center”.

data-button-lefttext

The text at the left side within the built-in main button. If not set, it defaults to “LIVE”. It can be hidden by setting an empty string as value.

data-button-righttext

The text at the right side within the built-in main button. If not set, it defaults to “ASSISTANCE”. It can be hidden by setting an empty string as value.

data-button-showicon

Whether the built-in main button should display a small “chat” icon. It defaults to “false”.

data-request-userinfo

Whether user name and email must be requested before the user can start a chat. It defaults to “true”.

data-show-pin

Whether support PIN must be shown. Useful if there is an already ongoing support session by other means (for example, a phone call) while the customer is visiting the website. By sharing this PIN with the agent by phone, the agent can initiate a syrup chat with the customer.

It defaults to “false”.

JavaScript API

More granular features can be obtained by using the provided JavaScript API. The API allows the web developer use his own button to open the widget, preset user information (name, email), etc.

Once the syrup script is loaded, the web developer can access it via window.syrup.

Methods

syrup.run([options])

NOTE: This method should just be used when data-autorun is “false” (otherwise it does nothing).

When run() is called the widget machinery is initiated. options is an optional object with the following fields:

  • name: Sets the user name (so the visitor does not need to enter it). This is ignored if email is not given.
  • email: Sets the user email (so the visitor does not need to enter it). This is ignored if name is not given.
  • useDefaultButton: Whether the syrup built-in main button should be displayed. If not set to true, the website is responsible for calling syrup.open() (see below) in order to open the chat and provide its custom main button if desired. If an object is provided, the built-in main button will be displayed by overriding the script data-xxxx attributes with the following properties:
    • position: “right-bottom” or “right-center”.
    • leftText: The text at the left side.
    • rightText: The text at the right side.
    • showIcon: Boolean indicating whether to show or not a small “chat” icon.
  • requestUserInfo: Boolean indicating whether user name and email must be requested.
  • showPin: Boolean indicating whether the support PIN must be shown.
  • sidepanel: If set, the widget chat will be placed in the given HTMLElement (rather than floating over the entire website).
syrup.run({
  name      : 'Peter Smith',
  email     : 'peter.smith@gmail.com',
  sidepanel : document.getElementById('right-panel')
});

syrup.open()

NOTE: This method should just be used when data-autorun is “false” or syrup.run() is called without options.useDefaultButton set to true.

Call open() to open the chat. This is useful if the website application provides its own “chat with us” main button.

<button id="openchat">Chat with us!</button>

<script>
  document.getElementById('openchat').addEventListener('click', function() {
    syrup.open();
  });
</script>

syrup.clear()

Closes the current chat session (if any) and deletes user/session cookies.

syrup.isReady()

Indicates whether syrup is ready to be used. That happens once the script is loaded and external settings are retrieved from the cloud.

It can be used in combination with the syrup:ready event defined below to provide a robust mechanism that would work in any use case:

if (window.syrup && window.syrup.isReady()) {
  console.log('syrup ready');
  runSyrup();
} else {
  window.addEventListener('syrup:ready', function() {
    console.log('syrup ready');
    runSyrup();
  });
}

function runSyrup() {
  // Your stuff here
}

Events

syrup:ready

syrup performs some asynchronous tasks before being ready. Once ready, it fires a global syrup:ready event on the window object.

window.addEventListener('syrup:ready', function() {
  console.log('syrup is ready!');
});

syrup.on('open', callback)

Event fired when the chat is open. Useful to disable the custom button that launches it (if any).

syrup.on('open', function() {
  document.getElementById('openchatbutton').disabled = true;
});

syrup.on('close', callback)

Event fired when the chat is closed. Useful to re-enable the custom button.

syrup.on('close', function() {
  document.getElementById('openchatbutton').disabled = false;
});