Webhooks

Start Meeting Webhooks

The start meeting endpoints allow your applications to be notified when certain events happen during the meeting lifecycle via webhooks. You can register callback URLs for these events, as well as custom data that will be passed back when the event occurs. The join.me API will then call these URLs when the relevant meeting lifecycle event occurs.

We currently support callbacks events for the following meeting lifecycle events:

  • Meeting Started ("meeting.start") - fired when the presenter clicks the presenter link and actually launches the meeting in a join.me client
  • Meeting Ended ("meeting.end") - fired when all parties have left the meeting

Set Webhooks

The start meeting endpoints each take an additional "webhooks" parameter. This parameter is a JSON dictionary, whose keys are the meeting lifecycle event you are subscribing to (you cannot register multiple webhooks for the same event). Valid webhook type keys:

  • meeting.start
  • meeting.end

The values for these keys are objects with the following properties:

Property Type Description
callbackUrl string Required. The fully-qualified URL that will be POSTed to when the event occurs.
customCallbackData Object An arbitrary JSON parameter that will be added to the response body of the callback.
Example Start Meeting Request with Webhooks:
{
    "startWithPersonalUrl": true,
    "webhooks": {
        "meeting.start": {
            "callbackUrl": "http://example.com/integrations/joinme/callbacks/meeting_started",
            "customCallbackData": { foo: 123 }
        },
        "meeting.end": {
            "callbackUrl": "http://example.com/integrations/joinme/callbacks/meeting_ended",
            "customCallbackData": { bar: "abc" }
        }
    }
}

Set Webhooks Response

If you include the "webhooks" property in your start meeting request, the response body will include an additional object describing the status of the webhooks that were requested. It is possible for the meeting to start successfully but for the webhooks to not be registered. The response object will be under the property "webhooksStatus" and has two parameters:

Property Type Description
webhookErrors Object[] A list of error objects identifying which webhooks failed to register and why. An empty array indicates that all webhooks were successfully registered.
webhookMeetingId Guid A unique identifier for the webhooks that were just enqueued for this specific instance of this join.me meeting.

A webhook error object has the following properties:

Property Type Description
type string The webhook event key subscription that failed (i.e. meeting.start, meeting.end etc.). A "None" type indicates that none of the webhooks were set successfully.
code string Parsable error code identifying the error that occurred. If you continue to receive a certain error, submit this code (along with the webhookMeetingId) to join.me support with details about your failing request.
message string Error message
Example /meetings/start Response:
{
    "presenterLink": "https://secure.join.me/API/Public/StartMeeting.aspx?token=01_123456789",
    "viewerLink": "https://secure.join.me/123-456-789",
    "audioConference": {
        "conferenceId": "123456789",
        "conferenceCallNumbersUrl": "https://secure.join.me/api/public/intphone.aspx?conferenceId=123456789",
        "organizerCode": "1234"
    },
    "webhooksStatus": {
        "webhookErrors": [
            {
                "type": "meeting.start",
                "code": 2,
                "message": "An unknown error occurred."
            }
        ],
        "webhookMeetingId": "e11cc6b1-7982-4d68-824f-11bc41296716"
    }
}

Webhook Event Callback

When the meeting lifecycle event triggers the webhook callback, we will POST to your callback URL with the following JSON data:

Property Type Description
event string The event that triggered the webhook. Events:
  • StartMeeting
  • EndMeeting
customCallbackData Object The same JSON object that was initially passed in on the start meeting request.
eventData Object An object with data that is relevant for the current event. For meeting.start webhhoks, this object will include the viewerLink and the audioConference information that was returned from the original start meeting request. For meeting.end webhooks, this object will be empty.
Webhook Event Callback POST
{
    "webhookMeetingId": "e11cc6b1-7982-4d68-824f-11bc41296716",
    "event": "StartMeeting",
    "customCallbackData": {
        "foo": 123
    },
    "eventData": {
        "viewerLink": "https://secure.join.me/123-456-789",
        "audioConference": {
            "conferenceId": "123456789",
            "conferenceCallNumbersUrl": "https://secure.join.me/api/public/intphone.aspx?conferenceId=123456789",
            "organizerCode": "1234"
        }
    }
}