Your Alexa Dashboards Settings

Build Skills for Conferencing Devices

Alexa skills created for conferencing devices give customers voice access to their business calendars and meetings, and the ability to control conferencing equipment by voice. For example, a customer can say, “Alexa, start the meeting” and the next scheduled meeting in the conference room that contains the Alexa device will start.

When you build a skill for conferencing devices, you can enable Alexa voice interactions to join and end meetings, turn a device on or off, or adjust the volume of device. The voice interaction model builds on the existing smart home voice model and is defined and handled for you. Alexa interprets customer utterances and sends messages to your skill that communicate customer requests.

This document provides a overview of concepts you should understand when building skills for conferencing devices as well as the interfaces and error messages you should be familiar with.

How it works

When Alexa hears a customer request like, “Alexa, start the meeting”, Alexa recognizes the customer intent to start a meeting in a specific meeting room or location. Because the device has been configured to a room in the Alexa for Business console (an AWS service), Alexa knows the location for the meeting. Alexa creates a message called a directive that contains the request and location and authentication information. As a skill developer, you receive and parse this message in code hosted in AWS Lambda, a compute service offered by Amazon Web Services (AWS), and pass it to the specified device in your device cloud. You respond to Alexa with a message called an event and indicate the request was successful or not.

The following image shows the conference functionality offered for developers.

  1. The organization uses the Alexa for Business console to configure their conference room with an Alexa device. They add your skill in the console and associate it with the room.
  2. An employee enters a conference room and says, “Alexa, start the meeting” to the Alexa device in that room.
  3. Alexa sends a directive to to the calendar API to find the meeting or asks the employee for the meeting ID, which the employee provides. Alexa sends a directive to start the meeting. A directive includes:

    • The capability (find a meeting or start the meeting)
    • The endpoint identifier (an ID representing the endpoint that controls meetings)
    • A message identifier
    • Information authenticating the request and the location (called a partition) where it originated.
  4. Your skill code, which is hosted as a Lambda function receives and parses the directive, and validates the authentication information. Your skill communicates with the conferencing system and device cloud, using communication channels you’ve defined to start the employee’s meeting.
  5. The skill sends a response back to Alexa indicating if the operation was successful. Alexa uses this response to provide the appropriate response to the employee. For example, Alexa might say, “OK” to indicate the requested directive was successfully handled.
  6. The meeting finishes early and the employee asks Alexa to end the meeting. Alexa sends another directive to your skill and the skill ends the meeting.

What kind of devices are supported

Alexa capability interfaces support a number of device types. Conferencing devices are specifically supported with the Alexa.Calendar and Alexa.MeetingClientController interfaces, but you can also implement interfaces for that enable customers to turn devices off and on and adjust the volume, and more. For more information, see the Implement Capabilities section. For a full list of capabilities, see the Capability Interface Message Guide.

Prerequisites to developing skills for conferencing

In order to develop a conferencing skill you must have the following:

  • An AWS account. You must configure skills and devices with the Alexa for Business console, and you will host your skill code as an AWS Lambda function.
  • An Amazon developer account. Sign up is free.
  • A cloud-connected conferencing device or software.
  • An Alexa-enabled device such as Amazon Echo that is configured in the Alexa for Business console.
  • Knowledge of JSON.
  • Knowledge of Java, Node.js, C# or Python as Lambda functions can be written in any of these languages.
  • Understanding of OAuth 2.0.
  • Understanding of how a smart home skill works and the messaging structure. For more information see Device API Message Reference. Note that the conferencing APIs are synchronous, which means you cannot send messages to the Alexa event gateway for a conferencing skill.

Steps to build a skill for conferencing

Creating a skill for conferencing devices is very similar to creating a skill for a smart home endpoint. As a prerequisite to this section, you should review Steps to Create a Smart Home Skill. The following steps will walk you through the steps for creating a skill for conferencing using the steps for a smart home skill as a reference.

Step 1: Create the skill in the Developer Portal

Create a smart home skill. Follow the instructions in Steps to Create a Smart Home Skill. Note that you MUST:

  • Target v3. v2 is not supported for conferencing skills.
  • Choose English (US) for your skill.

Step 2: Add a Lambda function for your skill

Follow the instructions in Steps to Create a Smart Home Skill. Make sure you create a Lambda in the US East (N. Virginia) region. In your Lambda, you will need to identify a conferencing endpoint and implement the interfaces that make sense for your devices. Find sample Lambda code written in Node.js in the Sample Lambda section.

