Alexa.RTCSessionController Interface 3

Implement the Alexa.RTCSessionController interface in your Alexa add-on for devices that are capable of real-time communication with the Web Real-Time Communication (WebRTC) protocol. By using the Alexa.RTCSessionController interface in your add-on, 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 add-ons, see Smart Home Security Overview. If you support mode-based camera settings, such as setting a camera to an “Away” mode, you can also implement the Alexa.SecurityPanelController interface. To develop and test your Alexa add-on, 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 Add-ons. 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.

Utterances

The Alexa.RTCSessionController interface uses the pre-built voice interaction model. After the user says one of these utterances, Alexa sends a corresponding directive or report state request to your add-on. Users can start conversations by using one of the following utterances:

Users can end conversations by using one of the following utterances:

Real time streaming protocol usage

You can build an Alexa add-on for security cameras, video doorbells, and other devices that stream video and audio by using the WebRTC protocol. For details, see About the Real-Time Communication Interface.

Discovery

You describe endpoints that support Alexa.RTCSessionController using the standard discovery mechanism described in Alexa.Discovery. In addition, identify duplex support in the configuration of the Alexa.RTCSessionController capability. Use CAMERA, or both CAMERA and DOORBELL, for the display category. For example, for camera devices, use CAMERA. For video doorbells with a camera, use both CAMERA and DOORBELL categories. For the full list of display categories, see display categories. To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Configuration object

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`	Set to `true` if the device supports 2-way (full duplex) communication. Set to `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 doorbell",
          "displayCategories": ["CAMERA", "DOORBELL"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RTCSessionController",
              "version": "3",
              "configuration": {
                "isFullDuplexAudioSupported": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3.1",
              "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 start a real-time communication session with a front door device. The following examples show user utterances:

InitiateSessionWithOffer directive example

The following example illustrates an InitiateSessionWithOffer directive that Alexa sends to your add-on.

{
  "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 an 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 an 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. If the camera or connected hub is offline, return ENDPOINT_UNREACHABLE.

SessionConnected directive

The SessionConnected directive notifies you that your WebRTC session is connected.

SessionConnected directive example

The following example illustrates a SessionConnected directive that Alexa sends to your add-on.

{
  "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 a 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 WebRTC session is disconnected.

SessionDisconnected directive example

The following example illustrates a SessionDisconnected directive that Alexa sends to your add-on.

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

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.

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": [
    ]
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.RTCSessionController Interface 3

Utterances

Real time streaming protocol usage

Discovery

Configuration object

Discover response example

Directives and events

InitiateSessionWithOffer directive

InitiateSessionWithOffer directive example

InitiateSessionWithOffer directive payload

InitiateSessionWithOffer response

AnswerGeneratedForSession event example

AnswerGeneratedForSession event payload

InitiateSessionWithOffer directive error handling

SessionConnected directive

SessionConnected directive example

SessionConnected directive payload

SessionConnected response

SessionConnected event example

SessionConnected event payload

SessionConnected directive error handling

SessionDisconnected directive

SessionDisconnected directive example

SessionDisconnected directive payload

SessionDisconnected response event

SessionDisconnected event example

SessionDisconnected event payload

SessionDisconnected directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Real time streaming protocol usage

​Discovery

​Configuration object

​Discover response example

​Directives and events

​InitiateSessionWithOffer directive

​InitiateSessionWithOffer directive example

​InitiateSessionWithOffer directive payload

​InitiateSessionWithOffer response

​AnswerGeneratedForSession event example

​AnswerGeneratedForSession event payload

​InitiateSessionWithOffer directive error handling

​SessionConnected directive

​SessionConnected directive example

​SessionConnected directive payload

​SessionConnected response

​SessionConnected event example

​SessionConnected event payload

​SessionConnected directive error handling

​SessionDisconnected directive

​SessionDisconnected directive example

​SessionDisconnected directive payload

​SessionDisconnected response event

​SessionDisconnected event example

​SessionDisconnected event payload

​SessionDisconnected directive error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Real time streaming protocol usage

Discovery

Configuration object

Discover response example

Directives and events

InitiateSessionWithOffer directive

InitiateSessionWithOffer directive example

InitiateSessionWithOffer directive payload

InitiateSessionWithOffer response

AnswerGeneratedForSession event example

AnswerGeneratedForSession event payload

InitiateSessionWithOffer directive error handling

SessionConnected directive

SessionConnected directive example

SessionConnected directive payload

SessionConnected response

SessionConnected event example

SessionConnected event payload

SessionConnected directive error handling

SessionDisconnected directive

SessionDisconnected directive example

SessionDisconnected directive payload

SessionDisconnected response event

SessionDisconnected event example

SessionDisconnected event payload

SessionDisconnected directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics