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.

Diagram to illustrate a call initiated from an Alexa endpoint to your endpoint

  1. 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 contains sessionId, Session Description Protocol (SDP) offer, caller, and callee details.
  2. Your Alexa skill forwards InitiateOutboundCall to your cloud.
  3. Your endpoint on your cloud sends the CallRinging request to Alexa, which contains sessionId from the InitiateOutboundCall. Your developer application starts ringing on the callee side.
  4. The Alexa service sends the CallRingingAck event to your skill to acknowledge the CallRinging request that's received from your cloud.
  5. Your skill forwards the CallRingingAck event to the endpoint on your cloud.
  6. Your cloud sends CallInProgress to the Alexa service.
  7. The Alexa service sends CallInProgressAck to your skill to acknowledge the CallInProgress request.
  8. Your skill forwards the CallInProgressAck event to your cloud.
  9. Your cloud sends the CallAccepted request to Alexa when the callee accepts the call.
  10. The Alexa service sends the CallAcceptedAck event to your skill to acknowledge the CallAccepted request.
  11. Your skill forwards the CallAcceptedAck event to your cloud. After this event, the call begins between your endpoint and Alexa.
  12. 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 the CallEnded request to your skill.
  13. 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.

Diagram to illustrate SDP renegotiation from your cloud

  1. The Alexa service sends the CallUpdate request that contains the reoffer to your Alexa skill.
  2. Your skill forwards CallUpdate with the reoffer to your cloud.
  3. Your cloud sends the CallUpdateResponse request that contains SDP answer for the reoffer to Alexa.
  4. The Alexa service sends CallUpdateAck to your Alexa skill to acknowledge the CallUpdateResponse.
  5. 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

InitiateOutboundCall

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.

CallRingingAck

Signaling SPI

The Alexa service sends this payload to your skill in response to the CallRinging request from your skill for an outbound call from an Alexa device.

CallInProgressAck

Signaling SPI

The Alexa service sends this payload to your skill in response to the CallInProgress request from your cloud for an outbound call from an Alexa device.

CallEnded

Signaling SPI

The Alexa service sends this payload to your skill when the Alexa user ends the call.

CallRinging

Signaling SPI

The Alexa service sends this payload to your skill when an inbound call from your cloud starts ringing on an Alexa device.

CallInProgress

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.

CallAccepted

Signaling SPI

The Alexa service sends this payload to the skill when one of the Alexa endpoints accepts an inbound call from your endpoint.

CallUpdate

Signaling SPI

The Alexa service sends this reoffer payload to your skill when there is an SDP renegotiation from Alexa.

CallUpdateAck

Signaling SPI

The Alexa service sends this payload to your skill in response to the CallUpdateResponse request.

CallUpdateResponse

Signaling SPI

The Alexa service sends this payload to your skill. The payload contains the SDP Answer for the reoffer that was initiated from your endpoint.

CallAcceptedAck

Signaling SPI

The Alexa service sends this payload to your skill in response to CallAccepted.

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

Type of the request. For InitiateOutboundCall, set the type to Alexa.Comms.CallSignaling.InitiateOutboundCall.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

participants[]

List of participants in the call.

Array of objects

Yes

participants[].id

Participant identifier details.

Object

Yes

participants[].id.type

Type of supported participant ID. Possible values: PHONE_NUMBER, RAW_ADDRESS, COMMUNICATION_PROFILE_ID. RAW_ADDRESS means the address is used as is.

Enum

Yes

participants[].id.value

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

participants[].isOriginator

Whether participant is the originator of the call. Possible values: true, false. When set to true, the participant is the caller.

Boolean

Yes

sdpDetails

SDP message details.

Object

Yes

sdpDetails.type

SDP message type. Here the acceptable value is OFFER.

String

Yes

sdpDetails.value

SDP content offer or answer details.

String

Yes

Response parameters

Property Description Type Required

response

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

Type of the request. For CallRingingAck, set the type to Alexa.Comms.CallSignaling.CallRingingAck.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

Response parameters