Identify a conferencing endpoint

Alexa sends a discovery request when your skill is enabled and you describe a conferencing endpoint in the response. You provide the interface capabilities associated with the endpoint, and properties that you support for each capability.

The following code example shows how you might describe a conferencing device. For more information on device discovery messages, see Alexa.Discovery. Note that if your endpoint supports Alexa.MeetingClientController, you must specify whether you support the JoinScheduledMeeting directive with the supportsScheduledMeeting flag.

Example discovery response for a conferencing device

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "2b7f08b3-02b1-4548-a477-d2fdf67406d4"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "uniqueId",
                "manufacturerName": "MyConferencingManufacturer",
                "friendlyName": "phone",
                "description": "This is a smart conferencing equipment in Meeting Room 15.104",
                "displayCategories": ["OTHER"],
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.MeetingClientController",
                        "supportsScheduledMeeting": false,
                        "properties": {},
                        "version": "1.0"
                    }
                ]
            }]
        }
    }
}

Implement capabilities

The following table lists possible customer requests related to conferencing and tasks a user might perform in a conference room. Implement the interfaces that make sense for the devices and tasks you need to support.

Customer Operation Capability Interface
Discover devices Alexa.Discovery
Find a meeting on a calendar Alexa.Calendar
Join or end a meeting Alexa.MeetingClientController
Turn things on and off Alexa.PowerController
Change the input on an AV device Alexa.InputController
Change the volume Alexa.Speaker or Alexa.StepSpeaker

Report errors

If an error occurs while attempting to start or end a meeting, you should return an error event from your Lambda code. The following table lists some of the scenarios and the types of errors to return. For more information, or for errors with other requests such as to turn a device on, you should see the full error list.

Scenario Error message type Alexa response
Indicates skill cannot connect to in-room conferencing equipment because the endpoint is offline or some other connectivity issue occurs ENDPOINT_UNREACHABLE “Looks like your conference device is not responding”
Indicates the a meeting ID is not valid for the endpoint INVALID_VALUE “That meeting ID is invalid. What is your meeting ID?”
The skill does not have the correct credentials for the endpoint it is trying to access INVALID_AUTHORIZATION_CREDENTIAL “Sorry, I cannot join the meeting. If the problem continues, contact your IT support.”
All other error scenarios See Alexa.ErrorResponse for error types. “Sorry, I cannot join the meeting. If the problem continues, contact your IT support.”

Sample Lambda

The following Node.js code provides a starting point for your Lambda function. This code discovers a discovery response and parses a request to join or end a meeting such as extracting the authentication token and partition for the request. You must provide the full implementation, including the code that calls to the device cloud and calendar provider to find meetings, and start and end meetings, and error handling. The typical conferencing flow is:

  1. A customer enters a room and requests to join a meeting -> Alexa sends a Calendar.GetCurrentMeeting directive to your skill. Each request from Alexa includes a scope of type BearerTokenWithPartition, which identifies the customer and the request location.
  2. Your code accesses the calendar for that room, finds the meeting ID and sends the meeting back to Alexa in a response event.
  3. Alexa sends a MeetingClientController.JoinMeeting directive with the meeting specified in the previous response.
  4. The customer requests to end the meeting -> Alexa sends a MeetingClientController.EndMeeting directive.

