Meet-up Plugin API

Version 1.0.8 - Released 03/06/2016

Introduction

The Meet and Engage Plugin API allows you to embed Meet-up 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. 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. 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 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 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://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://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 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 Object,  
    showinlinecontrols: Boolean,  
    identitycallback: Function(Object), 
    onstatechange: Function(Object) 
});

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 (i.e. meeting over / meeting start etc) (see below for more detail) Function(object){}

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
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
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
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 -
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

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
},
{...},
{...}]

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
);

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 the eventID to join as a string, as the only argument:

chat.joinEvent(
    eventID // String
);

The joinEvent() function can be called without first calling getEvents(), as long as a valid eventID is passed in. This can be especially useful for longer running events, to echo support functionality typically found on consumer websites. However, as no user interaction actions are taken by the API in the getEvents() function, we recommend that a call to getEvents() is made just to confirm the event still exists.

Depending on whether the user has a valid user logon cookie from 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.

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.

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
});

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.

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.

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

Latest Tweets

RT @redfernj: Quite. Good read. https://t.co/TYmf6rPsON
RT @CKE1977: As the evolution from recruiter to "talent adviser" continues the need for a strong TA strategy is greater than ever https://t…
Employers say uncertainty is the biggest challenge they face https://t.co/I8dXGfDPsO