Property Description Type Required

response

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

Type of the request. For CallInProgressAck, set the type to Alexa.Comms.CallSignaling.CallInProgressAck.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

Response parameters

Property Description Type Required

response

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

Type of the request. For CallEnded, set the type to Alexa.Comms.CallSignaling.CallEnded.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

callResult

Information about the call result.

Object

Yes

callResult.code

Reason code for the ended call. Possible values are: INTERNAL_ERROR, UNAUTHORIZED, DEVICE_BUSY, SESSION_TIMEOUT, SUCCESS, DEVICE_UNAVAILABLE.

String

Yes

callResult.message

Detailed description for the ended call.

String

No

Response parameters

Property Description Type Required

response

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

Type of the request. For CallRinging, set the type to Alexa.Comms.CallSignaling.CallRinging.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

Response parameters

Property Description Type Required

response

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

Type of the request. For CallInProgress, set the type to Alexa.Comms.CallSignaling.CallInProgress.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

sdpDetails

SDP message details.

Object

Yes

sdpDetails.type

SDP message type. Here the acceptable value is ANSWER.

String

Yes

sdpDetails.value

SDP content offer or answer details.

String

Yes

Response parameters

Property Description Type Required

response

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

Type of the request. For CallAccepted, set the type to Alexa.Comms.CallSignaling.CallAccepted.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

sdpDetails

SDP message details.

Object

Yes

sdpDetails.type

SDP message type. Here the acceptable value is ANSWER. If the SDP ANSWER was sent in CallInProgress, this property is optional.

String

No

sdpDetails.value

SDP content offer or answer details. If the SDP ANSWER was sent in CallInProgress, this property is optional.

String

No

Response parameters

Property Description Type Required

response

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

Type of the request. For CallUpdate, set the type to Alexa.Comms.CallSignaling.CallUpdate.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

renegotiationType

Type of renegotiation. The acceptable values are CALL_HOLD, CALL_RESUME, CALL_UPDATE.

String

Yes

sdpDetails

SDP message details.

Object

Yes

sdpDetails.type

SDP message type. Here the acceptable value is OFFER.

String

Yes

sdpDetails.value

SDP content offer or answer details.

String

Yes

Response parameters

Property Description Type Required

response

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

Type of the request. For CallUpdateAck, set the type to Alexa.Comms.CallSignaling.CallUpdateAck.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

Response parameters

Property Description Type Required

response

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

Type of the request. For CallUpdateResponse, set the type to Alexa.Comms.CallSignaling.CallUpdateResponse.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

renegotiationType

Type of renegotiation to indicate if the renegotiation is on hold, resumed, or a normal update. The possible values are: CALL_HOLD, CALL_RESUME, CALL_UPDATE.

String

Yes

sdpDetails

SDP message details.

Object

Yes

sdpDetails.type

SDP message type. Here the acceptable value is ANSWER.

String

Yes

sdpDetails.value

SDP content offer or answer details.

String

Yes

Response parameters

Property Description Type Required

response

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

Type of the request. For CallAcceptedAck, set the type to Alexa.Comms.CallSignaling.CallAcceptedAck.

String

Yes

sessionId

Unique ID for each call. You can trace the call with this property.

String

Yes

Response parameters

Property Description Type Required

response

Information about what to render to the user and whether to end the current session.

Object

No

HTTP exception codes

Status code Exception Description

400

InvalidCallStateException

The call is not in progress or not in ringing state.

400

InvalidInputException

The request is malformed, is missing any required parameters, or if query contains an invalid filter.

401

BadTokenException

The access token is missing, or expired.

403

AccessDeniedException

The user doesn't have permission to access the service or has the wrong Login With Amazon (LWA) authorization token in the request.

404

ResourceNotFoundException

The sessionId, participant, or device doesn't exist.

409

ResourceConflictException

The request conflicts with another one being processed.

429

ThrottlingException

The user has made more calls than the allowed limit.

500

InternalServerException

An internal service error caused the request failure.

Was this page helpful?

Last updated: Nov 28, 2023