WebRTC Calling in Alexa Smart Properties

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

With Web Real-Time Communication (WebRTC) calling, you can make calls between Alexa devices and non-Alexa devices on your network. The following instructions provide the steps to onboard and implement WebRTC calling.

Note: Your cloud calling solution must be compliant with WebRTC specifications for call setup and media streaming.

WebRTC calling overview

Skill-based calling involves establishing calls between Alexa devices and customer devices on your network. In the context of WebRTC, a customer device is a non-Alexa device used for calling. This might be a web browser, an app on a mobile device, or another device on your property network that supports making and receiving calls. Staff and family members might use these devices to communicate with a resident or guest in an ASP unit. This topic uses the terms "device" and "customer device" to refer to these non-Alexa devices.

You need two components for establishing a call: signaling and media.

Signaling consists of exchanging network events and WebRTC Session Description Protocol (SDP) information between an Alexa device and your network.
Media is established by using a peer-to-peer connection between an Alexa device and your network through the standard WebRTC protocol.

You build an Alexa custom skill to handle signaling between Alexa and your devices. Alexa sends calling related requests to your skill. Your code handles these requests to place and receive calls between an Alexa device and your customer devices. These requests are part of the Alexa.Comms.CallSignaling interface that you must implement in your skill. Because the skill is a custom skill, you must provide a custom voice interface with a valid invocation name and at least one custom intent.

Prerequisites

Before you start, you must have the following items:

An Amazon developer account. The account is free.
An Alexa device. An Amazon Echo device that's compatible with WebRTC is required to test calling. For a list of devices, see Devices that support WebRTC, later.
An ASP base subscription for healthcare, senior living, hospitality, or core.

Note: Customers who have ASP subscriptions for healthcare or senior living can use both WebRTC video calling and WebRTC audio calling. Customers who have ASP subscriptions for core or hospitality can use WebRTC audio calling but can't use WebRTC video calling because these subscriptions don't support the camera feature. For feature availability, see Product feature comparison.

Devices that support WebRTC

The following Amazon devices support WebRTC:

Echo (2nd, 3rd, and 4th Gen)
Echo Dot (2nd, 3rd, 4th, and 5th Gen)
Echo Dot with clock (3rd, 4th, and 5th Gen)
Echo Plus (2nd Gen)
Echo Pop
Echo Show 5 (1st and 2nd Gen)
Echo Show 8 (1st, 2nd, and 3rd Gen)
Echo Show 15 (1st and 2nd Gen)
Echo Show 21

WebRTC requirements

You devices must meet the following requirements:

Support Datagram Transport Layer Security encryption as described in RFC5763.
Use Interactivity Connectivity Establishment (ICE) protocol RFC5245 and protocol RFC8445 to negotiate the media route with Alexa endpoints.
Your devices must not be on a VPN.
Use audio and video codecs that are supported by Alexa devices. The following table lists Alexa supported codecs.

Codecs type	Codecs	Relevant standard
Audio	Opus Audio Codec Note: The stereo parameter is treated as if stereo=0.	RFC7586
Audio	G.711	T-REC-G.711
Audio	G.722	T-REC-G.722
Video	H.264 constrained baseline	RFC6184
Video	VP 8	RFC7741

Important: The Trickle ICE is not supported

Activate the WebRTC add-on

You must enable the WebRTC Add-on for your ASP organization. Do the following steps:

Step 1: Create a security profile
Step 2: Enable API access
Step 3: Request the WebRTC add-on

Create a security profile

Access to the WebRTC APIs requires a Login with Amazon (LWA) security profile. If you have already configured a security profile for ASP REST API access, you can use your existing profile.

Note: To reuse your existing security profile, make sure that you know your Client ID and skip to Step 2: Enable API access.

To create a security profile

In the Login with Amazon console, sign in with your Amazon developer account, and then click Create a New Security Profile.
Enter your Security Profile Name, Security Profile Description, and Consent Privacy Notice URL.
For details about security profiles, see Security Profile.
Click Save.
After you save the security profile, Amazon issues a client ID and a client secret for your profile.
Save your client ID and client secret in a secure place. You need these values to enable API access.
To use LWA with a website, take the following additional steps in the Login with Amazon console:
1. To the right of your security profile name, under Manage, click the gear icon.
2. Click the Web Settings tab.
3. At the bottom, click Edit.
4. Under Allowed Return URLs, register a callback URL.
5. Click Save.
Tip: If you don't have a return URL and you plan to use a REST client to interact with the API, enter https://example.com/login.

