Session Status of Calls API

This method allows you to review the "Voice Session Summary" status and individual call legs.
"Voice Session Summary" (VSS) endpoint. Your "Voice Session Summary" (VSS) endpoint can be configured on the sub-account level with programmable voice Webhooks
This can be used alongside or instead of the Call Status, to simplify your monitoring.

☑️

Session ID

Please matach the session ID for the calls API with the session ID in the call summary

Request

When receiving final call statuses, the 8x8 platform will POST a JSON object to your URL.

The JSON object will contain the following values:

NameTypeDescription
namespaceString8x8's overall product namespace. For Voice products the value will be "VOICE"
eventTypeStringEvent type that generated this callback. For call status events the value will be "CALL_STATUS"
descriptionStringDescription of the event type that triggered the callback.
sessionIdStringUnique id that represents Number masking session [UUID]
subAccountIdStringUnique ID of account
sessionStatusString“sessionStatus” values of the two call legs. Possible values for “sessionStatus” are:
COMPLETED, NO ANSWER, BUSY, CANCELED, FAILED
startTimeStringStart time of call masking session
endTimeStringStart time of call masking session
lastActionStringShows the last executed command during the session (MakeCall, PlayTTS or PlayFile)
callCountIntegerShows how many call legs have been bridged for the given session
detailsObjectJSON object containing information about all call legs in the session
callIdStringUnique identifier of call leg
callDirectionStringIndicates the direction of the call leg (INBOUND or OUTBOUND)
callTypeStringType of the call leg. Values can be "PSTN" or "VOIP", depending on where the call was initiated from (telco operators or VoiceSDK users). For NumberMasking the value will always be PSTN.
initiatedTimestampStringInitiated time of call leg
connectedTimestampStringTime when the call leg is connected
disconnectedTimestampStringTime when the call leg is disconnected
sourceStringSource number (CallerID) set for the call leg
sourceFormatStringThe value for Number Masking will always be "MSISDN"
destinationStringDestination number set for the call leg
destinationFormatStringThe value for Number Masking will always be "MSISDN"
sourceCountryCodeStringCountry code for the Source Number
destinationCountryCodeStringCountry code for the Destination Number
sourceRefIdStringFor INBOUND call legs this property shows the referenceId of the Virtual Number that has been called. For OUTBOUND calls the value is null
destinationRefIdStringFor OUTBOUND call legs this property shows the referenceId of the Virtual Number that is used as callerId. For INBOUND calls the value is null
callStatusStringCall status of the call leg. The values can be:
COMPLETED, NO ANSWER, BUSY, CANCELED, FAILED
callDurationIntegerCall duration of the call leg.
errorDetailsObjectJSON object containing information about all call leg errors in the session
errorMsgStringThe error details of the call leg
errorCodeStringError code specified in the Error object
callQualityObjectJSON object containing information about all call leg call quality indicators in the session
mosStringMean Opinion Score (MOS) is a numerical measure of the human-judged overall quality of the call leg
packetlossRateIntegerPacket loss rate reflects the reliable of a communication network path.
jitterIntegerJitter reflects any time delay in sending data packets over your call connection.

Example of a JSON object sent to your "Voice Session Summary" endpoint:

Success 

