Requests Exposed by Alexa.Comms.CallSignaling Interface
You use the Alexa.Comms.CallSignaling
interface to establish call connections from your endpoints to Alexa. Amazon exposes call signaling application programming interfaces (APIs) so your skill can send signaling information as a request to Alexa and Alexa can respond to these signaling events.
Overview
When a customer makes a call from an endpoint on your network to an Alexa device, your skill should send signaling information as a request to Alexa. The Alexa service sends a response to your skill. Alexa and your cloud should authenticate the request with Login with Amazon (LWA) token as part of the request.
Typical workflow
The following diagram shows a typical workflow for a call initiated from an endpoint on your network to Alexa.
- When a customer initiates a call from an endpoint on your network to Alexa, your cloud sends the
InitiateInboundCall
payload by sending the request to Alexa. This request contains caller, callee, and Session Description Protocol (SDP) offer details. - The Alexa service sends the
CallRinging
payload to your Alexa skill when the Alexa endpoint starts ringing. - Your Alexa skill forwards the
CallRinging
payload to your cloud. - Your cloud sends
CallRingingAck
to Alexa to acknowledge theCallRinging
event. - The Alexa service sends the
CallInProgress
payload to your Alexa skill to send an SDP answer before the call gets accepted. - Your skill forwards the
CallInProgress
payload to your cloud. - Your cloud sends
CallInProgressAck
to Alexa to acknowledge theCallInProgress
event. - The Alexa service sends the
CallAccepted
payload to your Alexa skill when the callee accepts the call. - Your skill forwards the
CallAccepted
payload to your cloud. - Your cloud sends
CallAcceptedAck
to Alexa to acknowledge theCallAccepted
event. - If the caller wants to end the call, your cloud sends the
CallEnded
request to your skill. Similarly, if the callee wants to end the call, the Alexa service sends theCallEnded
event to your skill. - Your skill forwards the
CallEnded
event to your cloud to end the call.
SDP renegotiation workflow
When a caller establishes a call and the call is ongoing and call signaling happens again, SDP renegotiation starts. For example, SDP renegotiation starts when the caller or callee places an ongoing call on hold and later the call resumes, or when there is a Wi-Fi disconnection and reconnection during a call. The following diagram shows the renegotiation sequence of steps.
- Your cloud sends the
CallUpdate
request that contains the reoffer to The Alexa service. - The Alexa service sends the
CallUpdateResponse
event that contains the SDP answer for the reoffer to your Alexa skill. - Your skill forwards the
CallUpdateResponse
event to your cloud. - Your cloud sends the
CallUpdateAck
request to the Alexa service to acknowledge theCallUpdateResponse
event.
Requests and responses
When a customer makes a call from your endpoint, your skill sends the request to Alexa and listens to responses coming from Alexa.
All requests include the version, context, session, and request object at the top level.
All responses include the version, and response object.
For details about the version, context, session, request object, and response object, see Request and Response JSON Reference.
The CallSignaling REST API path is https://api.amazonalexa.com/v1/communications/signaling
.
To send signaling information, make a POST
request to v1/communications/signaling
. You need a Login with Amazon (LWA) token to use this REST API. In this case, your role is resource owner, and someone else is the client. For details, see Get an access token when you're the resource owner, and someone else is the client. Here the LWA scope to use is amazon_communication::calling
.
Operation | Type | Description |
---|---|---|
Request |
Your skill sends this request to the Alexa service when an outbound call from Alexa starts ringing on your endpoints. | |
Request |
Your skill sends this request to the Alexa service when one of your endpoints provisionally accepts an outbound call from Alexa. | |
Request |
Your skill sends this request to the Alexa service when one of your endpoints accepts an outbound call from Alexa. | |
Request |
Your skill sends this request to the Alexa service when the call ends on your endpoint. | |
Request |
Your skill sends this request to the Alexa service when an inbound call is activated. | |
Request |
Your skill sends this request to the Alexa service in response to the | |
Request |
Your skill sends this request to the Alexa service in response to the | |
Request |
Your skill sends this request to the Alexa service when your skill wants to initiate the reoffer for SDP renegotiation. | |
Request |
Your skill sends this request to the Alexa service to provide an answer for the | |
Request |
Your skill sends this request to the Alexa service in response to the | |
Request |
Your skill sends this request to the Alexa service in response to the |
CallRinging
Your skill sends this request to the Alexa service when an outbound call from Alexa starts to ring on your endpoints.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallInProgress
Your skill sends this request to the Alexa service when an outbound call from Alexa is provisionally accepted by one of the endpoints on your cloud.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
|
SDP details. |
Object |
Yes |
|
Type of SDP. Here the possible type to use is: |
String |
Yes |
|
Value of SDP details. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallAccepted
Your skill sends this request to the Alexa service when an outbound call from Alexa is accepted by one of the endpoints on your cloud.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
|
SDP details. |
Object |
Yes |
|
Type of SDP. Here the possible type to use is |
String |
No |
|
Value of SDP details. If the SDP |
String |
No |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallEnded
Your skill sends this request to the Alexa service when the call ends on your endpoint.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
|
Call result details. |
Object |
Yes |
|
Status of the call result. Possible values are: |
String |
Yes |
|
Detailed description why the call has ended. |
String |
No |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
InitiateInboundCall
Your skill sends this request to the Alexa service when an inbound call is initiated from your endpoint.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
|
List of participants in the call. |
Array of objects |
Yes |
|
Participant identifier details. |
Object |
Yes |
|
Type of supported participant ID. Possible values: |
Enum |
Yes |
|
Participant identifier value. This value can be a phone number, raw address value, or communication profile ID. Raw address value is used as is. |
String |
Yes |
|
Whether participant is the originator of the call. If not set, the default is |
Boolean |
Yes |
|
SDP message details. |
Object |
Yes |
|
SDP message types. Here the possible value is |
String |
Yes |
|
SDP content offer details. |
String |
Yes |
|
Custom parameter details. |
Object |
No |
|
Caller name. Possible values are: |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallRingingAck
Your skill sends this request to the Alexa service in response to the CallRinging
event from Alexa.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallInProgressAck
Your skill sends this request to the Alexa service in response to the CallInProgress
request from Alexa.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallUpdate
Your skill sends this request to the Alexa service when you want to initiate the reoffer for SDP renegotiation.
sendrecv
and recvonly
. If you attempt to add new streams instead when you unmute, Alexa ignores the additional streams and continues to treat your stream as muted.Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
|
Type of renegotiation. The acceptable values are |
String |
Yes |
|
SDP details. |
Object |
Yes |
|
Type of SDP. Here the possible type to use is: |
String |
Yes |
|
Value of SDP details. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallUpdateResponse
Your skill sends this request to the Alexa service to provide the answer for the CallUpdate
request.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
|
Type of renegotiation. The acceptable values are |
String |
Yes |
|
SDP details. |
Object |
Yes |
|
Type of SDP. Here the possible type is: |
String |
Yes |
|
Value of SDP details. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallUpdateAck
Your skill sends this request to the Alexa service to acknowledge the CallUpdateResponse
, which contains the SDP answer for reoffer from your endpoint.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
CallAcceptedAck
Your skill sends this request to the Alexa service to acknowledge the CallAccepted
request.
Request parameters
Property | Description | Type | Required |
---|---|---|---|
|
Type of the request. For |
String |
Yes |
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Unique ID for each call. You can trace the call with this property. |
String |
Yes |
HTTP exception codes
Status code | Exception | Description |
---|---|---|
|
|
The call is not in progress or not in ringing state. |
|
|
The request is malformed, is missing any required parameters, or if query contains an invalid filter. |
|
|
The access token is missing, or expired. |
|
|
The user doesn't have permission to access the service or has the wrong Login With Amazon (LWA) authorization token in the request. |
|
|
The |
|
|
The request conflicts with another one being processed. |
|
|
The user has made more calls than the allowed limit. |
|
|
An internal service error caused the request failure. |
Related topics
Last updated: Nov 28, 2023