Enable API access

Make sure you have the LWA Client ID from your security profile. For instructions to enable API access, see Manage API Access.

Request the WebRTC add-on

To request the WebRTC add-on package

Sign on to the ASP management console.
Navigate to the Billing & Subscriptions page and click the Add-ons tab.
Under the WebRTC section, click Request add-on.

Note: An Alexa Smart Properties Solutions Architect provides confirmation to you when the add-on has been activated.

Steps to onboard and build a WebRTC-based skill

Note: Work with your ASP Solutions Architect to onboard your skill with ASP.

The skill you build to implement WebRTC serves as a middleware solution to connect your customer devices and Alexa. Alexa sends calling related requests to your skill. Your code handles these requests to place and receive calls between an Alexa device and your customer devices.

Typical workflow

To onboard and build a skill that supports skill-based calling, complete the following steps:

Get an access token
Create a service provider
Build a skill that implements WebRTC-based calling
Map your skill with the service provider
Enable the WebRTC subscription skill on unit
Associate devices on your network with the service provider
Define contacts and assign an address book to units

The following diagram illustrates this workflow.

Step 1: Get an access token

You must have an LWA access token to perform any API operation.

For details about how to get an access token, see Integrate with LWA to get an API access token. In your request, use the LWA scope, called amazon_communication::service_provider. Contact your ASP Solution Architect to get access to the LWA scope.

Step 2: Create a service provider

To onboard yourself as a service provider, use the Self Service Onboarding REST API. Call the Create a service provider API operation.

The following example shows a POST request for creating a service provider. Replace the {access token} the access token you retrieved previously. Replace the values for the serviceProviderLogicalId and displayName.value properties. For detailed explanations, see Create a service provider.

POST /v1/communications/serviceProviders HTTP/1.1
Host: api.amazonalexa.com
Content-type: application/json  
Authorization:  Bearer {access token}

{
    "serviceProviderLogicalId" : "service.provider.logical.id.1",
    "displayName": [
       {
          "locale": "en-US",
          "value": "Example Service Provider"
       }
    ]
}

Important: After you create the new service provider, save the serviceProviderId from the response body. You use this ID with the Get the service provider information operation to retrieve the service provider. There isn't an operation to retrieve a list of all service providers.

Step 3: Build a skill that implements WebRTC-based calling

To build the skill, complete the following sub-steps:

Step 3.1: Create a custom skill
Step 3.2: Implement account linking
Step 3.3: Write your code to implement the Calling APIs
Step 3.4: Certify and publish your skill

Step 3.1: Create a custom skill

You use a custom skill to implement the skill-based calling feature. The skill performs the WebRTC signaling between the Alexa device and your customer devices. To learn more about WebRTC signaling, see Signaling and video calling in MDN Web Docs.

To create a custom skill in the Alexa developer console

Sign in to your Alexa Developer Console, and then choose to create a custom skill.
Click Create Skill, type a name for the skill and choose a locale, and then click Next.
On the Experience, Model, Hosting service page, choose Other as the type, choose Custom model, choose a host service based on your need, and then click Next.
On the Templates page, keep the default choice Start from Scratch, and click then Next.
On the Review page, review your selections, and then click Create Skill.
After your skill is created, make sure that you're on the Build tab.
From the left-hand panel, click TOOLS, choose Permissions, and then enable Communication-Calling.

Note: If you use the ASK CLI or SMAPI to create the skill instead of the developer console, make sure that you add the permission amazon_communication::calling to the skill manifest.

Step 3.2: Implement account linking

To send requests to Alexa as described in Requests Exposed by Alexa.Comms.CallSignaling Interface, your skill must implement an OAuth 2.0 exchange to obtain an access token that's valid outside of the skill invocation. For implementation details, see Request Access to the Alexa Event Gateway.

