Skip to main content
GuidesAPI ReferenceSupport

Session Summary (Voice Messaging)

This webhook provides a comprehensive summary of a Voice Messaging session after it ends. The Voice Session Summary (VSS) is sent to your configured webhook endpoint and includes details about all call legs in the session, call quality metrics, and session outcomes.

Your VSS endpoint can be configured at the sub-account level using the Voice Webhooks API.

When a voice session ends, the 8x8 platform will POST a JSON object to your VSS endpoint.

Webhook Payload​

Root Level Fields​

NameTypeDescription
namespaceString8x8's overall product namespace. For Voice products, the value is VOICE
eventTypeStringEvent type that generated this callback. For session summary events, the value is SESSION_SUMMARY
descriptionStringDescription of the event type that triggered the callback
payloadObjectContains the session summary details

Payload Fields​

NameTypeDescription
sessionIdStringUnique identifier representing the Voice Messaging session [UUID]
subAccountIdStringUnique ID of the 8x8 SubAccount
sessionStatusStringFinal status of the session. Possible values:
COMPLETED
NO_ANSWER
BUSY
CANCELED
FAILED
ERROR

For Opt Out Scenario:
- COMPLETED_UNSUBSCRIBED (user opt out)
- COMPLETED_UNSUB_ERROR (error encountered during blacklist process)
- UNSUBSCRIBED_CONTACT (user is already in the blacklist group)
startTimeStringStart time of the Voice Messaging session (ISO 8601 format)
endTimeStringEnd time of the Voice Messaging session (ISO 8601 format)
lastActionStringThe last callflow action executed during the session (e.g., MAKE_CALL, SAY, PLAY_FILE)
callCountIntegerNumber of call legs bridged in the session
errorDetailsObject(Optional) Contains error information when sessionStatus is ERROR. Includes errorMsg (String) and errorCode (Integer)
detailsObjectContains information about individual call legs in the session

Call Leg Fields (callA, callB, etc.)​

Each call leg in the details object contains:

NameTypeDescription
callIdStringUnique identifier of the call leg [UUID]
callDirectionStringDirection of the call leg. Values: INBOUND or OUTBOUND
callTypeStringType of the call leg. For Voice Messaging, the value is always PSTN
initiatedTimestampStringWhen the call leg was initiated (ISO 8601 format)
connectedTimestampString(Optional) When the call leg was connected/answered (ISO 8601 format)
disconnectedTimestampStringWhen the call leg was disconnected (ISO 8601 format)
sourceStringSource number of the call leg
destinationStringDestination number of the call leg
sourceFormatStringFormat of the source number. For Voice Messaging, the value is always MSISDN
destinationFormatStringFormat of the destination number. For Voice Messaging, the value is always MSISDN
sourceCountryCodeStringCountry code of the source number (ISO 3166-1 alpha-2 format, e.g., "US", "SG")
destinationCountryCodeStringCountry code of the destination number (ISO 3166-1 alpha-2 format, e.g., "SG", "US")
sourceRefIdStringFor OUTBOUND calls, the reference ID of the virtual number used as caller ID. For INBOUND calls, the value is null
callStatusStringFinal status of the call leg. Possible values:
COMPLETED
NO_ANSWER
BUSY
CANCELED
FAILED
ERROR
callDurationIntegerDuration of the connected call in seconds
callQualityObject(Optional) Call quality metrics for this leg

Call Quality Metrics​

When available, each call leg may include quality metrics:

NameTypeDescription
mosNumberMean Opinion Score (MOS) - a measure of call quality ranging from 1.0 (poor) to 5.0 (excellent)
packetLossRateNumberPacket loss rate as a decimal (e.g., 0.01 = 1% packet loss)
jitterIntegerJitter in milliseconds - variation in packet arrival times

Example Payloads​

Session Summary (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": 1,
    "details": {
      "CallA": {
        "callId": "1f048a83-ea6d-11ee-911b-e9023a97c284",
        "callDirection": "OUTBOUND",
        "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",
        "SourceRefId": "null",
        "callStatus": "COMPLETED",
        "callDuration": 13,
        "callQuality": {
          "mos": 4.5,
          "packetLossRate": 0,
          "jitter": 20
        }
      }
    }
  },
  "namespace": "VOICE",
  "eventType": "SESSION_SUMMARY",
  "description": "Summary of a completed call session"
}

Session Summary (Failure)​

{
  "payload": {
    "sessionId": "47f19e66-2163-11ee-8ccd-27b543a164ea",
    "subAccountId": "8x8_test",
    "sessionStatus": "ERROR",
    "startTime": "2024-07-13T09:54:38Z",
    "endTime": "2024-07-13T09:54:38Z",
    "lastAction": "MAKE_CALL",
    "callCount": 1,
    "errorDetails": {
      "errorMsg": "No coverage available for requested area",
      "errorCode": -2004
    },
    "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"
}

Response​

Your endpoint should respond with an HTTP 200 OK status to acknowledge receipt of the webhook.

Understanding Call Quality Metrics​

The callQuality object provides real-time network quality metrics for each call leg:

  • MOS (Mean Opinion Score):

    • 4.3-5.0: Excellent
    • 4.0-4.3: Good
    • 3.6-4.0: Fair
    • 3.1-3.6: Poor
    • 1.0-3.1: Bad

  • Packet Loss Rate: Lower is better. Values above 1-2% may affect call quality.

  • Jitter: Lower is better. Values above 30ms may cause noticeable audio issues.

Error Details and Error Codes​

These error codes may appear in the errorDetails object when sessionStatus is "ERROR". For complete error code documentation, see Voice Error Codes.

Error CodeMessage
-2001An internal error has occurred
-2002An internal connectivity error has occurred
-2003The call flow provided is invalid
-2004No coverage available for requested area
-2005Unable to synthesize text to speech
-2006Unable to download file for playback
-2007The validity period of the call flow request has expired
-2008The provided source MSISDN or caller ID is not whitelisted
-2009The scenario parameters provided is invalid
-2010The trunk capacity has been exceeded
-9999An unknown error has occurred

Support Channels​