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.

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.

An employee enters a conference room and says, "Alexa, start the meeting" to the Alexa device in that room.

Alexa sends a directive to to the calendar API to find the meeting or asks the employee if the want to start an instant meeting or asks for the meeting ID, which the employee provides. Alexa sends the necessary directives to obtain meeting information and start the meeting. A directive includes:

Information authenticating the request and the location (called a partition) where it originated.

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.

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.

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.

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

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.

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."

"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:

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.

Your code accesses the calendar for that room, finds the meeting ID and sends the meeting back to Alexa in a response event.

Alexa sends a MeetingClientController.JoinMeeting directive with the meeting specified in the previous response.

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);}elseif(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);}}functionhandleDiscovery(request,context){varpayload={"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"}]}]};varheader=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}});}functionlog(message,message1,message2){console.log(message+message1+message2);}functionhandleMeetingControl(request,context){varrequestMethod=request.directive.header.name;varrequestToken=request.directive.endpoint.scope.token;varroom=request.directive.endpoint.scope.partition;if(requestMethod==="JoinMeeting"){varmeetingId=request.directive.payload.meeting.id;//Makeacalltothedevicecloudtostartthemeetingwith//thespecifiedtokenandroom(partition).//deviceCloud.JoinMeeting(requestToken,room,meetingId)}elseif(requestMethod==="EndMeeting"){//Makeacalltothedevicecloudtoendthemeetingwith//thespecifiedtokenandroom(partition).//deviceCloud.EndMeeting(requestToken,room)}varresponseHeader=request.directive.header;responseHeader.name="Alexa.Response";responseHeader.messageId=responseHeader.messageId+"-R";varresponse={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 console

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

On the Build page for your skill, copy and paste the Lambda ARN into the Default endpoint 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. See:

Conference skills need to meet the same account linking requirements as smart home skill.

Important: Do not move the slider for Send Alexa Events box under the Permissions section. This is for asynchronous replies to Alexa, and does not apply to conferencing skills.

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, mark the skill as an Alexa for Business Organizations skill on the Availability page of the developer console, or use the Alexa Skill Management API to mark the skill manifest as private. To use the skill management API, 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