Scheduler API

Version 1.1.0 - Released 19/05/2017

Introduction

The REST API Scheduler methods allow the creation, modification, deletion and undeletion of events on the Meet & Engage platform.

Where an exiting CRM or other system is in place to manage event planning and scheduling, you might use this API as a way to include 'Meet & Engage Moderated Chat Event' as the meeting place for upcoming events and treat it as you would any other bookable resource.

Authentication

The Meet & Engage REST API is secured with Basic Auth with randomly generated complex key pairs. You can generate such keys for your organisation account (without a limit on the number used) from your Control Panel. When logged onto the Control Panel, click on the cog button in the top-right to access your preferences menu. Towards the bottom you will find a list of any existing keys in your account as well as the ability to revoke current key pairs and generate new ones. Click on 'Generate new key pair' to create and store a key pair. Please make a note of this immediately, as we do not store the secret portion in a reversibly encrypted format.

If you suspect that a key has been lost or stolen, please revoke it immediately.

New keys are linked to the Meet & Engage Account, not the current Moderator account. This means that if you have access to multiple Accounts you will need to generate keys for each Account to which you need API Access. In addition, Keys will remain active even if the user who generated them is removed, for the same reason.

When coding against this API, ensure you include the ID and Secret in the header of your connection, not as part of the URL itself, as this is not secure. As an example, using CURL this would be

curl -u id:secret https://meetandengage.com/api/1.0/rest

rather than

curl https://id:secret@meetandengage.com/api/1.0/rest

Connect to https://meetandengage.com/api/1.0/rest with the correct Authentication header and the following will be returned:

{
    "authenticated": true
}

Each key is limited to 10 successful calls in each 5 second interval. No daily/monthly overall limits are imposed. All rate limits breaches are logged, and following excessive rate limiting keys may be disabled to safeguard the security of your data. If you have an questions about limits or how to avoid them, please contact our support team.

Endpoints

The scheduler endpoints and their associated HTTP methods / verbs are:

URL HTTP method
https://meetandengage.com/api/1.0/rest/scheduler/list GET
https://meetandengage.com/api/1.0/rest/scheduler/create POST
https://meetandengage.com/api/1.0/rest/scheduler/update PUT
https://meetandengage.com/api/1.0/rest/scheduler/delete DELETE
https://meetandengage.com/api/1.0/rest/scheduler/undelete PUT

All parameters passed to the above endpoints are expected in the document body.

Listing Events

The GET /scheduler/list endpoint allows a read-only view of events on the Meet & Engage platform, within the account to which the API Key pair belongs. The API returns a JSON object containing an array of planned, running and recent past events, designed to mirror the view seen on the Control Panel. No metadata or content from events is included (use the Data API to obtain this)

No parameters are required when calling the /scheduler/list endpoint. It will automatically list events within the account to which the API Key pair belongs only.

Creating Events

The POST /scheduler/create endpoint allows the creation of events on the Meet & Engage platform, within the account to which the API Key pair belongs. The API is designed to mirror the manual method for scheduling events within the Control Panel, and it offers broadly the same scope for configuration. The exceptions are:

  • Start and Finish Times - Fine-grain control of event start and finish time is possible through the API, where only 15-minute increments are possible using the GUI
  • Extended Attributes - 20 additional fields are exposed via the API, intended to be used for arbitrary storage of data. These fields are then accessible through the Plugin API, so can be used to filter events based on a custom value or topic, for example.

Group Event

The /scheduler/create endpoint accepts the following fields to create a basic group chat event.

Key Description Example Format
title Event Title - keep this as a short heading Our Project Management Roles String
description Event Description (optional) - Can be longer than the title, to give more information to the participant. This is displayed under the title of the event on the landing page Come and chat to us to learn all about being a Project Manager at Acme Co String
type Either Group or 1to1 event group String
eventStart Time to start this event 1511568000000 Integer, number of milliseconds from 1/1/1970 to the required date/time in GMT
eventFinish Time to finish this event 1511586000000 Integer, number of milliseconds from 1/1/1970 to the required date/time in GMT
logonType The type of information requested from participants when they join the chat event. Can be an array of "nick", "nickandemail", "oauth" or "guest". Choose "nick" if programmaticLogon() is required in your Plugin API implementation nick Array

One to One Event

In addition to the above fields, the /scheduler/create endpoint accepts the following fields to configure a basic one-to-one chat event.

Key Description Example Format
autoresponderEnabled Seed each newly opened chat room with a welcome message? true Boolean
autoresponderWelcomeMessage The message body to send to each new room Hi! Welcome to this chat. Can you let me know your application ID please? String
autoresponderDisplayname The name of the autoresponder Application Helpdesk String
autoresponderAvatar a URL to the avatar of the autoresponder https://... URL String
recurring Do you want the event to recur at set intervals? e.g. once a day, or once a week? true Boolean
recurrency How often should the event recur? Accepts DAILY, WORKWEEKDAILY, ARBITRARYWEEKDAY, WEEKLY, MONTHLY or YEARLY WORKWEEKDAILY custom, as shown
finalOccurrence When should the event stop recurring? Omit for never 1511586000000 Integer, number of milliseconds from 1/1/1970 to the required date/time in GMT
recurForever Should the event recur indefinitely? true Boolean
recurringArbitraryDays Which days each week to recur, as an array of boolean values starting with Sunday [true, false, false, false, true, true, true] custom, as shown
blackoutDays Days to skip, even though they would normally be a chat day (e.g. public holidays) [1511586000000, 1511586000000] Array of epoch milliseconds for each day to skip

