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.

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

  1. 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.
  2. The Alexa service sends the CallRinging payload to your Alexa skill when the Alexa endpoint starts ringing.
  3. Your Alexa skill forwards the CallRinging payload to your cloud.
  4. Your cloud sends CallRingingAck to Alexa to acknowledge the CallRinging event.
  5. The Alexa service sends the CallInProgress payload to your Alexa skill to send an SDP answer before the call gets accepted.
  6. Your skill forwards the CallInProgress payload to your cloud.
  7. Your cloud sends CallInProgressAck to Alexa to acknowledge the CallInProgress event.
  8. The Alexa service sends the CallAccepted payload to your Alexa skill when the callee accepts the call.
  9. Your skill forwards the CallAccepted payload to your cloud.
  10. Your cloud sends CallAcceptedAck to Alexa to acknowledge the CallAccepted event.
  11. 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 the CallEnded event to your skill.
  12. 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.

Diagram to illustrate SDP renegotiation from your cloud

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

CallRinging

Request

Your skill sends this request to the Alexa service when an outbound call from Alexa starts ringing on your endpoints.

CallInProgress

Request

Your skill sends this request to the Alexa service when one of your endpoints provisionally accepts an outbound call from Alexa.

CallAccepted

Request

Your skill sends this request to the Alexa service when one of your endpoints accepts an outbound call from Alexa.

CallEnded

Request

Your skill sends this request to the Alexa service when the call ends on your endpoint.

InitiateInboundCall

Request

Your skill sends this request to the Alexa service when an inbound call is activated.

CallRingingAck

Request

Your skill sends this request to the Alexa service in response to the CallRinging request from Alexa for an inbound call.

CallInProgressAck

Request

Your skill sends this request to the Alexa service in response to the CallInProgress request from Alexa for an inbound call.

CallUpdate

Request

Your skill sends this request to the Alexa service when your skill wants to initiate the reoffer for SDP renegotiation.

CallUpdateResponse

Request

Your skill sends this request to the Alexa service to provide an answer for the CallUpdate request.

CallUpdateAck

Request

Your skill sends this request to the Alexa service in response to the CallUpdateResponse request.

CallAcceptedAck

Request

Your skill sends this request to the Alexa service in response to the CallAccepted request.

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

Type of the request. For CallRinging, set it 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

sessionId

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

Type of the request. For CallInProgress, set it 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 details.

Object

Yes

sdpDetails.type

Type of SDP. Here the possible type to use is: ANSWER.

String

Yes

sdpDetails.value

Value of SDP details.

String

Yes

Response parameters

Property Description Type Required

sessionId

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

Type of the request. For CallAccepted, set it 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 details.

Object

Yes

sdpDetails.type

Type of SDP. Here the possible type to use is ANSWER. If the SDP ANSWER was sent in CallInProgress, this property is optional.

String

No

sdpDetails.value

Value of SDP details. If the SDP ANSWER was sent in CallInProgress, this property is optional.

String

No

Response parameters

Property Description Type Required

sessionId

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

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

String

Yes

sessionId

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

String

Yes

callResult

Call result details.

Object

Yes

callResult.code

Status of the call result. Possible values are: INTERNAL_ERROR, UNAUTHORISED, DEVICE_BUSY, SESSION_TIMEOUT, SUCCESS.

String

Yes

callResult.message

Detailed description why the call has ended.

String

No

Response parameters

Property Description Type Required

sessionId

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

Type of the request. For InitiateInboundCall, set it to Alexa.Comms.CallSignaling.InitiateInboundCall.

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: COMMUNICATION_PROFILE_ID, PHONE_NUMBER, RAW_ADDRESS. RAW_ADDRESS means the address is used as is.

Enum

Yes

participants[].id.value

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

participants[].isOriginator

Whether participant is the originator of the call. If not set, the default is false. when set to true, the participant is the caller.

Boolean

Yes

sdpDetails

SDP message details.

Object

Yes

sdpDetails.type

SDP message types. Here the possible value is OFFER.

String

Yes

sdpDetails.value

SDP content offer details.

String

Yes

customParams

Custom parameter details.

Object

No

customParams.callerName

Caller name. Possible values are: Scam Likely, Nuisance Likely, Telemarketing, Political Call, Survey Call, Charity Call, and Informational.

String

Yes

Response parameters

Property Description Type Required

sessionId

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

Type of the request. For CallRingingAck, set it 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

sessionId

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

Type of the request. For CallInProgressAck, set it 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

sessionId

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.

Request parameters

Property Description Type Required

type

Type of the request. For CallUpdate, set it 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 details.

Object

Yes

sdpDetails.type

Type of SDP. Here the possible type to use is: OFFER.

String

Yes

sdpDetails.value

Value of SDP details.

String

Yes

Response parameters

Property Description Type Required

sessionId

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

Type of the request. For CallUpdateResponse, set it 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. The acceptable values are CALL_HOLD, CALL_RESUME, CALL_UPDATE.

String

Yes

sdpDetails

SDP details.

Object

Yes

sdpDetails.type

Type of SDP. Here the possible type is: ANSWER.

String

Yes

sdpDetails.value

Value of SDP details.

String

Yes

Response parameters

Property Description Type Required

sessionId

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

Type of the request. For CallUpdateAck, set it 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

sessionId

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

Type of the request. For CallAcceptedAck, set it 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

sessionId

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

String

Yes

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