Skip to main content
GuidesAPI ReferenceSupport

Session Summary (IVR)

This webhook provides a comprehensive summary of an IVR 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
versionIntegerIndicates the schema version of this webhook payload
payloadObjectContains the session summary details

Payload Fields​

NameTypeDescription
sessionIdStringUnique identifier representing the IVR session [UUID]
subAccountIdStringUnique ID of the 8x8 SubAccount
sessionStatusStringFinal status of the session. Possible values:
COMPLETED
BUSY
NO_ANSWER
FAILED
CANCELED
ERROR
startTimeStringStart time of the IVR session (ISO 8601 format)
endTimeStringEnd time of the IVR session (ISO 8601 format)
lastActionStringThe last callflow action executed during the session (e.g., MAKE_CALL, HANGUP, SAY_AND_CAPTURE)
callCountIntegerNumber of call legs bridged in the session
clientRequestIdString(Optional) A user-supplied identifier for this request. Echoed back in the webhook to allow correlation with the original request
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. Values: PSTN or VOIP
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. Value: MSISDN
destinationFormatStringFormat of the destination number. Value: MSISDN
sourceCountryCodeStringCountry code of the source number (ISO 3166-1 alpha-2 format, e.g., "SG", "US")
destinationCountryCodeStringCountry code of the destination number (ISO 3166-1 alpha-2 format, e.g., "SG", "US")
sourceRefIdString(Optional) For OUTBOUND calls, the reference ID of the virtual number used as caller ID
destinationRefIdString(Optional) For INBOUND calls, the reference ID of the virtual number that was called
callStatusStringFinal status of the call leg. Possible values:
COMPLETED
BUSY
NO_ANSWER
FAILED
CANCELED
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 Scenarios​

Scenario 1: Inbound Call → DTMF → Bridge Call → Answered​

An inbound call is received, the caller navigates an IVR menu (DTMF), and is successfully bridged to a destination that answers.

Session Status: COMPLETED Call Count: 2 (inbound leg + outbound bridged leg)

{
  "payload": {
    "sessionId": "a089b40d-f059-11f0-8937-99c7872ee3c4",
    "subAccountId": "8x8_test",
    "sessionStatus": "COMPLETED",
    "startTime": "2026-01-13T08:26:58Z",
    "endTime": "2026-01-13T08:27:33Z",
    "lastAction": "MAKE_CALL",
    "callCount": 2,
    "clientRequestId": "Request-Id-Client-Confirmation-1200",
    "details": {
      "callA": {
        "callId": "a08f331e-f059-11f0-816b-2daade7d6599",
        "callDirection": "OUTBOUND",
        "callType": "PSTN",
        "initiatedTimestamp": "2026-01-13T08:26:58Z",
        "connectedTimestamp": "2026-01-13T08:27:09Z",
        "disconnectedTimestamp": "2026-01-13T08:27:33Z",
        "source": "+6568332048",
        "destination": "+6591178965",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "SG",
        "destinationCountryCode": "SG",
        "sourceRefId": "virtual-number-trunk-01",
        "callStatus": "COMPLETED",
        "callDuration": 23,
        "callQuality": {
          "mos": 4.5,
          "packetLossRate": 0,
          "jitter": 20
        }
      },
      "callB": {
        "callId": "aba1845a-f059-11f0-816b-2daade7d6599",
        "callDirection": "OUTBOUND",
        "callType": "PSTN",
        "initiatedTimestamp": "2026-01-13T08:27:17Z",
        "connectedTimestamp": "2026-01-13T08:27:26Z",
        "disconnectedTimestamp": "2026-01-13T08:27:33Z",
        "source": "+6568332048",
        "destination": "+6531589338",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "SG",
        "destinationCountryCode": "SG",
        "sourceRefId": "virtual-number-trunk-01",
        "callStatus": "COMPLETED",
        "callDuration": 6,
        "callQuality": {
          "mos": 4.5,
          "packetLossRate": 0,
          "jitter": 20
        }
      }
    }
  },
  "namespace": "VOICE",
  "eventType": "SESSION_SUMMARY",
  "description": "Summary of a completed call session",
  "version": 5
}

