Alexa.MeetingClientController Interface 1.0


Implement the Alexa.MeetingClientController interface in your Alexa skill so that users can join a meeting.

For the list of languages that the MeetingClientController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.MeetingClientController interface uses the pre-built voice interaction model. The following examples show some user utterances:

Alexa, start the meeting.
Alexa, end the meeting.

After the user says an utterance, Alexa sends a corresponding directive to your skill. If Alexa needs more information first, such as to identify the correct meeting to join, Alexa prompts the user.

Discovery

You describe endpoints that support Alexa.MeetingClientController using the standard discovery mechanism described in Alexa.Discovery.

For the full list of display categories, see display categories.

In addition to the usual discovery response fields, for the MeetingClientController entry in the capabilities array, include the following fields.

Field Description Type
supportsScheduledMeeting True if the device supports the JoinScheduledMeeting directive; otherwise, false. Boolean

Discover response example

The following example shows a Discover.Response message for a device that supports the Alexa.MeetingClientController and Alexa.Calendar interfaces.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints":[
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Device name, displayed in the Alexa app",
          "displayCategories": ["OTHER"],
          "additionalAttributes":  {
            "manufacturer": "Manufacturer of the endpoint",
            "model" : "Model of the device",
            "customIdentifier": "Optional custom identifier for the device"
          },
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.MeetingClientController",
              "version": "1.0",
              "supportsScheduledMeeting": false
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.Calendar",
              "version": "1.0"
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

JoinMeeting directive

Support the JoinMeeting directive so that users can join a meeting when they know the id of the meeting that they want to join. You must support the JoinMeeting directive.

The following example shows a customer utterance:

User: Alexa, start the meeting.

Alexa: What is your meeting ID?
User: One two three four.

Alexa: What is your meeting pin?
User: Five six seven eight.

JoinMeeting directive payload details

Field Description Type
meeting.provider The meeting provider, such as Amazon Chime or Skype for Business. String
meeting.protocol The protocol for the meeting, one of SIP, SIPS, H323. String
meeting.endpoint The meeting endpoint. Typically an IP address or URL. String
meeting.id The identifier for the meeting. This field is not always specified. String
meeting.pin The PIN for the meeting. This field is not always specified. String

JoinMeeting directive example

The following example illustrates a JoinMeeting directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.MeetingClientController",
      "name": "JoinMeeting",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerTokenWithPartition",
        "token": "OAuth2.0 bearer token",
        "partition": "Partition, for example, room101",
        "userId": "user id"
      },
      "endpointId": "Unique ID of the endpoint",
      "cookie": {}
    },
    "payload": {
      "meeting": {
        "provider": "chime",
        "protocol": "sip",
        "endpoint": "54.19.29.39",
        "id": "1234",
        "pin": "5678"
      }
    }
  }
}

JoinMeeting response

If you handle a JoinMeeting directive successfully, respond with an Alexa.Response event.

The following example shows a JoinMeeting response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa ",
      "name": " Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "payload": {}
  }
}

JoinMeeting directive error handling

If you can't handle a JoinMeeting directive successfully, respond with an Alexa.ErrorResponse event.

EndMeeting directive

Support the EndMeeting directive so that users can end a meeting. You must support the EndMeeting directive. When Alexa sends the EndMeeting directive, you should end all active meetings.

The following example shows a customer utterance:

Alexa, end the meeting.

EndMeeting directive example

The following example illustrates a EndMeeting directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.MeetingClientController",
      "name": "EndMeeting",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerTokenWithPartition",
        "token": "OAuth2.0 bearer token",
        "partition": "Partition, for example, room101",
        "userId": "user id"
      },
      "endpointId": "Unique ID of the endpoint",
      "cookie": {}
    },
    "payload": {}
  }
}

EndMeeting response

If you handle a EndMeeting directive successfully, respond with an Alexa.Response event.

The following example shows an EndMeeting response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa ",
      "name": " Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "payload": {}
  }
}

EndMeeting directive error handling

If you can't handle a EndMeeting directive successfully, respond with an Alexa.ErrorResponse event.

JoinScheduledMeeting directive

Support the JoinScheduledMeeting directive so that users can join a meeting without knowing id of the meeting that they want to join. Supporting the JoinScheduledMeeting directive is optional.

You should support the JoinScheduledMeeting directive if your skill has access to an organization's calendar, and you can access the identifiers of meetings on that calendar. If you support this directive, set supportsScheduledMeeting to true in your discovery response. To support the JoinScheduledMeeting directive, you must also implement the Alexa.Calendar interface.

The following example shows a customer utterance:

User: Alexa, start the meeting.

Alexa sends a Calendar.GetCurrentMeeting directive to your skill.
Your skill sends a response to Calendar.GetCurrentMeeting with the meeting information.
Alexa: Do you want to join meeting organized by John Doe?
User: Yes.

Alexa sends a MeetingClientController.JoinScheduledMeeting directive to your skill.

JoinScheduledMeeting directive payload details

Field Description Type
calendarEventId The identifier of the meeting on the organization's calendar. String

JoinScheduledMeeting directive example

The following example illustrates a JoinScheduledMeeting directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.MeetingClientController",
      "name": "JoinScheduledMeeting",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerTokenWithPartition",
        "token": "OAuth2.0 bearer token",
        "partition": "Partition, for example, room101",
        "userId": "user id"
      },
      "endpointId": "Unique ID of the endpoint",
      "cookie": {}
    },
    "payload": {
      "calendarEventId": "Meeting ID"
    }
  }
}

JoinScheduledMeeting response event

If you handle a JoinScheduledMeeting directive successfully, respond with an Alexa.Response event.

The following example shows a JoinScheduledMeeting response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa ",
      "name": " Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "payload": {}
  }
}

JoinScheduledMeeting directive error handling

If you can't handle a JoinScheduledMeeting directive successfully, respond with an Alexa.ErrorResponse event.


Last updated: Oct 19, 2022