Call Handle

This method allows you to set up your handleURL and to forward all incoming calls to your Virtual Number to this URL.

Your handleURL can be configured at the sub account level through the Number Masking webhooks.

Request

When receiving an incoming call to your virtual number Wavecell platform will POST a JSON object to your URL.

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. CALL_RECEIVED, CALL_INITIATED or CALL_DISCONNECTED

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.

destination

String

Destination number of the call leg.

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

Example of a JSON object sent to your handleURL:

{
    "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_INITIATED",
        "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"
    }
}

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.