Scenario 2: Inbound Call → DTMF → Bridge Call → Busy​

An inbound call is received, the caller navigates an IVR menu, but the bridged destination is busy.

Session Status: BUSY Call Count: 2 (inbound leg + attempted outbound leg)

{
  "payload": {
    "sessionId": "ece96728-f059-11f0-baa6-c147150ab00e",
    "subAccountId": "8x8_test",
    "sessionStatus": "BUSY",
    "startTime": "2026-01-13T08:29:06Z",
    "endTime": "2026-01-13T08:29:43Z",
    "lastAction": "MAKE_CALL",
    "callCount": 2,
    "details": {
      "callA": {
        "callId": "ece96727-f059-11f0-baa6-c93abb37794a",
        "callDirection": "INBOUND",
        "callType": "PSTN",
        "initiatedTimestamp": "2026-01-13T08:29:06Z",
        "connectedTimestamp": "2026-01-13T08:29:07Z",
        "disconnectedTimestamp": "2026-01-13T08:29:43Z",
        "source": "+6591178965",
        "destination": "+6568332048",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "SG",
        "destinationCountryCode": "SG",
        "destinationRefId": "virtual-number-trunk-01",
        "callStatus": "COMPLETED",
        "callDuration": 37,
        "callQuality": {
          "mos": 4.5,
          "packetLossRate": 0,
          "jitter": 20
        }
      },
      "callB": {
        "callId": "faa4dfc1-f059-11f0-816b-2daade7d6599",
        "callDirection": "OUTBOUND",
        "callType": "PSTN",
        "initiatedTimestamp": "2026-01-13T08:29:29Z",
        "disconnectedTimestamp": "2026-01-13T08:29:43Z",
        "source": "+6568332048",
        "destination": "+6531589338",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "SG",
        "destinationCountryCode": "SG",
        "sourceRefId": "virtual-number-trunk-01",
        "callStatus": "BUSY",
        "callDuration": 0
      }
    }
  },
  "namespace": "VOICE",
  "eventType": "SESSION_SUMMARY",
  "description": "Summary of a completed call session",
  "version": 5
}

Scenario 3: Inbound Call → DTMF → Hangup​

An inbound call is received, the caller navigates an IVR menu, but hangs up before being bridged.

Session Status: COMPLETED Call Count: 1 (only the inbound leg)

{
  "payload": {
    "sessionId": "4eec57d5-f05a-11f0-baa6-c147150ab00e",
    "subAccountId": "8x8_test",
    "sessionStatus": "COMPLETED",
    "startTime": "2026-01-13T08:31:51Z",
    "endTime": "2026-01-13T08:32:08Z",
    "lastAction": "HANGUP",
    "callCount": 1,
    "details": {
      "callA": {
        "callId": "4eec57d4-f05a-11f0-baa6-c93abb37794a",
        "callDirection": "INBOUND",
        "callType": "PSTN",
        "initiatedTimestamp": "2026-01-13T08:31:51Z",
        "connectedTimestamp": "2026-01-13T08:31:52Z",
        "disconnectedTimestamp": "2026-01-13T08:32:08Z",
        "source": "+6591178965",
        "destination": "+6568332048",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "SG",
        "destinationCountryCode": "SG",
        "destinationRefId": "virtual-number-trunk-01",
        "callStatus": "COMPLETED",
        "callDuration": 16,
        "callQuality": {
          "mos": 4.5,
          "packetLossRate": 0,
          "jitter": 20
        }
      }
    }
  },
  "namespace": "VOICE",
  "eventType": "SESSION_SUMMARY",
  "description": "Summary of a completed call session",
  "version": 5
}

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​