Alexa.Comms.CallSignaling Service Provider Interface
The Alexa.Comms.CallSignaling
namespace defines a Service Provider Interface (SPI) for interactions between the Alexa service and endpoints on your network. You implement the Alexa.Comms.CallSignaling
SPI in your Alexa skill to establish call connections from Alexa to your endpoints.
Overview
When your customer uses Alexa to call an endpoint on your cloud, your skill should reply to the event with the appropriate response.
Typical workflow
The following diagram shows a typical workflow for a call initiated from Alexa to your endpoint.
- When a customer initiates a call from Alexa to your endpoint, the Alexa service sends the
InitiateOutboundCall
event to your skill and your skill should send a deferred response to Alexa. The event containssessionId
, Session Description Protocol (SDP) offer, caller, and callee details. - Your Alexa skill forwards
InitiateOutboundCall
to your cloud. - Your endpoint on your cloud sends the
CallRinging
request to Alexa, which containssessionId
from theInitiateOutboundCall
. Your developer application starts ringing on the callee side. - The Alexa service sends the
CallRingingAck
event to your skill to acknowledge theCallRinging
request that's received from your cloud. - Your skill forwards the
CallRingingAck
event to the endpoint on your cloud. - Your cloud sends
CallInProgress
to the Alexa service. - The Alexa service sends
CallInProgressAck
to your skill to acknowledge theCallInProgress
request. - Your skill forwards the
CallInProgressAck
event to your cloud. - Your cloud sends the
CallAccepted
request to Alexa when the callee accepts the call. - The Alexa service sends the
CallAcceptedAck
event to your skill to acknowledge theCallAccepted
request. - Your skill forwards the
CallAcceptedAck
event to your cloud. After this event, the call begins between your endpoint and Alexa. - If the caller wants to end the call, the Alexa service sends the
CallEnded
event to your Alexa skill. Similarly, if the callee wants to end the call, your cloud sends theCallEnded
request to your skill. - Your skill forwards the
CallEnded
request to your endpoint to end the call.
SDP renegotiation workflow
When the caller establishes a call and the call is ongoing and call signaling happens again, SDP renegotiation starts. For example, SDP renegotiation starts when a caller or callee puts 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.
- The Alexa service sends the
CallUpdate
request that contains the reoffer to your Alexa skill. - Your skill forwards
CallUpdate
with the reoffer to your cloud. - Your cloud sends the
CallUpdateResponse
request that contains SDP answer for the reoffer to Alexa. - The Alexa service sends
CallUpdateAck
to your Alexa skill to acknowledge theCallUpdateResponse
. - Your skill forwards
CallUpdateAck
to your cloud.
Requests and responses
Your Alexa skill must implement the Alexa.Comms.CallSignaling
SPI to establish call connection with Alexa. The Alexa service sends requests to your skill and listens to the responses coming from your Alexa skill.
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.
Operation | Type | Description |
---|---|---|
Signaling SPI |
The Alexa service sends this payload to your skill, and your skill sends a deferred response to Alexa when the user initiates an outbound call from an Alexa device. To send a deferred response, see Deferred response. | |
Signaling SPI |
The Alexa service sends this payload to your skill in response to the | |
Signaling SPI |
The Alexa service sends this payload to your skill in response to the | |
Signaling SPI |
The Alexa service sends this payload to your skill when the Alexa user ends the call. | |
Signaling SPI |
The Alexa service sends this payload to your skill when an inbound call from your cloud starts ringing on an Alexa device. | |
Signaling SPI |
The Alexa service sends this payload to your skill when an inbound call from your cloud starts ringing on an Alexa endpoint and Alexa wants to send early media to your skill. | |
Signaling SPI |
The Alexa service sends this payload to the skill when one of the Alexa endpoints accepts an inbound call from your endpoint. | |
Signaling SPI |
The Alexa service sends this reoffer payload to your skill when there is an SDP renegotiation from Alexa. | |
Signaling SPI |
The Alexa service sends this payload to your skill in response to the | |
Signaling SPI |
The Alexa service sends this payload to your skill. The payload contains the SDP | |
Signaling SPI |
The Alexa service sends this payload to your skill in response to |
InitiateOutboundCall
The Alexa service sends this payload request to your skill when the user initiates an outbound call from an Alexa device.
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. The 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. Possible values: |
Boolean |
Yes |
|
SDP message details. |
Object |
Yes |
|
SDP message type. Here the acceptable value is |
String |
Yes |
|
SDP content offer or answer details. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallRingingAck
The Alexa service sends this payload to your skill in response to the CallRinging
request from your cloud for an outbound call from an Alexa device.
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 |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallInProgressAck
The Alexa service sends this payload to the skill in response to the CallInProgress
request from your cloud for an outbound call from an Alexa device.
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 |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallEnded
The Alexa service sends this payload to the skill when the Alexa user ends the call.
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 |
|
Information about the call result. |
Object |
Yes |
|
Reason code for the ended call. Possible values are: |
String |
Yes |
|
Detailed description for the ended call. |
String |
No |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallRinging
The Alexa service sends this payload to the skill when an inbound call from your cloud starts ringing on Alexa 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 |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallInProgress
The Alexa service sends this payload to your skill when an inbound call request from your cloud starts ringing on an Alexa endpoint and Alexa wants to send early media to your endpoint. This is equivalent to the SIP 183 Session Progress response message.
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 message details. |
Object |
Yes |
|
SDP message type. Here the acceptable value is |
String |
Yes |
|
SDP content offer or answer details. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallAccepted
The Alexa service sends this payload to your skill when one of the Alexa endpoints accepts the call from 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 message details. |
Object |
Yes |
|
SDP message type. Here the acceptable value is |
String |
No |
|
SDP content offer or answer details. If the SDP |
String |
No |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallUpdate
The Alexa service sends this reoffer payload to your skill when there is SDP renegotiation 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 |
|
Type of renegotiation. The acceptable values are |
String |
Yes |
|
SDP message details. |
Object |
Yes |
|
SDP message type. Here the acceptable value is |
String |
Yes |
|
SDP content offer or answer details. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallUpdateAck
The Alexa service sends this payload to your skill in response to the CallUpdateResponse
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 |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallUpdateResponse
The Alexa service sends this payload to your skill containing Answer
from the device for the reoffer that was 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 |
|
Type of renegotiation to indicate if the renegotiation is on hold, resumed, or a normal update. The possible values are: |
String |
Yes |
|
SDP message details. |
Object |
Yes |
|
SDP message type. Here the acceptable value is |
String |
Yes |
|
SDP content offer or answer details. |
String |
Yes |
Response parameters
Property | Description | Type | Required |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
CallAcceptedAck
The Alexa service sends this payload to the skill in response to CallAccepted
.
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 |
---|---|---|---|
|
Information about what to render to the user and whether to end the current session. |
Object |
No |
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