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.