Meet & Engage

Plugin API

Version 1.0.12 - Released 11/09/2017

Introduction

The Meet and Engage Plugin API allows you to embed live chat events into your website and interact with information about events from within JavaScript.

Meetings are surfaced within a preferred element on the page or within a separate popup window, either in the standard Meet and Engage look and feel or according to supplied CSS. Using the API’s JavaScript functions you are able to retrieve information about upcoming and live events, embed running events into the page and receive information about embedded meetings such as whether the meeting is running or has ended.

We use the same API ourselves to render the meeting elements of each account’s public page. (i.e. www.meetandengage.com/account)

This guide explains how to use the Plugin API, what events the API can send and what your code should do to react to offer a seamless and more integrated feeling event to the participant.

Overview of API interaction and event flow

To provide some context around the way in which you use the Plugin API, lets look at a typical process the participant would interact with, where ‘you’ in the example is JavaScript code running on your page:

  1. You initialise the plugin API via JavaScript, supplying the following information:

    • Meet and Engage account name (i.e. www.meetandengage.com/account)
    • Locale, from a set of supported languages
    • URI to custom CSS, if required
    • onstatechange event listener function

  2. You call the getEvents() function on page load, which returns a JavaScript array containing upcoming and running events. Your page parses and plots the information somewhere on the page, presenting a ‘join now’ button or similar for any running events

    It is not mandatory to respond to onstatechange events as they are raised, so you are free to plot the results of getEvents() on a different page of your site to the desired meeting, perhaps showing a ‘Talk to us live’ button on all pages of the site whenever an event is running that links to the page on which you wish to embed the meeting.

  3. The user notices an interesting event and clicks on your ‘join now’ button. You call the joinevent() function accordingly, supplying the eventID

  4. If the user does not have a valid www.meetandengage.com logged-on user cookie, your event listener is called to let you know that a logon is required. You can either do a programmatic logon (as 'Guest', or a particular user) or call the showlogondialog() function supplying the target DOM object

  5. Depending on whether the meeting moderator has decided on an OAuth, email or nickname logon for the event, the API shows the relevant dialog to the user within the supplied target element (within an <iframe>)

  6. The user enters their details or clicks on the relevant OAuth logon button, is processed on the www.meetandengage.com domain and a logon cookie is established

  7. The user is forwarded back to your page after successful (or unsuccessful) logon

    If established, an identitycallback() event listener is called with a javascript object containing logged-on-user information, to allow you to display the avatar and name on the page.

  8. Your event listener is called to let you know that the event the user has joined is currently in ‘Lobby mode’. You show the user some relevant ‘please wait’ content.

    You can choose to display content from the meet and engage platform to display in your Lobby if this has been added via the control panel.

  9. When the moderator changes the event from Lobby mode to Meeting Room mode, your event listener is called again to let you know. At this point you make the meeting target element visible and call the chatnow() function.

    Some events may be configured as ‘popup’ events. For these, the logon and meeting room is rendered on a popup window with the familiar Instant Message software dimensions rather than an element on the page.

  10. The event is rendered to the target element within an <iframe>, with any custom CSS included in the page

  11. When the moderator changes the event from Meeting Room mode to Exit Lobby mode, your event listener is called again to report the change. You hide the meeting target element and show relevant ‘thanks for taking part’ content.

    You can choose to display content from the meet and engage platform to display in your Exit Lobby if this has been added via the control panel.

You will note that rather than a contiguous process, no action is directly taken by the API. Instead, a change is state event is raised to your code’s event listener function and the onus placed on your code to trigger the next action. This is to give more control over ancillary parts of the event process (the parts pre and post event) with the intention that a more integrated feel is achieved.

Requirements

The Plugin API invokes, controls and responds to an <iframe> tag within either a target element on the page or a popup window (as controlled on a per-event basis from the control panel). Communication between the embedded event and the calling API is carried out via postMessage. As such, the minimum browser requirement is Internet Explorer 8. All newer browsers are supported.

