Understanding telephony events
The Audio Service invokes your AWS AWS Lambda function when certain events occur during a call. The following example shows the events, and text after the example explains each event.
{ "SchemaVersion": "1.0", "Sequence": 3, "InvocationEventType": "
event-type
", "CallDetails": { "TransactionId": "transaction-id-1
", "AwsAccountId": "aws-acct-id-1
", "AwsRegion": "us-east-1
", "SipMediaApplicationId": "sip-media-app-id-1
", "Participants": [ { "CallId": "call-id-1
", "ParticipantTag": "LEG-A", "To": "e164PhoneNumber
", "From": "e164PhoneNumber
", "Direction": "Inbound/Outbound
", "StartTimeInMilliseconds": "1641998241509
", "Status": "Connected/Disconnected
" } ] } }
- SchemaVersion
The version of schema used to create this event object.
- Sequence
The sequence of events that invoke your AWS Lambda function. Each time your function is invoked during a call, the sequence is incremented.
- InvocationEventType
The type of event that triggers an AWS Lambda invocation. For more information, see Event types later in this topic.
- CallDetails
Information about the call associated with the AWS Lambda invocation.
- TransactionId
The ID of a call associated with an AWS Lambda invocation.
- AwsAccountId
The AWS account ID associated with the SIP media application that resulted in the call routing.
- SipMediaApplicationId
The ID of the SIP media application associated with the call.
- Participants
Information about the participants on the call that invokes an AWS AWS Lambda function.
- CallId
A unique ID assigned to each participant.
- ParticipantTag
Each call participant gets a tag,
LEG-A
orLEG-B
.- To
The participant "to" phone number, in E.164 format.
- From
The participant “from” phone number, in E.164 format.
- Direction
The direction that a call leg comes from.
Inbound
represents a call made to the Audio Service.Outbound
represents a call made from the Audio Service.- StartTimeInMilliseconds
The epoch time in milliseconds, starting when a participant joins a call.
- Status
Whether a participant is
Connected
orDisconnected
Event types
The Audio Service invokes the Lambda function with these event types:
- NEW_INBOUND_CALL
A new call has been initiated by a phone number associated with your SIP media application.
- NEW_OUTBOUND_CALL
A new outbound call has been made via the CreateSipMediaApplicationCall API.
- ACTION_SUCCESSFUL
An action returned from your AWS Lambda function has succeeded. Successful actions include
ActionData
that matches the successful action."ActionData": { // The previous successful action },
- ACTION_FAILED
-
An action returned from your AWS Lambda function did not succeed. Unsuccessful actions include
ActionData
that matches the failed action, an error type, and an error message that describes the failure:"ActionData": { // The previous unsuccessful action "ErrorType": "
error-type
", "ErrorMessage": "error message
" }, - ACTION_INTERRUPTED
-
An action in the process of running was interrupted by an UpdateSipMediaApplicationCall API invocation. The
ActionData
includes the interrupted actions:"ActionData": { // The action that was interrupted },
- HANGUP
-
A user or the application hung up a call leg. The
ActionData
includes these details about the event:"ActionData": { "Type": "Hangup", "Parameters": { "SipResponseCode":
486
, "CallId": "c70f341a-adde-4406-9dea-1e01d34d033d
", "ParticipantTag": "LEG-A" } },- Type
Hangup.
- Parameters
The information about the
HANGUP
event:SipResponseCode – The response code associated with the event. The most common codes are:
0 – Normal clearing
480 – No answer
486 – User busy
CallId The ID of the participant that hung up.
ParticipantTag The tag of the participant that hung up.
- CALL_ANSWERED
The Audio Service answered an incoming call was answered. This event is returned on a dial-out call unless the call is bridged.
- INVALID_LAMBDA_RESPONSE
The response provided to the last AWS Lambda invocation caused a problem. The
ActionData
includes these additional fields:"ErrorType": "
error-type-1
", "ErrorMessage": "error-msg-1
"- DIGITS_RECEIVED
The application received DTMF digits after completion of a
ReceiveDigits
action. TheActionData
includes the received digits."ActionData": { "ReceivedDigits":
###
// The ReceiveDigits action data },- CALL_UPDATE_REQUESTED
-
The UpdateSipMediaApplicationCall API was invoked. The
ActionData
includes information about the update request:"ActionData": { "Type": "CallUpdateRequest", "Parameters": { "Arguments": { "leg": "LEG-A" } } }, }
- RINGING
A call leg is ringing