Specifically, your skill must implement Alexa.Authorization.AcceptGrant and exchange the authorization code for an access and refresh token. You then use this access token to send events to Alexa by using the API described in Requests Exposed by Alexa.Comms.CallSignaling Interface.

When Alexa invokes your skill for a request originating from an Alexa endpoint, the request to the skill should contain the access token to authenticate with your cloud.

After you implement account linking, you must enable the following items for your WebRTC skill:

Account linking. For ASP, you must enable the skill for the Alexa endpoints. To enable endpoints to use your skill, Amazon recommends that you use delegated account linking so that you only maintain one pair of access and refresh tokens. For details, see How to use delegated account linking.
Persistent Unit IDs. For details, see Set up your skill to request PersistentUnitId or PersistentEndpointId permissions.

Step 3.3: Write your code to implement the Calling APIs

To enable calls between Alexa endpoints and your customer devices, you implement the Alexa.Comms.CallSignaling Service Provider Interface (SPI) in your skill. You also must implement logic for sending signaling to Alexa as a request and responding to these signaling events by using APIs exposed by the Alexa.Comms.CallSignaling Interface.

Write code for processing calls from Alexa to your devices

You must implement the following Alexa.Comms.CallingSignaling Service Provider Interfaces (SPI) in your Alexa skill for establishing call connections from Alexa to your non-Alexa devices. When a customer starts a call from Alexa, Alexa sends the InitiateOutboundCall to your skill, and then your skill should send a deferred response to Alexa.

For detailed explanations about the Alexa.Comms.CallSignaling SPI, see Alexa.Comms.CallSignaling Service Provider Interface.

Write code for processing calls from your devices to Alexa

When a customer initiates a call from a device on your network to an Alexa endpoint, your skill should send signaling information as a request to Alexa. Alexa sends a response to your skill. Amazon exposes the following requests for your skill to respond. Your skill should forward the events received to your network cloud service.

For request formats, sample requests, and responses, see Requests Exposed by Alexa.Comms.CallSignaling Interface.

Step 4: Map your skill with your service provider

Use the Service Provider Network Mapping API to associate your skill ID with your service provider ID.

To copy your skill ID, sign in to the Alexa developer console. Find your skill in the list and click the Copy Skill ID link.

The Copy Skill ID link displays below the skill name in the developer console list

The following example shows a POST request for creating the network mapping. Replace the following placeholders in the example when creating your call to the API:

Replace {access token} with your token retrieved previously. For details on this earlier step, see Step 1: Get an access token.
Replace {skillId} with the ID for the WebRTC skill you created.
In the request path, replace {serviceProviderID} with the service provider ID you created previously. For details on this earlier step, see Step 2: Create a service provider.

POST /v1/communications/serviceProviders/{serviceProviderId}/network HTTP/1.1
Host: api.amazonalexa.com
Content-type: application/json  
Authorization:  Bearer {access token}

{
  "networkType": "SKILL",
  "skillConfiguration": {
    "skillId": "{skillId}"
  }
}

For details about the Service Provider Network Mapping API, see Create network mapping.

Step 5: Enable the WebRTC subscription skill on the unit

You enable the WebRTC add-on subscription skill on each unit where you want to perform calling through WebRTC. This is a skill provided by Amazon that enables WebRTC in the unit. Do this step before you enable the signaling skill you built earlier.

The skill ID for the WebRTC subscription skill is amzn1.ask.skill.4f802665-333c-48e7-ada2-b218033d4015.

Do one of the following:

Use the Skill Management API to enable the WebRTC subscription skill. Use the Enable skill for a unit operation and provide the skill ID in the path.
Use the ASP console.

Enable the WebRTC subscription skill in the ASP console

Log in to the console and navigate to the Rooms page, and then open the page for the room.
Click Enable property skill.
Enter the WebRTC subscription skill ID in the Skill ID field.
Select the Live stage.
Click Enable skill.

Step 6: Enable your WebRTC signaling skill

After you enable the WebRTC add-on subscription skill on a unit, you can enable your WebRTC signaling skill built in Step 3.

If you use delegated account linking in your skill, do the following:

Sign in to the Alexa App using your Amazon Business credentials. These credentials must be the same ones you used to register with Alexa Smart Properties as a skill provider.
Enable your skill for your Amazon Business account. This links your skill provider account to the skill.
Enable the skill in the ASP unit. You can use either the Skill Management API or the ASP console. Provide the skill ID for the skill that you built in step 3.

