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 widget 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'
  • 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

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.

Usage

Still need help? Contact Us Contact Us