Web Messenger API
The Web Messenger API is an interface to programatically control the
FxoMessenger object which emits events and exposes a set of methods.
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:
- Amend the script
srcattribute to add your callback name after
- Wrap your code in a callback function with that name
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:
async deferfrom the script tag
- Always place your inline code after the script tag
sendMessageSend a message as the user
setConfigSet the config for current and future messengers
getStateGet the state and config of the current messenger
createCreate a new messenger
destroyShutdown an existing messenger
toggleDestroy any existing messenger or else create one
The API publishes events about the messenger lifecycle that you can subscribe to.
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
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.
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
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.
Returns an object describing the current messenger configuration and the state of the messenger (if created).
Create a new messenger. If one is already created it will be destroyed and recreated.
Destroy any existing messenger.
Returns true if a messenger was destroyed, false otherwise.
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.