Notes:

  • recurrency, finalOccurrence, recurringArbitraryDays, blackoutDays and recurForever are only required if recurring is true.

Advanced features - All events

Key Description Example Format
openForRegistration Is the event open for registration before it begins? true Boolean
registrationCap How many participants should be allowed to register, omit or 0 for unlimited 30 Integer
gatherEmailAddressesWhenFull Collect contact details when user tries to register for a full event true Boolean
openInPopup On the standard landing page, open the chat in an IM sized popup, rather than embedded in the page? false Boolean
targetTeam Restrict moderation to a particular Team ProjectManagers String
npsSurveyEnabled Send out NPS survey after the event closes? true Boolean
npsLimitRespondents Send the NPS survey only to new users? Recommend setting to true true Boolean
npsQuestionContent Content to be included on the email and feedback website Based on your recent chat, how likely are you to recommend company name to a friend or colleague String
npsPostFeedbackContent Content to be shown to the NPS respondent after they leave their feedback Thanks for your feedback! String
showNames Show people's first names in the chat true Boolean
showFullNames Show people's full names in the chat false Boolean
showAvatars Show people's avatars if collected from social media or Gravatar true Boolean
modsShowNames Show moderators first names in the chat true Boolean
modsShowFullNames Show moderators full names in the chat false Boolean
modsShowAvatars Show moderators avatars if colllected from social media or Gravatar true Boolean
stimulusTemplateEvent Use an existing event's stimulus as a template for this event m2e4r5t5 M&E Event ID
privateEvent Keep event hidden from the 'upcoming events' list on the normal landing page false Boolean
customLobbyContent Content to override the account-level lobby content - HTML encoded string
custom121LobbyContent Content to override the account-level one-to-one waiting room content - HTML encoded string
customExitLobbyContent Content to override the account-level exit lobby content - HTML encoded string
customRegistrationDisabledContent Content to override the account-level content to show users instead of registration content, when registration is disabled or full - HTML encoded string
customMissedEventContent Content to override the account-level 'sorry you missed this event' content - HTML encoded string
customHoldTightContent Content to override the account-level 'Just a moment, we're getting things ready!' copy, shown when the event is set to 'Lobby' but the start time has arrived - HTML encoded string
extendedAttribute1 - extendedAttribute20 Use to store any data you need alongside the event, which you can retrieve again using the Plugin API CRM_Code=123456 Any

Notes:

  • targetTeam must match an existing team name
  • Setting modsShow* attributes is not required. Moderators will inherit the show* settings if these are not specified. Use the modsShow* attributes if you need to apply different privacy settings to both.
  • extendedAttributeN are converted to String and truncated to 500 characters when stored

Return Format

The /scheduler endpoints return JSON data.

If you miss a required field, or include one in an unexpected format, the API will alert you to this. Any errors occuring during creation are also returned:

{
    "error": "title missing - expecting string"
}

On success, the endpoint will return the event ID created, completed: true and any warnings raised:

{
    "completed": true,
    "eventID": "m5n4b3v2",
    "warnings": 0
}

Modifying Events

The PUT /scheduler/update endpoint allows existing events to be modified. The way this functions internally is by creating a new event object according to the supplied attributes and then merging this with the existing event. As such, the same fields are required and applicable to the scheduler/update endpoint as the scheduler/create one, in addition to the event ID of the existing event:

Key Description Example Required?
eventID The M&E event to be modified m1m2m3n4 Yes

Therefore, ensure that all required fields are supplied in addition to any you wish to modify, or the API will reject the change.

Note that it is considered bad etiquette to drastically modify events after people have seen or interacted with them. The platform will allow the change to take effect, but care should be taken in modifying start and finish times, for instance, so as to avoid confusion.

Deleting Events

The DELETE /scheduler/delete endpoint allows events to be deleted and removed from the planned events list on both the landing page and control panel.

The M&E platform retains all previous, even deleted events for reference. The delete method on both the API and GUI is intended to remove the event from the active planned and running list, but not expunge entirely from the system. No expunge method is exposed over the REST API.

Only one parameter is required:

Key Description Example Required?
eventID The M&E event to be deleted m1m2m3n4 Yes

Undeleting Events

The PUT /scheduler/undelete endpoint allows events to be undeleted. Events are then reinstanted to the planned events list on both the landing page and control panel.

Only one parameter is required:

Key Description Example Required?
eventID The M&E event to be undeleted m1m2m3n4 Yes