Skip to main content
GuidesAPI ReferenceSupport

Voice Call Action Webhook Guide

Voice Call Action Webhook Guide​

The Voice Call Action (VCA) webhook is a callback mechanism that allows your application to receive real-time events during an active voice session and respond with dynamic callflow instructions.

Overview​

VCA webhooks are used across multiple 8x8 Voice products:

ProductUse Case
IVRReceive DTMF input from callers and respond with next menu or action
Number MaskingHandle call events and control call routing between masked parties
Voice MessagingTrack call progression and handle custom logic

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

How It Works​

  1. Call event occurs – A caller presses a digit (DTMF), a call connects, or another action completes
  2. 8x8 sends webhook – The platform POSTs a JSON payload to your configured VCA endpoint
  3. Your server responds – Return a callflow JSON to instruct 8x8 what to do next (play audio, bridge call, hang up, etc.)

VCA Webhook Flow Diagram​

VCA Webhook Flow

📘 Product-Specific Guides

For detailed implementation guides specific to each product:

Call Action Request (IVR)​

8x8 platform will POST a JSON object to your URL.

Sample of Call Action Event

{
  "namespace": "VOICE",
  "eventType": "CALL_ACTION",
  "description": "Action request of a call",
  "payload": {
    "eventId": "77e6a667-133a-11ef-9dd4-e911cc6fc82f",
    "callId": "627e25f1-133a-11ef-b08c-e33c09483244",
    "sessionId": "a4fad4b3-b388-12ee-b217-2fb8260fcf59",
    "subAccountId": "account_x",
    "callStatus": "ACTION_COMPLETED",
    "callDirection": "OUTBOUND",
    "callType": "PSTN",
    "source": "+6568888888",
    "destination": "+6598888888",
    "sourceFormat": "MSISDN",
    "destinationFormat": "MSISDN",
    "sourceCountryCode": "SG",
    "destinationCountryCode": "SG",
    "sourceRefId": "SOME-VN-REF-ID",
    "destinationRefId": "ANOTHER-VN-REF-ID",
    "callDuration": 0,
    "eventData": {            
      "dtmf": "1", //Nullable    
    },
    "sipCode": 200,
    "timestamp": "2024-05-16T04:12:11.217Z"
    "clientActionId": "ivr1_level1"
  }
}

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 action events the value will be "CALL_ACTION"
descriptionStringDescription of the event type that triggered the callback.
eventIdStringUnique id that triggered the callback
callIdStringId unique to a one call leg of the number masking session [UUID]
sessionIdStringUnique id that represents Number masking session [UUID]
subAccountIdStringId of the 8x8 SubAccount that the callback belongs to.
callStatusStringStatus of the call leg that triggered the callback. Values can be:
"ACTION_COMPLETED"
"CALL_RECEIVED" (applicable to Inbound IVR and Number Masking)
callDirectionStringDirection of the call leg that triggered the callback. Values can be "INBOUND" or "OUTBOUND"
callTypeStringType of the call leg. Values can be "PSTN" (telco operators) or "VOIP"(app to app calling users) users), depending on where the call was initiated from.
sourceStringSource number associated with the call leg that triggered this callback
sourceFormatStringFormat of the source number. For NumberMasking the value will always be "MSISDN"
destinationFormatStringFormat of the destination number. For NumberMasking the value will always be "MSISDN"
sourceCountryCodeStringCountry code of the source number
destinationCountryCodeStringCountry code of the destination number
sourceRefIdStringFor OUTBOUND call legs, this property shows the referenceId of the Virtual Number that has been called. For INBOUND calls the value is null
destinationRefIdStringFor INBOUND call legs, this property shows the referenceId of the Virtual Number that is used as callerId. For OUTBOUND calls the value is null
callDurationStringDuration of the call leg (in seconds) that initiated the callback
dtmfStringDTMF captured if SayAndCapture action is requested. Will be null if nothing is captured.
sipCodeIntegerFinal Sip status code for the call leg(s) defined by RFC 3261
timestampStringTimestamp of a call event
clientActionIdStringclientActionId that was provided in the previous VCA callback.

🚧 ClientActionId

clientActionId is only supported in Voice Call Action Webhook

clientActionId in Voice Call Action Response

{
    "clientActionId": "ivr1_level2", // Optional. Only supported in Call Action Webhook.
    "callflow": [
        {
            "action": "makeCall", 
            "params": {
                "source": "+65123456789",
                "destination": "+6543212345",
                "callRecording": true
            }
        }
    ]
}

Support Channels​