Alexa.RTCSessionController Interface 3

Note: Sign in to the developer console to build or publish your skill.

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. After the user says one of these utterances, Alexa sends a corresponding directive or report state request to your skill.

Note: At this time, there are no user utterances to control the live feed in the Alexa app.

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, speak 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, talk to my front door camera.
Alexa, talk to the person at the main door.

Alexa, montre-moi la caméra de la porte d'entrée.
Alexa, réponds à la porte d'entrée.
Alexa, parle à la porte d'entrée.
Alexa, parle à la caméra du jardin.
Alexa, parle au babyphone.
Alexa, passe l'appel avec la porte d'entrée.
Alexa, appelle la porte d'entrée.
Alexa, réponds à la porte d'entrée.
Alexa, parle à ma porte d'entrée.
Alexa, parle à la personne à la porte.

Alexa, zeige mir die Haustürkamera.
Alexa, beantworte die Haustür.
Alexa, spreche zur Haustür.
Alexa, spreche mit der Haustür.
Alexa, sprich mit der Hinterhofkamera.
Alexa, spreche mit dem Baby-Monitor.
Alexa, nehme den Anruf mit der Haustür an.
Alexa, bitte rufe die Haustür an.
Alexa, antworte auf die Haustür.
Alexa, rede mit meiner Haustürkamera.
Alexa, spreche mit der Person an der Haupttür.

Alexa, मुझे फ्रंट डोर कैमरा दिखाओ
Alexa, सामने वाले दरवाजे का जवाब दो।
Alexa, सामने वाले दरवाजे से बात करो।
Alexa, सामने वाले दरवाजे से बोलो।
Alexa, पिछवाड़े के कैमरे से बात करो।
Alexa, बेबी मॉनिटर से बात करो।
Alexa, सामने वाले दरवाज़े से बात शुरू करो।
Alexa, सामने वाले दरवाज़े से बात शुरू करो।
Alexa, सामने के दरवाजे पर जवाब दो।
Alexa, मेरे सामने वाले दरवाज़े के कैमरे से बात करो।
Alexa, मुख्य दरवाजे पर बैठे व्यक्ति से बात करो।

Alexa, mostrami la videocamera della porta.
Alexa, rispondi alla porta principale.
Alexa, parla con la porta d'ingresso.
Alexa, parla alla porta d'ingresso.
Alexa, parla con la videocamera del cortile.
Alexa, parla con il baby monitor.
Alexa, ricevi la chiamata dalla porta principale.
Alexa, per favore chiama la porta d'ingresso.
Alexa, rispondi alla porta d'ingresso.
Alexa, parla con la videocamera della mia porta d'ingresso.
Alexa, con la persona alla porta principale.

アレクサ、玄関のカメラを見せて
アレクサ、玄関に答えて
アレクサ、玄関に話しかけて
アレクサ、玄関に話して
アレクサ、裏庭のカメラに話しかけて
アレクサ、ベビーモニターに話しかけて
アレクサ、玄関のカメラと通話して
アレクサ、玄関のカメラにかけて
アレクサ、玄関に応答して
アレクサ、玄関のカメラに話しかけて
アレクサ、玄関にいる人に話しかけて

Alexa, mostra a câmera da porta da frente.
Alexa, atende a porta da frente.
Alexa, fale com a porta da frente.
Alexa, fale com a câmera do pátio.
Alexa, fale com o monitor do bebê.
Alexa, ligue para a porta da frente.
Alexa, favor ligar para a porta da frente.
Alexa, responda a porta da frente.
Alexa, fale com minha porta da frente.
Alexa, fale com a pessoa na porta principal.

Alexa, muéstrame la cámara de la puerta principal.
Alexa, contesta a la puerta principal.
Alexa, habla con la puerta principal.
Alexa, habla con la cámara del patio trasero.
Alexa, habla con el vigila bebés.
Alexa, habla con el monitor del bebé.
Alexa, empieza la llamada con la puerta del frente.
Alexa, llama a la puerta del frente.
Alexa, contesta a la puerta frontal.
Alexa, habla con la cámara de mi puerta frontal.
Alexa, habla con la persona en la puerta.

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

Alexa, go home.
Alexa, stop.

Alexa, accueil.
Alexa, stop.

Alexa, geh nach Hause.
Alexa, stopp.

Alexa, घर जाओ।
Alexa, रुको।

Alexa, vai a casa.
Alexa, fermati.

アレクサ、ホームに戻って
アレクサ、ストップ

Alexa, vá para casa.
Alexa, vai para a tela inicial.
Alexa, pare.

Alexa, pagina de inicio.
Alexa, pantalla principal.
Alexa, detente.

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.

Important: If your device supports multiple display categories, make sure that you list CAMERA before other categories in the displayCategories list.

To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Important: After you send the discovery response, don't send AddOrUpdateReport to add and remove the Alexa.RTCSessionController capability based on the device state. Instead, when your device is in a state that can't handle the request, respond to a directive from Alexa with the appropriate error code. For example, if the bridge connected to the camera is offline, respond with the BRIDGE_UNREACHABLE error in the Alexa.ErrorResponse.

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

Note: If your camera supports one or more of pan, tilt, and zoom, see discovery response example for a camera that supports pan, tilt, and zoom instead.

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": "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.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 start a real-time communication session with a front door device.

The following examples show user utterances:

Alexa, talk to my front door camera.

Alexa, parle à ma porte d'entrée.

Alexa, rede mit meiner Haustürkamera.

Alexa, मेरे सामने वाले दरवाज़े के कैमरे से बात करो।

Alexa, parla con la videocamera della mia porta d'ingresso.

アレクサ、玄関のカメラに話しかけて

Alexa, fale com minha porta da frente.

Alexa, habla con la cámara de mi puerta frontal.

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.

Copied to clipboard.

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

SessionConnected directive

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

Note: Alexa doesn't always send the 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

Copied to clipboard.

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

Copied to clipboard.

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

Important: The 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

Copied to clipboard.

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

Important: The 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

Copied to clipboard.

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

Was this page helpful?

Provide feedback

Last updated: Nov 22, 2023

Alexa.RTCSessionController Interface 3

Utterances

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

Was this page helpful?