For more about managing skills with ASP, see Manage Skills in Alexa Smart Properties

Step 7: Associate property units with your service provider

You must register a unique identifier representing each unit in your WebRTC system to make or receive calls.

To support calling, a unit must have a communications profile. Use the Create a communication profile operation and provide the unit ID and a display name in the request body. If a profile already exists for the unit, this operation returns the existing profileID for the unit.

The following example shows the POST request to create a communication profile.

POST /v1/communications/profile HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

{
  "entity": {
    "type": "UNIT",
    "id": "amzn1.alexa.unit.did.1234"
  },
  "name": "Jane Doe"
}

Next, use the Account Association API to associate units with your service provider ID. Use the Create account association operation. You make a POST request and include your service provider ID in the request path, and the communications profile ID as part of the request body.

The following example shows a POST request for associating a communications profile with your service provider. Replace the following placeholders in the example when creating your call to the API:

Replace {access token} with your token retrieved previously. For details on this earlier step, see Step 1: Get an access token.
In the request path, replace {serviceProviderID} with the service provider ID you created previously. For details on this earlier step, see Step 2: Create a service provider.
Replace {externalUserId} with a unique identifier representing the unit in your WebRTC system.
Replace {amazonId} with the communication profile ID for the unit.
Keep amazonIdType set to communication-profile.

POST /v1/communications/serviceProviders/{serviceProviderID}/externalUsers HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

{
  "externalUserId": "{externalUserId}",
  "amazonId": "{amazonId}",
  "amazonIdType": "communication-profile"
}

Step 8: Define contacts and assign an address book to units

To place and receive calls, a unit must have at least one address book. The address book contains the set of contacts that users can call and from which they can receive calls. You create an address book, define the contacts, and then associate the address book with a unit.

Create an address book

Use the Create an address book operation to create a new address book. Provide a name for the address book in the request body. The operation returns the address book ID.

POST /v1/addressBooks HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

{
  "name": "Room 101 Address Book"
}

Create contacts in the address book

Use the Create a contact operation to add each contact to the address book. Provide the address book ID in the path of the POST request. Provide details about the contact in the request body.

Each contact has a "friendly name" that the user can say to call the contact. For example, if the name is "caregiver," the user can say "Alexa, call my caregiver" to place a call to the contact. Set this name in the name property of the request body.

The contact also has an ID used for receiving calls:

For a contact that represents a unique network address on your network, set the providerContact.id in the request body to the unique network address.
For a contact that represents an Alexa device in a unit, set the alexaCommunicationProfileId property in the request body to the communication profile ID for the unit.

The following example shows the POST request to create a new contact in an address book. This contact represents a non-Alexa device in the network.

POST /v1/addressBooks/amzn1.alexa.addressbook.did.12345/contacts HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

{
  "contact": {
    "name": "Caregiver",
    "providerContact": {
      "id": "0123456789"
    }
  }
}

Note: You can create the contacts before or after you associate the address book to the unit.

Associate the address book with a unit

To make the contacts available to the unit, associate the address book with the unit. Use the Create an address book association API operation. Provide the address book ID in the path of the POST request and the unit ID in the request body.

The following example shows the POST request to associate an address book with a unit.

POST /v1/addressBooks/{addressBookId}/unitAssociations HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

{
    "unitId": "amzn1.alexa.unit.did.1234"
}

Step 9: Certify and publish your skill

After have finished building and testing your skill, review it with your Amazon Solutions Architect point of contact and then submit it for certification.

You must provide a valid existing setup to the certification team to test your WebRTC integration. You provide these details in the Testing Instructions:

The ASP unit to test the integration.
The expected locales for the WebRTC integration
Links to your web browser or mobile app
Instructions about how to use your web or mobile app integration with WebRTC.
Credentials of a test account

Test WebRTC calling

After you complete all the steps, test the following:

Place a call from an Alexa device to a device on your network.
Place a call from a device on your network to an Alexa device.

Note: The device must not be on a VPN.

Was this page helpful?

Provide feedback

Last updated: Dec 17, 2024