{
  "payload": {
    "sessionId": "1f048a84-ea6d-11ee-911b-078f7290bf52",
    "subAccountId": "8x8_test",
    "sessionStatus": "COMPLETED",
    "startTime": "2024-03-25T06:01:30Z",
    "endTime": "2024-03-25T06:01:50Z",
    "lastAction": "MAKE_CALL",
    "callCount": 2,
    "details": {
      "CallB": {
        "callId": "1fbdef11-ea6d-11ee-9e30-e53b76c602ef",
        "callDirection": "OUTBOUND",
        "callType": "PSTN",
        "initiatedTimestamp": "2024-03-25T06:01:30Z",
        "connectedTimestamp": "2024-03-25T06:01:37Z",
        "disconnectedTimestamp": "2024-03-25T06:01:50Z",
        "source": "+6568332048",
        "destination": "+6591178965",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "SG",
        "destinationCountryCode": "SG",
        "sourceRefId": "PSTN1",
        "callStatus": "COMPLETED",
        "callDuration": 13,
        "callQuality": {
          "mos": 4.5,
          "packetLossRate": 0,
          "jitter": 19
        }
      },
      "CallA": {
        "callId": "1f048a83-ea6d-11ee-911b-e9023a97c284",
        "callDirection": "INBOUND",
        "callType": "PSTN",
        "initiatedTimestamp": "2024-03-25T06:01:28Z",
        "connectedTimestamp": "2024-03-25T06:01:37Z",
        "disconnectedTimestamp": "2024-03-25T06:01:50Z",
        "source": "+12314377870",
        "destination": "+6568332048",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "US",
        "destinationCountryCode": "SG",
        "destinationRefId": "PSTN1",
        "callStatus": "COMPLETED",
        "callDuration": 13,
        "callQuality": {
          "mos": 4.5,
          "packetLossRate": 0,
          "jitter": 20
        }
      }
    }
  },
  "namespace": "VOICE",
  "eventType": "SESSION_SUMMARY",
  "description": "Summary of a completed call session"
}
Failure
{
  "payload": {
    "sessionId": "47f19e66-2163-11ee-8ccd-27b543a164ea",
    "subAccountId": "wavecell_voice",
    "sessionStatus": "ERROR",
    "startTime": "2023-07-13T09:54:38Z",
    "endTime": "2023-07-13T09:54:38Z",
    "lastAction": "PLAY_TTS",
    "callCount": 1,
    "errorDetails": {
      "errorMsg": "No coverage available for requested area",
      "errorCode": -2005
    },
    "details": {
      "CallA": {
        "callId": "4809bb03-2163-11ee-8f06-8da8b5ddeca4",
        "callDirection": "OUTBOUND",
        "callType": "PSTN",
        "initiatedTimestamp": "2023-07-13T09:54:38Z",
        "disconnectedTimestamp": "2023-07-13T09:54:38Z",
        "source": "+6568332048",
        "destination": "+6591178965",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "SG",
        "destinationCountryCode": "SG",
        "sourceRefId": "PSTN1",
        "callStatus": "ERROR",
        "callDuration": 0
      }
    }
  },
  "namespace": "VOICE",
  "eventType": "SESSION_SUMMARY",
  "description": "Summary of a completed call session"
}
 

Session statuses

Here is the list of all possible session statuses:

CallA StatusCallB StatusStatusComment
COMPLETEDCOMPLETEDCOMPLETEDSuccessfully established call between two call parties
COMPLETEDNO ANSWERNO ANSWERThe called party did not answer the call
COMPLETEDBUSYBUSYThe called party’s phone was busy
COMPLETEDFAILEDFAILEDThe outbound call towards the called party’s phone number failed. Possible reasons include the number is switched off or not reachable, invalid phone number, connection error, etc.
CANCELEDCANCELEDCANCELEDThe calling party disconnected the call before a “Status” for the outbound call leg was received. This can occur if a user disconnects before ringing is completed or as soon as the caller hears an operator tone suggesting the phone number is invalid / switched off.
COMPLETEDNULLCOMPLETEDIt indicates that the call flow did not have an outbound call leg. This can happen when the called phone number has been answered by a TTS prompt.
ERRORNULLERRORIt indicates that the inbound leg had an error while processing the call. This can happen when the Voice Call Action webhook fails or when there is no call coverage to the target country. Additional error details are provided when this happens.
COMPLETEDERRORERRORIt indicates that the outbound leg had an error while processing the call. Additional error details are provided when this happens.

Response

Your endpoint should respond with 200 OK status


Status Code and Status Message

Status CodeMessage
1Created
-1001Invalid JSON request body
-1002Speech profile or language parameter invalid
-1003Valid maxDigits required when minDigits provided
-1005Valid overallTimeout is required when digitTimeout provided
-1007$.callflow[0].action should be one of: [Call action names]
Eg: $.callflow[0].action should be one of: say,playFile,sayAndCapture
-1008Valid maxDigits is required when completeOnHash is false
-1009Invalid call flow entry provided. [Additional error details here].
Eg: Invalid call flow entry provided. $.callflow[0].params.text: is missing but it is required
-2005No coverage available for requested area
-9999An unknown error has occurred.