Alexa.RTCSessionController Interface 3
Implement the Alexa.RTCSessionController
interface in your Alexa skill for devices that are capable of real-time communication. By using the Alexa.RTCSessionController
interface in your skill, Alexa users can communicate remotely with their security cameras and other devices. For example, users can communicate with a visitor at their front door. For more details about security skills, see Smart Home Security Overview.
For the list of languages that the Alexa.RTCSessionController
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
To develop and test your Alexa skill, you can use the Smart Home debugger to see logs from your WebRTC sessions in real-time. For details, see Smart Home Debugger for WebRTC Skills.
Utterances
The Alexa.RTCSessionController
interface uses the pre-built voice interaction model. Users can start conversations by using one of the following utterances:
Alexa, show me the front door camera
Alexa, answer the front door.
Alexa, talk to the front door.
Alexa, talk to the backyard camera.
Alexa, talk to the baby monitor.
Alexa, get the call going with the front door.
Alexa, please call front door.
Alexa, respond to the front door.
Alexa, speak to the front door.
Alexa, talk to my front door camera.
Alexa, talk to the person at the main door.
Users can end conversations by using one of the following utterances:
Alexa, go home.
Alexa, stop.
After the user says one of these utterances, Alexa sends a corresponding directive to your skill.
Discovery
You describe endpoints that support Alexa.RTCSessionController
using the standard discovery mechanism described in Alexa.Discovery. In addition, identify if duplex is supported in the configuration of the Alexa.RTCSessionController
capability.
Use CAMERA
or DOORBELL
for the display category. For the full list of display categories, see display categories.
In addition to the usual discovery response fields, for the Alexa.RTCSessionController
entry in the capabilities array, include a configuration object that contains the following fields.
Field | Description | Type |
---|---|---|
isFullDuplexAudioSupported |
True if the device supports 2-way (full duplex) communication. False if the device supports 1-way (half duplex) communication. The default is false. If your device doesn't support audio communication, set the value to false and include an `a=sendonly` attribute. | Boolean |
Discover response example
The following example shows a Discover.Response
message for a security camera that supports the Alexa.RTCSessionController
and Alexa.EndpointHealth
interfaces.
{
"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": "My front door camera",
"displayCategories": ["CAMERA"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.RTCSessionController",
"version": "3",
"configuration": {
"isFullDuplexAudioSupported": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [
{
"name":"connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Directives and events
The Alexa.RTCSessionController
interface defines the following directives and events.
InitiateSessionWithOffer directive
Support the InitiateSessionWithOffer
directive so that users can initiate a real-time communication session with a front door device.
The following example shows a user utterance:
Alexa, talk to my front door camera
InitiateSessionWithOffer directive example
The following example illustrates an InitiateSessionWithOffer
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.RTCSessionController",
"name": "InitiateSessionWithOffer",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {
"sessionId" : "Session identifier",
"offer": {
"format" : "SDP",
"value" : "an SDP offer value"
}
}
}
}
InitiateSessionWithOffer directive payload
Field | Description | Type |
---|---|---|
sessionId |
Identifies the session that wants to connect. | Version 4 UUID. |
offer |
SDP offer. | String |
InitiateSessionWithOffer response
If you handle a InitiateSessionWithOffer
directive successfully, respond with an AnswerGeneratedForSession
event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
AnswerGeneratedForSession event example
The following example shows an AnswerGeneratedForSession
event.
{
"event": {
"header": {
"namespace": "Alexa.RTCSessionController",
"name": "AnswerGeneratedForSession",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"answer": {
"format" : "SDP",
"value" : "an SDP answer value"
}
}
}
}
AnswerGeneratedForSession event payload
Field | Description | Type |
---|---|---|
answer |
An SDP answer. | String |
InitiateSessionWithOffer directive error handling
If you can't handle a InitiateSessionWithOffer
directive successfully, respond with an Alexa.ErrorResponse event. If the customer needs to configure the camera, return the NOT_SUPPORTED_IN_CURRENT_MODE
error type and include the currentDeviceMode
field with a value of NOT_PROVISIONED
.
SessionConnected directive
The SessionConnected
directive notifies you that your RTC session is connected.
SessionConnected
directive.SessionConnected directive example
The following example illustrates a SessionConnected
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.RTCSessionController",
"name": "SessionConnected",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {
"sessionId" : "Session identifier"
}
}
}
SessionConnected directive payload
Field | Description | Type |
---|---|---|
sessionId |
Identifies the session from the original InitiateSessionWithOffer directive. |
Version 4 UUID |
SessionConnected response
If you handle a SessionConnected
directive successfully, respond with an SessionConnected
event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
SessionConnected event example
{
"event": {
"header": {
"namespace": "Alexa.RTCSessionController",
"name": "SessionConnected",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"sessionId" : "Session identifier"
}
}
}
SessionConnected event payload
Field | Description | Type |
---|---|---|
sessionId |
Identifies the session from the original InitiateSessionWithOffer directive. |
Version 4 UUID |
SessionConnected directive error handling
If you can't handle a SessionConnected
directive successfully, respond with an Alexa.ErrorResponse event.
SessionDisconnected directive
The SessionDisconnected
directive notifies you that your RTC session is disconnected.
SessionDisconnected directive example
The following example illustrates a SessionDisconnected
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.RTCSessionController",
"name": "SessionDisconnected",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {
"sessionId" : "Session identifier"
}
}
}
SessionDisconnected directive payload
Field | Description | Type |
---|---|---|
sessionId |
Identifies the session from the original InitiateSessionWithOffer directive. |
Version 4 UUID |
SessionDisconnected response event
If you handle a SessionDisconnected
directive successfully, respond with an SessionDisconnected
event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
SessionDisconnected event example
{
"event": {
"header": {
"namespace": "Alexa.RTCSessionController",
"name": "SessionDisconnected",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"sessionId" : "Session identifier"
}
}
}
SessionDisconnected event payload
Field | Description | Type |
---|---|---|
sessionId |
Identifies the session from the original InitiateSessionWithOffer directive. |
Version 4 UUID |
SessionDisconnected directive error handling
If you can't handle a SessionDisconnected
directive successfully, respond with an Alexa.ErrorResponse event.
State reporting
Alexa sends a ReportState
directive to request information about the state of an endpoint. When Alexa sends a ReportState
directive, you send a StateReport
event in response. The response contains the current state of all the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.
Alexa.RTCSessionController
interface doesn't define any retrievable properties. However, if you also implement other interfaces in the skill for your camera device, you must participate in state reporting for the properties in those interfaces.StateReport response example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Change reporting
You send a ChangeReport
event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.
Alexa.RTCSessionController
interface doesn't define any proactively reportable properties. However, if you also implement other interfaces in the skill for your camera device, you must participate in change reporting for the properties in those interfaces.ChangeReport event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"change": {
"cause": {
"type": "PERIODIC_POLL"
},
"properties": [
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "UNREACHABLE"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {
"properties": [
]
}
}