Web Messenger API

The Web Messenger API is an interface to programatically control the web messenger from within the page itself (using JavaScript). You'll first need to create a web messenger and follow the setup instructions below. You will then have access to a FxoMessenger object which emits events and exposes a set of methods.

Setup

Before you can use the API, you'll first need to create a web messenger and add the messenger script tag to your web page just before the closing </body> tag. Next, you'll need to make a small change to the script tag, depending on how you want to use the API.

Option 1: Use the 'ready' callback (better performance)

In this scenario, the script import is non-blocking (because async defer is used) and the function you want to use as a callback is passed to the embed script URL as a parameter callback. The callback (in this case messengerReady) is available in the global scope, and will be called when the messenger is ready.

To use this option:

1. Amend the script src attribute to add your callback name after embed.js
2. Wrap your code in a callback function with that name

Example

Option 2: Load the script synchronously (easier for novices)

To use this option, you simply need to remove async defer from your script tag. The script import will then block until embed.js has downloaded and executed, so by the time the inline script is run, we can be sure that FxoMessenger is available.

To use this option:

1. Remove async defer from the script tag
2. Always place your inline code after the script tag

Example

Methods

• sendMessage Send a message as the user
• setConfig Set the config for current and future messengers
• getState Get the state and config of the current messenger
• create Create a new messenger
• destroy Shutdown an existing messenger
• toggle Destroy any existing messenger or else create one

Events

The API publishes events about the messenger lifecycle that you can subscribe to.

Available events:

• created
• destroyed
• messageReceived
• messageSent
• configUpdated
• stateChanged

You can subscribe using:

The callback is passed the event data. You can unsubscribe using:

If no event name is specified all listeners are removed.

Note that for each event a convenience method exists too:

So for example, to use the convenience method for messageReceived, use:

Usage

sendMessage(text, metadata)

Send a message from the current messenger (as the user).

Some metadata about the user's client is also sent with every message.

Any custom metadata specified in the metadata parameter will be added to the default set, and override any of the defaults if they have the same property name.

Returns true on success and false if no messenger exists to send from.

Usage

setConfig(config)

Set the configuration for the current or any future messengers (for the lifetime of the page).

You can specify one or more properties. Valid configuration values are:

• mode (String) Set to either 'sidebar' (default) or 'fullscreen'
• popupHeight  The height (in pixels or %) that you want the popup to be. By default, this is 100%. Example: '50%' or '500px'
• allowBackgroundScroll  Whether or not the background is allowed to scroll when the chat widget is popped up. By default, this is false.
• headerText (String) The message to display in the window top bar
• color (String) A valid CSS color value
• botIcon (String) A URL to the icon to display for the bot
• metadata (Object) Global metadata that should be sent along with every message
• disableAttachments (Boolean) Set this to true to hide the attachments icon in the composer
• disableInput (Boolean) Set this to true to disable free-form typing into the composer
• disableReset (Boolean) Set this to true to disable the reset button
• externalUserId (String) A custom identifier for the current user. Use this if your app already knows the identity of a user, and you don't want to use the automatic cookie based identity that is built in to Flow XO. Note: when you use this configuration value, there will be an externalUserId property of the Metadata that is sent to your flow with this value, so you can use it in your flow logic or filters.

Returns false if any of the configuration options are invalid, and true on success.

Usage

getState()

Returns an object describing the current messenger configuration and the state of the messenger (if created).

Usage

create()

Create a new messenger. If one is already created it will be destroyed and recreated.

Usage

destroy()

Destroy any existing messenger.

Returns true if a messenger was destroyed, false otherwise.

Usage

toggle()

Toggle the state of the messenger.

If a messenger exists it will be destroyed, and vice versa.

Returns true if a messenger is created and false if destroyed.

Let us know how we can improve Flow XO on our feedback site.