If you are invoking the API over https, the resultant embedded meeting and all browser <-> server traffic will be sent via the same protocol. Where a link to a custom stylesheet is passed to the API this must also be accessible via a secure URL, as mixing protocols will trigger a warning on most browsers.

Unless you are running popup-window based events exclusively, the following target elements are required on the page:

Target: Notes: Minimum viewport size and style requirements Required?
logonTarget Used to embed the logon dialog prior to surfacing the event to the user. Note: all meeting events require a logon take place as this establishes the session and cookie on the participant’s device. Minimum 350px x 500px [x]
eventTarget Target for the Event Surface, containing the chat and all associated stimulus while an event is in progress Minimum 350px x 500px. Should be an absolutely positioned element taking up the page real-estate you are willing to allot to the event. Can be set to display:none until required [x]
lobby Target for lobby content, to show the participant while the event is waiting to start -
exitlobby Target for exit lobby content, to show the participant when the event is closed by a moderator -
Upcoming events Somewhere to show a list of upcoming and live events with ‘join now’ or similar buttons -

Getting Started

The following sample HTML page shows the plugin API being initialised and calling getEvents to obtain a list of running and upcoming events (the numbered parts explained below):

<!doctype html>
<html>
    <head>
        <!-- 1. Load meetandengage.js plugin API code -->
        <script type="text/javascript" src="https://www.meetandengage.com/api/1.0/meetandengage.js"></script>
    </head>
    <body>

        <script type="text/javascript">

            // 2. Initialise new meetandengage() class
            var chat = new meetandengage();
            chat.initialise({
                locale: 'en-gb',
                account: 'acme',
                css: 'https://example.com/chatevent.css', 
                eventTarget: document.getElementById("eventtarget"), 
                identitycallback: function(user){}, 
                onstatechange: function(ret){}
            });

            // 3. Call getEvents() to immediately pull list of new events
            chat.getEvents(function(eventsarray){

                for (var event in eventsarray){
                    var strstart = new Date(eventsarray[event].eventstart);
                    var strfinish = new Date(eventsarray[event].eventfinish);
                    var times = pad(strstart.getHours()) + ":" + pad(strstart.getMinutes()) + " " + strstart.getDate() + "/" + (strstart.getMonth() + 1) + " - " + pad(strfinish.getHours()) + ":" + pad(strfinish.getMinutes()) + " " +  strfinish.getDate() + "/" + (strfinish.getMonth() + 1);
                    var description = eventsarray[event].description;
                    var title = eventsarray[event].title;
                    var eventid = eventsarray[event].eventid;
                    // 4. plot to page..
                    // ...
                }

            });

            function pad(n) { return ("0" + n).slice(-2); }

        </script>
    </body>
</html>

  1. We’re calling <script type="text/javascript" src="https://www.meetandengage.com/api/1.0/meetandengage.js"></script> in the <head> section of the document. Calling this over https:// ensures that all subsequent traffic follows the same protocol and is encrypted from the browser to the www.meetandengage.com servers (regardless of the protocol used for the page on which it is being embedded).

  2. You can see that we’re calling initialise() with an object as the only argument, containing the locale (en-gb in this case); the account (acme) and some CSS to load when rendering the logon and event surfaces (example.com/chatevent.css), noting that this must be accessible over HTTPS to prevent errors from being thrown by the user’s browser.
    We’ve also defined a function to call whenever an event fires for identitycallback and onstatechange but doing nothing with them in this example.

  3. After the initialisation, we immediately call chat.getEvents() with an asynchronous callback function as the only argument. Note that calling getEvents() without first calling the (synchronous) initialise() function would result in an error, as it would not be established which in account events should be sought.

  4. This sample page does nothing visible, but the variables defined from the eventsarray array will reflect any planned or running event. All date/time fields are handled as epoch timestamp in milliseconds, to make compare operations easier without date parsing. In the above example we’re calling and concatenating the output of JavaScript .getDate() and .getMonth() functions to assemble the date of the start and finish of each event. Naturally a different order or a more comprehensive method might be used to handle and parse these into different (YMD / MDY etc.) date formats.

