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

Opus Audio Codec

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

Steps to onboard and build a WebRTC-based skill

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

  1. Create a security profile
  2. Get an access token
  3. Create a service provider
  4. Build a skill that implements WebRTC-based calling
  5. Map your skill with the service provider
  6. Enable the WebRTC subscription skill on unit
  7. 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

  1. In the Login with Amazon console, sign in with your Amazon developer account, and then click Create a New Security Profile.

  2. Enter your Security Profile Name, Security Profile Description, and Consent Privacy Notice URL.
    For details about security profiles, see Security Profile.

  3. Click Save.
    After you save the security profile, Amazon issues a client ID and a client secret for your profile.

  4. Save your client ID and client secret in a secure place.
    You need these values in Step 2.

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

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

You must use a custom skill to implement the skill-based calling feature.

To create a custom skill

  1. Sign in to your Alexa Developer Console, and then choose to create a custom skill.

  2. Click Create Skill, type a name for the skill and choose a locale, and then click Next.

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

  4. On the Templates page, keep the default choice Start from Scratch, and click then Next.

  5. On the Review page, review your selections, and then click Create Skill.

  6. After your skill is created, make sure that you're on the Build tab.

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

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.

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.

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.

Was this page helpful?

Last updated: Mar 06, 2024