WebRTC Calling in Alexa Smart Properties
The following instructions walk you through the steps to onboard and implement WebRTC (Web Real-Time Communication) calling in your Alexa skill. With WebRTC calling, your customers can make calls between Alexa devices and endpoints on your network.
Overview
Skill-based calling involves establishing calls between Alexa devices and endpoints on your network. 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.
Prerequisites
Before you start, you must have the following items:
- An Amazon developer account. The account is free.
- An Alexa device. To test your skill in an Alexa Smart Properties (ASP) environment, you need an Amazon Echo device that's compatible with ASP. For more details, see supported devices.
- An ASP base subscription for healthcare, senior living, hospitality, or core.
- The WebRTC add-on subscription. You can request the subscription on the ASP console under Billing & Subscriptions.
- Your endpoints on your network. Your endpoints must meet the following requirements:
- Your endpoints must support Datagram Transport Layer Security encryption as described in RFC5763.
- Your endpoints must use Interactivity Connectivity Establishment (ICE) protocol RFC5245 and protocol RFC8445 to negotiate the media route with Alexa endpoints.
- Your endpoints must use audio and video codecs that are supported by Alexa devices. The following table lists Alexa supported codecs.
Codecs type | Codecs | Relevant standard |
---|---|---|
Audio |
Note: The stereo parameter is treated as if stereo=0.
| |
Audio |
G.711 | |
Audio |
G.722 | |
Video |
H.264 constrained baseline | |
Video |
VP 8 |
Steps to onboard and build a WebRTC-based skill
To onboard and build a skill that supports skill-based calling, complete the following steps:
- Create a security profile
- 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 endpoints on your network with the service provider
Step 1: Create a security profile
To implement WebRTC calling, you must have a security profile with Login with Amazon (LWA). To create a security profile, complete the following steps.
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 in Step 2. -
To use LWA with a website, take the following additional steps in the Login with Amazon console:
- To the right of your security profile name, under Manage, click the gear icon.
- Click the Web Settings tab.
- At the bottom, click Edit.
- Under Allowed Return URLs, register a callback URL.
- Click Save.
Tip: If you don't have a return URL and you plan to use a REST client to interact with the API, enterhttps://example.com/login
.
Step 2: Get an access token
You must have an LWA access token to perform any API operation.
For details, see Integrate with LWA to get an API access token. The LWA scope to use is amazon_communication::service_provider
. Contact your ASP Solution Architect to get access to the LWA scope.
Step 3: Create a service provider
To onboard yourself as a service provider, use the Self Service Onboarding REST API.
The following example shows a POST
request for creating a service provider. Replace the {access token} with your own from Step 2. Replace the serviceProviderLogicalId
and displayName.value
to your own. For detailed explanations, see Create a service provider.
Step 4: Build a skill that implements WebRTC-based calling
To build the skill, complete the following sub-steps:
- Step 4.1 Create a custom skill
- Step 4.2 Implement account linking
- Step 4.3 Write your code to implement the Calling APIs
- Step 4.4 Certify and publish your skill
- Step 4.5 Onboard your skill
Step 4.1: Create a custom skill
You must use a custom skill to implement the skill-based calling feature.
To create a custom skill
-
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 panel, click TOOLS, choose Permissions, and then enable Communication-Calling.
Step 4.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 is 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 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 4.3: Write your code to implement the Calling APIs
To enable calls between Alexa endpoints and your endpoints, you must 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 endpoints
You must implement the following Alexa.Comms.CallingSignaling
Service Provider Interfaces (SPIs) in your Alexa skill for establishing call connections from Alexa to your endpoints. 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.
- InitiateOutboundCall
- CallInProgress
- CallInProgressAck
- CallRinging
- CallRingingAck
- CallAccepted
- CallUpdate
- CallUpdateAck
- CallUpdateResponse
- CallAcceptedAck
- CallEnded
For detailed explanations about the Alexa.Comms.CallSignaling
SPI, see Alexa.Comms.CallSignaling
Service Provider Interface.
Write code for processing calls from your endpoints to Alexa
When a customer initiates a call from an endpoint 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.
- CallRinging
- CallInProgress
- CallAccepted
- CallEnded
- InitiateInboundCall
- CallRingingAck
- CallInProgressAck
- CallUpdate
- CallUpdateResponse
- CallUpdateAck
- CallAcceptedAck
For request formats, sample requests, and responses, see Requests Exposed by Alexa.Comms.CallSignaling
Interface.
Step 4.4: Certify and publish your skill
After you're satisified with the quality of your skill, you can submit it for certification. For more details, see Submit your skill for certification.
Step 4.5: Onboard your skill
After your skill is certified and published, work with your ASP Solution Architect to onboard this skill with ASP to allow calling in ASP endpoints.
Step 5: Map your skill with your service provider
After you onboard yourself as a service provider in Step 3 and create a WebRTC-based skill in Step 4, use the Service Provider Network Mapping API to associate your skill ID with your service provider ID.
To locate your skill ID, sign in to your Alexa developer console, and then click the skill name. From the left panel, click Endpoint. You can now copy your Skill ID to the clipboard.
The following example shows a POST
request for creating the network mapping. Replace the {access token} with your own from Step 2. Replace the skillId amzn1.ask.skill.49d658da-cee8-4634-b64a-5a4d03c01755
and serviceProviderID amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501
with your own. For detailed explanations about the Service Provider Network Mapping API, see Create network mapping.
Step 6: Enable the WebRTC subscription skill on unit
You must enable the WebRTC add-on subscription skill on each unit where you want to create network mapping.
You can enable the WebRTC subscription skill by using the Skill Management API.
You can also enable the WebRTC subscription skill on the ASP console. Navigate to the Rooms page. Click Hidden Skills, search for the WebRTC subscription skill ID, and then click Enable.
The skill ID for the WebRTC subscription skill is amzn1.ask.skill.4f802665-333c-48e7-ada2-b218033d4015
.
Step 7: Associate endpoints on your network with your service provider
Now use the Account Association API to associate endpoints on your ASP with your service provider ID from Step 3.
The following example shows a POST
request for associating endpoints on your network with your service provider ID. Replace the {access token} with your own from Step 2. Replace the serviceProviderID amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501
with your own from Step 3. Replace the externalUserId
and amazonId
with your own. For detailed explanations, see Create account association.
Test WebRTC calling
After you complete all the steps, test calling from an Alexa device to an endpoint on your network or from an endpoint on your network to an Alexa device.
Related topics
Last updated: Mar 06, 2024