Functions reference

The following are functions that you can call on demand from your JavaScript code. For documentation purposes it is assumed that you have set an instance of the meetandengage() class to the variable chat, as in the example page shown above and we will refer to API functions from this point forward as chat.functionName().

Multiple instantiations of the same class are supported, if concurrent events are required, for example.

initialise() Function

To use the plugin API it must be initialised, providing the account name to use and locale, along with event listener functions to catch changes to a joined event.

chat.initialise({  
    locale: String,  
    account: String, 
    css: String, 
    eventTarget: DOM Element,  
    showinlinecontrols: Boolean,  
    identitycallback: Function(Object), 
    onstatechange: Function(Object),
    oninformation: Function(Object),
    contextualData: Object,
    restartConversation: Boolean,
    showHistory: Boolean
});

The passed object should contain the following:

Parameter Decription Example
locale Select from the supported locale strings. The default is en-gb. See Locales section for supported languages. en-gb
account Account string, echoing the account name configured. Note that multiple accounts may have been configured for a business to reflect different business areas acme
css Fully qualified URI to css stylesheet, accessible over the same protocol used to invoke the meetandengage object. https://example.com/chat.css
eventTarget DOM object of target element on the page to which the event surface will be appended. document.getElement("chatdiv")
showinlinecontrols Show controls for ‘exit event’ inline in the event surface. This can be hidden if you plan to true
identityCallback Function called when identity information is available for a logged on user. (see below for more detail) function(object){}
onStateChange Function called when event state changes (e.g. meeting over / meeting start etc) (see below for more detail) function(object){}
onInformation Function called when information about an event is raised (e.g. Chat surface finished loading) (see below for more detail) function(object){}
contextualData (optional) Object to pass to the M&E servers containing information about the current user (see 'Contextual Data' section below) see 'Contextual Data' section below
restartConversation (optional) Restart the (chatbot) conversation each time the room is reloaded, allowing users to easily return to the start of a chatbot flow true
showHistory (optional) Show previous chat history each time the room is reloaded. Use in conjunction with restartConversation to effectively wipe and restart a chatbot on every reload. Also works on one-to-one chats true

Arguments supplied with identitycallback() call

The identitycallback() function passes a single object, with the following structure:

Object { 
    avatar: String, // URI to avatar, (from OAuth provider  
                    // or an identicon, URI encoded)  
    displayname: String, 
    email: String // Domain name obfuscated with asterisks 
 }

Arguments supplied with onstatechange() call

The onstatechange() function passes a single object, with the following structure:

Object{
    statecode: Integer,
    action: String,
    action-description: String
}

statecode or action should be used when processing the current state. action-description is provided to assist with development. The codes are as follows:

