Voice IVR Call Handle

When an incoming call is placed to a Virtual Number, allocated to your sub-account, a call flow is initiated. For each call flow event (incoming call, call update, or DTMF input), a Call Handle will be sent to your "Voice Call Action" (VCA) endpoint. Your "Voice Call Action" (VCA) endpoint can be configured on the sub-account level with the Webhooks

Sample Call Handle:

{
    "namespace": "VOICE",
    "eventType": "CALL_STATUS",
    "description": "Status update of a call",
    "payload": {
        "eventId": "eb0fc709-9693-11ea-454d-1705dde98182",
        "callId": "a1d6a5e3-efec-11e9-b999-7d370b5f90d1",
        "sessionId": "a1d6a5e2-efec-11e9-b999-efc71013a78f",
        "subAccountId": "your_subaccount_id",
        "callStatus": "CALL_RECEIVED",
        "callDirection": "INBOUND | OUTBOUND",
        "callType": "PSTN",
        "source": "+65123456789",
        "destination": "+65987654321",
        "sourceFormat": "MSISDN",
        "destinationFormat": "MSISDN",
        "sourceCountryCode": "SG",
        "destinationCountryCode": "SG",
        "sourceRefId": "NumberRef1",
        "destinationRefId": "vn-ref-1",
        "callDuration": 10,
        "eventData": "additional event data",
        "sipCode": 200,
        "timestamp": "2019-10-16T08:12:01Z"
    }
}

The JSON object will contain the following values:

Name

Type

Description

namespace

String

8x8 product channel definition

eventType

String

Current call handle event type. CALL_STATUS, CALL_ACTION or SESSION_SUMMARY

description

String

Description of the current call handle event type

payload

object

contains call information about the current number masking session

eventId

String

Id unique to a event of the current number masking session [UUID]

callId

String

Id unique to a call leg of the current number masking session [UUID]

sessionId

String

Id unique to the current number masking session [UUID]

subAccountId

String

unique id for your subacount

callStatus

String

Status of the current call leg. Values can be:
CALL_INITIATED
CALL_RECEIVED
CALL_CONNECTED
CALL_DISCONNECTED
CALL_UPDATED
DTMF_RECEIVED

callDirection

String

Direction of the call leg. INBOUND or OUTBOUND

callType

String

For Number Masking the call type is always PSTN

source

String

Source number of the call leg. For inbound calls, the source represents the calling user's phone number

destination

String

Destination number of the call leg. For inbound calls, the destination represents one of Virtual numbers allocated to your subaccount

sourceFormat

String

Source format for number masking is always MSISDN

sourceCountryCode

String

Country code of the source number

destinationCountryCode

String

Country code of the destination number

callDuration

Integer

Call duration for the current call leg

sipCode

Integer

Final Sip status code for the call leg defined by RFC 3261

Timestamp

Timestamp

Timestamp of the processed event

To start your call flow you need to reply to the call handle with an HTTP 200 response code including a Call Action in the HTTP response body. The supported Call Actions are:

  • PlayTTS - Generates and plays a TTS to the calling user.
  • PlayFile - Plays a pre-recorded message to the calling user.
  • MakeCall - Initiates an outgoing call to the desired destination. Once answered, the calling user and the second user (outgoing call destination) will be connected to the same call flow.
  • Hangup - Terminates the ongoing call.