join.me - 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"
        }
    }
}

Webhooks