statecode action action-description Recommended Action
0 initialised No action needed.. Just letting you know the API is now initialised. -
1 gotologon The user is not logged on, or has just logged off. Your code should display the logon dialog with the logonbox function Call showlogondialog()
2 gotolobby The chat event is in lobby mode. Either the moderator has not yet opened the event or set it to locked. Your code should display the lobby and wait for state changes. Hide event surface and show the lobby content (showLobbyContent())
3 gotoeventroom The chat event is now open. Your code should call the chatnow function to begin rendering the chat. Hide lobbies and show event surface. Call chatnow() to attach chat surface
4 gotoexitlobby The chat event has finished. Your code should display the exit lobby and wait for state updates Hide event surface and show exit lobby content (showExitLobbyContent())
5 gotomanualexit The user has pressed the exit button. The event is no longer being watched by this API. Hide event surface and show exit lobby content (showExitLobbyContent())
6 constrainedtopopup This event has been configured to run in a popup by the organiser. The participant journey will be managed within the launched popup. -
7 showregistration Registration for this event is open. Your code should display the registration dialog Show registration dialog with showRegistrationDialog()
8 registered User is registered for this event. Show post-registration copy calling showRegistrationComplete()
9 registrationisfull Registration for this event is full, or has been closed manually by the event organiser show registration full dialog with showRegistrationFullDialog()
10 logonerror The previous logon attempt failed. -
11 showregistrationdisabled Registration is disabled for this event. Your code should display the 'thanks for your interest' dialog Show 'thanks for your interest' dialog with showRegistrationDisabledDialog()
12 showmissedevent The user missed the requested event. Your code should display the Missed Event dialog Show missed event dialog with showMissedEventDialog()
13 goto121queue There is a queue for this 121 event. Show 'waiting for 121 agent' copy and wait for state updates Show 'waiting for 121 agent' copy (show121queuecontent())
14 showgeolockcopy The user is located outside the allowed list of countries for this event, call showGeolockDialog() to show appropriate copy to the user Call showGeolockDialog()
15 loggedon The user is logged on. Make your logon window invisible No action

Arguments supplied with oninformation() call

The oninformation() function passes a single object, with the following structure:

Object{
    infocode: Integer,
    message: String,
    message-description: String
}

infocode should be used when processing the received information. message-description is provided to assist with development. The codes are as follows:

infocode message message-description About
14 chatsurfaceloaded The chat surface has finished loading and the chat is now displayed. The chat surface has finished loading. You should display the target div now, or ignore this if you display the event target div on receipt of gotoeventroom on onStateChange()
15 transitioningtostimuluslayout The event is about to show stimulus (video, image). If you wish to resize the chat target to show a larger area, do so now. If not, and you are showing the chat in a narrow 'instant message' format, we will show the stimulus above and overlapping the chat as on mobile devices
16 transitioningtochatlayout The event has stopped showing stimulus. If you have resized the chat target for stimulus, it can now be reset.

getEvents() Function

Called to obtain an array of upcoming and live events.

Ensure that initialise() has been called (checking for a state of 0 being returned) before calling getEvents().

The getEvents() function accepts a function as the only argument, which is called when the query returns:

chat.getEvents(
    Function(array)
);

The returned array has the following structure:

[{
    account: String,
    currentspace: String, // "lobby" | "eventroom" | "exitlobby"
    description: String,
    eventfinish: Integer, // timestamp in ms
    eventid: String,
    eventstart: Integer, // timestamp in ms
    popup: String, // "on" | "off"
    title: String,
    type: String, // "group", "onetoone"
    openforregistration: Boolean,
    joinnow: Boolean
},
{...},
{...}]

The joinnow boolean indicates whether an event can be joined now, i.e. is currently open according to its configured start/finish times.

programmaticLogon() Function

Called to generate a Meet & Engage logon cookie for the user without prompting them for logon. This is useful in automatically creating a 'guest' logon so that your 'Join Now' buttons allow the user to join immediately, or passing in an established identity from the hosting website for example. Note that the user cookie will always be given the lowest authentication level, so events requiring Social Network logon or Nickname and Email logon are not able to be joined in this way; ensure any events accept 'Nickname only' logon for programmatic logon to be accepted.

The programmaticLogon() function accepts an object containing the user identity (or 'guest: true' for guest logon) and a callback function as arguments:

chat.programmaticLogon(
    {
        guest: Boolean, // if true, the other attributes are not required
        displayname: String, // "John Smith"
        email: String, // Optional, but used as identifier if provided
    }, 
    callback // Function
);

registerForEvent() Function

Called to register the user to the event passed as an argument.

Ensure that initialise() has been called (checking for a state of 0 being returned) before calling registerForEvent().

The registerForEvent() function accepts an object as the only argument, containing eventID of the event to join as a string:

chat.registerForEvent({
    eventID: eventID // String
});