exports.handler = function(request, context) {
    if (request.directive.header.namespace === 'Alexa.Discovery' && request.directive.header.name === 'Discover') {
        log("DEBUG:", "Discover event", JSON.stringify(request));
        handleDiscovery(request, context);
    }
    else if (request.directive.header.namespace === 'Alexa.MeetingClientController') {
        if (request.directive.header.name === 'JoinMeeting' || request.directive.header.name === 'EndMeeting') {
            log("DEBUG:", "JoinMeeting or EndMeeting event", JSON.stringify(request));
            handleMeetingControl(request, context);
        }
    }

    function handleDiscovery(request, context) {
        var payload = {
            "endpoints":
            [
                {
                    "endpointId": "demo_id",
                    "manufacturerName": "Smart Conferencing Company",
                    "friendlyName": "Conference room 210",
                    "description": "Smart conferencing connect with my conferencing",
                    "displayCategories": ["OTHER"],
                    "cookie": {
                        "key1": "arbitrary key/value pairs for skill to reference this endpoint.",
                        "key2": "There can be multiple entries",
                        "key3": "but they should only be used for reference purposes.",
                        "key4": "This is not a suitable place to maintain current endpoint state."
                    },
                    "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.MeetingClientController",
                        "supportsScheduledMeeting": false,
                        "properties": {},
                        "version": "1.0"
                    }
                   ]
                }
            ]
        };
        var header = request.directive.header;
        header.name = "Discover.Response";
        log("DEBUG", "Discovery Response: ", JSON.stringify({ header: header, payload: payload }));
        context.done(null, { event: { header: header, payload: payload } });
    }

    function log(message, message1, message2) {
        console.log(message + message1 + message2);
    }

    function handleMeetingControl(request, context) {
        
        var requestMethod = request.directive.header.name;
        var requestToken = request.directive.endpoint.scope.token;
        var room = request.directive.endpoint.scope.partition;
       
        
        if (requestMethod === "JoinMeeting") {

            var meetingId = request.directive.payload.meeting.id;
            // Make a call to the device cloud to start the meeting with
            // the specified token and room (partition).
            // deviceCloud.JoinMeeting(requestToken, room, meetingId) 


        }
        else if (requestMethod === "EndMeeting") {

            // Make a call to the device cloud to end the meeting with
            // the specified token and room (partition).
            // deviceCloud.EndMeeting(requestToken, room) 
        }
       
        var responseHeader = request.directive.header;
        responseHeader.name = "Alexa.Response";
        responseHeader.messageId = responseHeader.messageId + "-R";
        var response = {
            event: {
                header: responseHeader
            },
            payload: {}

        };
        log("DEBUG", "Alexa.ClientMeetingController ", JSON.stringify(response));
        context.done(null, response);
    } 
};

Step 3: Configure the ARNs for your lambda function in the developer portal

When you create and save your Lambda, you will provide this ARN in the developer console.

  • On the Configuration page for your skill, copy and paste the Lambda ARN into the Default text box.
  • Select Yes for Provide geographical region endpoints, select North America, and add the ARN in the text box.

Step 4: Add account linking information.

This enables IT administrators to link an enterprise account with your skill. Follow the steps in Authenticate an Alexa User to a User in Your System with Account Linking.

Step 5: Test your skill

You can test your skill using your developer account. Follow the instructions listed in Steps to Create a Smart Home Skill to find, enable and test your skill. You should be able to complete a discovery request and make requests of the skill.

Step 6: Choose private or Alexa Skills store distribution

When you create a skill, you can choose to distribute it privately, within a business, or complete the certification process and make it available to customers across businesses.

Create a private skill: If the skill will be privately distributed within an enterprise, you can make it a private skill and you do not need to submit the skill for certification. You must provide an entry in each section of the Publishing Information page of the developer portal in order to submit the skill, but this information is for your use only. When you have completed this information, use the Alexa Skill Management API to mark the skill manifest as private. Follow the instructions in Create and Publish Private Skills. These steps will walk you through marking the skill as private, and making it visible to the AWS Account that has access to the Alexa for Business console.

-or-

Provide publishing information and submit for certification: If you plan to publish the skill for use across multiple businesses, you must provide detailed publishing information and go through the certification process. In general, follow the instructions in the Smart Home Skill Publishing Guide. However, because the certification team will test your skill with the Alexa for Business console, you must provide additional information specified below:

Test Instructions: You must provide the following information for our certification team to enable and test your skill:

  • Account credentials: Provide a test account username and password for your device cloud so that the certification team can complete the account linking process.
  • A room identifier: Provide a room identifier that the certification team can configure in the Alexa for Business console. This identifier will be sent in the scope of a directive request to access a calendar or start a meeting and your skill must recognize this value.
  • Conferencing provider name: Specify the conferencing provider, which is sent in the payload of the message.
  • A meeting ID and optional pin Provide a meeting ID, and optional pin for that meeting for testing purposes
  • Dial-in number: This is not sent in the directive, but used to configure the conferencing provider in the Alexa for Business console.
  • Protocol/IP address: Provide the connection information for the conferencing provider

Step 7: Configure the skill in the Alexa for Business Console.

Use the Alexa for Business console to add the skill to your business’s Alexa devices. Follow the instructions in the Alexa for Business Administration Guide.