Call Action Handling (Number Masking)

This method provides insights about call details and 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 Number Masking Webhooks.

Call Action Request

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

The JSON object will contain the following values:

Example of a JSON object sent to your handleURL:

{
	"namespace": "VOICE",
	"eventType": "CALL_ACTION",
	"description": "Action request 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",
		"callType": "PSTN",
		"source": "+65123456789",
		"destination": "+65987654321",
		"sourceFormat": "MSISDN",
		"destinationFormat": "MSISDN",
		"sourceCountryCode": "SG",
		"destinationCountryCode": "SG",
		"destinationRefId": "vn-ref-1",
		"callDuration": 0,
		"sipCode": 200,
		"timestamp": "2019-10-16T08:12:01Z"
	}
}

Responding to Call Action Request

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

• makeCall - Initiates an outgoing call to the desired destination. This function should be used to connect the first call with another party.
• say - Generates and plays a TTS to the calling user.
• hangup - Disconnects all active calls. This will terminate the session, triggering the session summary webhook.

makeCall

This function should be used to connect the first call with another party.

The following is an example of the JSON response you would need to provide:

{
   "clientActionId": "NumberMaskingId1",
   "callflow": [
      {
         "action": "makeCall",
         "params": {
            "source": "6512345678",
            "destination": "6587654321",
            "callRecording": true //Optional. Use only if call recording has been set up.
         }
      }
   ]
}

The action should contain the following parameters:

say

This action should be used to play a text to speech message on the call.

The following is an example of the JSON response you would need to provide:

{
  "clientActionId": "NumberMaskingId1",
  "callflow": [
    {
      "action": "say",
      "params": {
        "text": "Hello This is a test message",
        "voiceProfile": "en-US-ZiraRUS",
        "repetition": 1,//optional(default is 1)
        "speed": 1.0,//optional(defailt is 1)
      }
    }
  ]
}

The above example would be used if you want the message

The action should contain the following parameters:

playFile

Downloads the sound/voice file provided and plays it back in the currently active call.

File type requirements:

• Supported file types are .wav and mp3.
• API only accepts file that is smaller than 5MB.

The following is an example of the JSON response you would need to provide:

{
  "clientActionId": "ivr1_level2",
  "callflow": [
    {
  "action": "playFile",
	"params": {
    "fileUrl": "https://sample-videos.com/audio/mp3/wave.mp3",  // mandatory
    "repetition": 1   //optional
      }
    }
  ]
}

The action should contain the following parameters:

📘

Downloaded Voice files

Downloaded voice files are cached for 1 hour for faster access, if used in consequent requests. If the file content is changed within 1 hour after the first request, make sure to change the file name for the changes to be reflected in the calls afterward

hangup

This action should be used to hang up the incoming call.

The following is an example of the JSON response you would need to provide:

{
	"clientActionId": "NumberMaskingId1",
	"callflow": [ 
		{
  		"action": "hangup" 
    }
  ]
}

Note: The Hangup action terminates the active call session.

Commands Example

On the following example it is demonstrated how multiple actions can be used in the same call action handle reply:

{
  "clientActionId": "NumberMaskingId1",
	"callflow": [ 
    {
      "action": "say",
        "params": {
          "text": "Hello This is a test message",
          "voiceProfile": "en-US-ZiraRUS",
          "repetition": 1,//optional(default is 1)
          "speed": 1.0,//optional(defailt is 1)
      }
    },
    {
  		"action": "hangup" 
    }
  ] 
}