Depending on whether the user has a valid user logon cookie from www.meetandengage.com, the registerForEvent() function call your onStateChange listener requesting a logon (via showLogonDialog()).

It is recommended that registerForEvent() is called from a user interaction, such as the onclick event of a button or link, as events requiring a popup have an immediate (synchronous) call to window.open within the joinEvent() function. Without user interaction the user’s browser is likely to prevent the window from opening (or at best, prompt) due to popup window blocker technology.

joinEvent() Function

Called to join the user to the event passed as an argument.

Ensure that initialise() has been called (checking for a state of 0 being returned) before calling joinEvent().

The joinEvent() function accepts an object as the only argument, containing eventID of the event to join as a string:

chat.joinEvent({
    eventID: eventID // String
});

Depending on whether the user has a valid user logon cookie from www.meetandengage.com, the joinEvent() function call your onStateChange listener requesting a logon (via showLogonDialog()).

It is recommended that joinEvent() is called from a user interaction, such as the onclick event of a button or link, as events requiring a popup have an immediate (synchronous) call to window.open within the joinEvent() function. Without user interaction the user’s browser is likely to prevent the window from opening (or at best, prompt) due to popup window blocker technology.

showLogonDialog() Function

Displays the user logon dialog within the target element appropriate to the requested event (i.e. OAuth logon; Name and Email; Nickname).

The showLogonDialog() function accepts an object as the only argument with the following structure:

chat.showLogonDialog({
    target: DOM Object
});

If the user has a valid user logon cookie it will be checked against the running event to establish the level of authentication that has taken place. If a greater authentication level is required for the joined event the logon dialog will be required to ‘upgrade’ this. This may apply when a user provides a nickname for one event but latterly joins a second event that requires OAuth authentication. No logon is required in the reverse scenario.

showMissedEventDialog() Function

Displays the 'sorry, you missed this event' dialog in the supplied target element.

The showMissedEventDialog() function accepts an object as the only argument with the following structure:

chat.showMissedEventDialog({
    target: DOM Object
});

showRegistrationDialog() Function

Displays the event registration dialog within the target element appropriate to the requested event (i.e. OAuth logon; Name and Email).

The showRegistrationDialog() function accepts an object as the only argument with the following structure:

chat.showRegistrationDialog({
    target: DOM Object
});

If the user has a valid user logon cookie it will be checked against the running event to establish the level of authentication that has taken place. If a greater authentication level is required for the joined event the logon dialog will be required to ‘upgrade’ this. This may apply when a user provides a nickname for one event but latterly joins a second event that requires OAuth authentication. No logon is required in the reverse scenario. Nickname only events request name and email to ensure we have a mail address to 'register' the event against.

showRegistrationDisabledDialog() Function

Displays the 'event registration is disabled for this event' dialog in the supplied target element.

The showRegistrationDisabledDialog() function accepts an object as the only argument with the following structure:

chat.showRegistrationDisabledDialog({
    target: DOM Object
});

showRegistrationComplete() Function

Displays the 'event registration complete' dialog in the supplied target element, along with a download link to an event ICS file.

The showRegistrationComplete() function accepts an object as the only argument with the following structure:

chat.showRegistrationComplete({
    target: DOM Object
});

showRegistrationFullDialog() Function

Displays the 'event registration full' content in the supplied target element.

The showRegistrationFullDialog() function accepts an object as the only argument with the following structure:

chat.showRegistrationFullDialog({
    target: DOM Object
});

showGeolockDialog() Function

Displays the 'geolock' content if a user is joining from a blocked country in the supplied target element.

The showGeolockDialog() function accepts an object as the only argument with the following structure:

chat.showGeolockDialog({
    target: DOM Object
});

showLobbyContent() Function

Displays the lobby content generated on the control panel within the supplied target element.

The showLobbyContent() function accepts an object as the only argument with the following structure:

chat.showLobbyContent({
    target: DOM Object
});

