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://www.meetandengage.com/api/1.0/rest

rather than

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

Connect to https://www.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:

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.

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.

Notes:

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

Advanced features - All events

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:

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:

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: