Use the Smart Home Debugger for WebRTC Add-ons
If you implement the Alexa.RTCSessionController interface in your Alexa smart home add-on, you can use the smart home debugger to test and debug your add-on. For example, when your add-on controls a smart home security camera, the user can say "Alexa, show me my front door camera", and the video feed from your camera appears on the user's Alexa device.
While you're developing and testing your Alexa add-on, you can use the smart home debugger to see logs from your WebRTC sessions in real-time. You can verify correct behavior, or find problems, such as the following:
- Incorrect DTLS version
- Invalid SDP answer
- Invalid or missing ICE candidates
- Unsupported codecs
- Incorrect JSON formatting
For details about debugging problems with Alexa.ChangeReport, Alexa.AddOrUpdateReport, and Alexa.DeleteReport events, see Use the Smart Home Debugger.
RTCSessionController events.Prerequisites
To use the smart home debugger during your WebRTC session, you need the following:
- Your add-on must communicate with a device that's capable of real-time communication (RTC).
- Your add-on must implement the Alexa.RTCSessionController interface.
- You must have an Alexa device to use to test your add-on, such as a Fire TV or any Echo device, such as an Echo Dot, Echo Plus, Echo Show, or Echo Spot.
Accessing the smart home debugger
To access the smart home debugger, you use the Alexa developer console.
To view the smart home debugger
-
Sign in to the Alexa developer console.
-
Open the smart home add-on associated with your smart home device.
-
Open the Test page.
-
Enable testing for the add-on.
-
At the top of the page, select Device Log and Smart Home Debugger.
-
In the Smart Home Debugger section of the page, use the toggle to enable Smart Home debugger.
After you complete the procedure, begin testing your add-on by interacting with your RTC device. Event information appears in the device log.
Viewing events
The smart home debugger shows logs for the events that Alexa receives from your add-on, for the Amazon account that you used to sign in to the Alexa developer console. Each event in the device log contains a JSON document with details about the event that Alexa received.
If you encounter problems with the smart home debugger, send the details to Amazon by using the Alexa Developer Contact Us page.
Example event with success
The following example shows the log in the smart home debugger for a SessionDisconnected event that Alexa is able to process successfully. The event field contains the JSON of the event that you sent to Alexa.
{
"header": {
"namespace": "SkillDebugger",
"name": "CaptureDebuggingInfo",
"messageId": "message ID"
},
"payload": {
"skillId": "skill id",
"timestamp": "2020-09-29T19:08:14.545Z",
"dialogRequestId": null,
"skillRequestId": null,
"type": "RTCSessionControllerSuccess",
"content": {
"eventType": "SessionDisconnectedResponse",
"event": {}
}
}
}
Example event with success on session connected
The following example shows the log in the smart home debugger for a change in connection state that Alexa processes successfully.
{
"header": {
"namespace": "SkillDebugger",
"name": "CaptureDebuggingInfo",
"messageId": "message ID"
},
"payload": {
"skillId": "skill id",
"timestamp": "2020-09-29T19:08:14.545Z",
"dialogRequestId": null,
"skillRequestId": null,
"type": "RTCSessionControllerSuccess",
"content": {
"eventType": "ConnectionStateEvent",
"event": {
"oldState": "DISCONNECTED",
"newState": "CONNECTED"
}
}
}
}
Example event with success on media flowing
The following example shows the log in the smart home debugger when Alexa is able to process RTC media. The state field can be FLOWING or NOT_FLOWING. The mediaType field can be AUDIO, DATA, or VIDEO.
{
"header": {
"namespace": "SkillDebugger",
"name": "CaptureDebuggingInfo",
"messageId": "message ID"
},
"payload": {
"skillId": "skill id",
"timestamp": "2020-09-29T19:08:14.545Z",
"dialogRequestId": null,
"skillRequestId": null,
"type": "RTCSessionControllerSuccess",
"content": {
"eventType": "MediaFlowOutStateChangeEvent",
"event": {
"state": "FLOWING",
"mediaType": "VIDEO"
}
}
}
}
Example event with error
The following example shows the log in the smart home debugger for an SessionDisconnected event that Alexa is unable to process successfully. The event field contains the JSON of the event that you sent to Alexa.
{
"header": {
"namespace": "SkillDebugger",
"name": "CaptureDebuggingInfo",
"messageId": "message ID"
},
"payload": {
"skillId": "skill id",
"timestamp": "2020-09-29T19:08:14.545Z",
"dialogRequestId": null,
"skillRequestId": null,
"type": "RTCSessionControllerFailure",
"content": {
"eventType": "SessionDisconnectedException",
"errorCode": "LAMBDA_GENERAL_ERROR",
"errorMessage": "Lambda general error message.",
"event": null
}
}
}
RTCSessionController error codes
The following table lists the error codes that you might see in the smart home debugger for RTCSessionController events.
| Error Code | Error Message |
|---|---|
SETUP_EVENT_ERROR |
Too many concurrent requests. |
NO_VIDEO_ERROR |
Couldn't establish connection because timeout occurred waiting on video. |
CONNECTION_ERROR |
Failed to establish the connection. |
INTERNAL_ERROR |
Internal Exception occurred establishing connection. |
Related topics
- View Device State to Test and Debug your Smart Home Add-on
- About the Automated Testing Service
- Smart Home Test
- Test and Debug Your Smart Home Add-on
- Steps to Build Smart Home Add-ons
- Works with Alexa Overview
- Use the Smart Home Live Debugger Tool to Test, Debug, and Speed Up Your Camera WebRTC Integration
Last updated: May 13, 2026