Once the event state is changed you should set your lobby target internal HTML to 'empty' ($(element).html("") or element.innerHTML="" etc.) as well as hiding the element from user. This ensures any video or assets running in the embedded iframe will be stopped and any bandwidth usage limited.

showExitLobbyContent() Function

Displays the lobby content generated on the control panel within the supplied target element.

The showExitLobbyContent() function accepts an object as the only argument with the following structure:

chat.showExitLobbyContent({
    target: DOM Object
});

Once the event state is changed you should set your exit lobby target internal HTML to 'empty' ($(element).html("") or element.innerHTML="" etc.) as well as hiding the element from user. This ensures any video or assets running in the embedded iframe will be stopped and any bandwidth usage limited.

show121queuecontent() Function

Displays the 121 queue content generated on the control panel within the supplied target element.

The show121queuecontent() function accepts an object as the only argument with the following structure:

chat.show121queuecontent({
    target: DOM Object
});

Once the event state is changed you should set your 121 queue target internal HTML to 'empty' ($(element).html("") or element.innerHTML="" etc.) as well as hiding the element from user. This ensures any video or assets running in the embedded iframe will be stopped and any bandwidth usage limited.

chatNow() Function

Instructs the API to render the event surface into the required DOM element.

Ensure that initialise() has been called (checking for a state of 0 being returned) and joinEvent() has been called (also the logon dialog if required) before calling.

The chatNow() function accepts no arguments.

contextualData() Function

The contextualData() function accepts an object as the only argument with the following structure:

{
    type: String,
    data: Object / URL / String    
}

Contextual Data

It is possible to send data to the M&E servers about the current user through the Plugin API so that it is displayed to the moderator when they appear in the chat. If you are embedding the chat interface into an environment where a user profile is being held (and perhaps programmaticLogon() is being used to provide a single-sign-on experience) is is often useful to view summary information about the user whilst chatting: E.g. for in-process candidates, understanding which roles have been applied for and their current stage; For graduate attraction, any information known about what grades they have or hope to get. Contextual Data can also be used to pass information through about the webpage the participant is currently viewing or role they are interested in if displaying a 'chat to us now' button next to each role on a careers website.

There are two places data can be passed into the Plugin API to best map into your own workflow: Passing a contextualData Object{} into the initialise() function or calling contextualData() at any time before joinEvent() is called.

Object format

Calling contextualData() or supplying an object to initialise() called contextualData requires the same object structure:

{
    type: String,
    data: Object / URL / String    
}

The type parameter should be one of the following, which then corresponds to the expected format of data:

  • text - Any plain text, e.g. "User's phone number: 01234567890"
  • html - A string containing escaped HTML, e.g. "<strong>User's phone number:</strong> 01234567890"
  • url - A URL that will be loaded inside an iframe on the M&E moderator view, on which further info can be presented, e.g. "https://greenbugATS.example.com/useroverview?userID=1234567"
  • object - JS object format data. Will be stored with the user for data purposes, arbitrary data structure

For simple data or information about the current page, we recommend passing either text or HTML. For security purposes, if information should not be transmitted to the browser before manipulating in JavaScript, a URL (to your own servers) should be passed, and the information surfaced there. We recommend passing in an https:// URL where possible. If no such route is available, we will proxy the request through our HTTPS proxy to prevent protocol downgrade errors in the browser. If you make use of this function, please note that all relative paths are rewritten by the proxy, scripts are disabled to avoid XSS vulnerabilities and no attempt is made to ensure consistency with the source.

Calling contextualData() after supplying the contextualData object in the initialise() function will overwrite the object supplied in initialise(). Only one object may be passed.

Locales

The following locales are supported by the plugin API, and are used to carry out internationalisation for label and help text during meeting events.

Please note that help text passed to developers is presented in en-gb regardless of locale chosen.

Locale String Language
en-gb British English
fr-fr French
pl-pl Polish
es-es Spanish