Setting up a Webhook to Receive Call Statuses

In this section, you will be acquainted with a simplistic Webhook API for you to receive call status update notifications for your voice calls.

To set up a Webhook on your Voice Application

Create Webhook API

curl --location --request POST '<https://voice.unifonic.com/v1/providers/webhook>'  
--header '_AppsId: 'XXXXXXXXXXXXXX_'  
--header 'Content-Type: application/json'  
--data-raw '{
    "url":"insert your webhook endpoint here",
    "basicAuthNeeded": false,
    "username":"XX",  //optional
    "password":"XXX". //optional
}}'

If basicAuthNeeded is true, the username and password must be included. Otherwise, feel free to omit it.

Sample of a webhook notification sent to you for outbound IVR

text

{
    “applicationId”: “xxxx”,
    “callSid”: “xxxx”,// our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “parentCallSid”: null,our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “from”: “+96611xxx”,// the masking number (i.e. the caller ID)
    “to”: “+96650xxxx”,// the phone number of the called party
    “duration”: 17, // duration of the call (in seconds)
    “direction”: “OUTBOUND”,
    “status”: “COMPLETED”,
    “initiatedAt”: xxxx,// the date and time we initiated the outbound call to the operator
    “completedAt”: xxxx,// the date and time that we received the final call status feedback from the operator
    “useCase”: “IVR”,
    “accountId”: “xxxxx”,customer's unique account ID in Unifonic
    “referenceId”: “xxxx”,// this is your internally generated unique Id that you may have attached to the API request for your internal correlation
    “externalCallsId”: “xxxx”,//our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “recordingUrl”: “”,//a link to download the recording would be returned if the call was set to be recorded
    “failureReason”: xxxx,// failure reason may be provided if the call is not completed and the failure reason is provided by the operator
    “maskId”: null, //the Id we return when you create the number masking session (only applicable to number masking use case)
    “requestReceivedAt”: xxxx,//the date and time we received the inbound call from the operator
    “uniqueCallId”: “xxxx”,//our internal reference Id which are generated after the call is successfully terminated to the carrier for delivery
    “secondaryCallerId”: xxxx,//this is the failover call ID added to the API request
    “callId”: “xxxx”,//this is the Id we return in the initial response to your Outbound API call request
    “campaignId”: null //this is only relevant to voice campaigns uploaded and dispatched via our Unifonic console
}

Sample of a webhook notification sent to you for number masking (inbound leg)

text

{
    “applicationId”: “xxxx”,
    “callSid”: “xxxx”,// our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “parentCallSid”: null,// our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “from”: “+96650xxx”,// the phone number of the calling party
    “to”: “+96611xxxx”,// the masking number (i.e. the caller ID)
    “duration”: 17, // duration of the call (in seconds)
    “direction”: “INBOUND”,
    “status”: “COMPLETED”,
    “initiatedAt”: "xxxx",// the date and time we connect the inbond call to the called party
    “completedAt”: xxxx, // the date and time that we received the final call status feedback from the operator
    “useCase”: “NUMBER_MASKING”,
    “accountId”: “xxxx”,// customer's unique account ID in Unifonic
    “referenceId”: “xxxx”,// this is your internally generated unique Id that you may want to attach to each API request for your internal correlation
    “externalCallsId”: “xxxx”,// our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “recordingUrl”: “”,//a link to download the recording would be returned if the call was set to be recorded
    “failureReason”: xxxx,// failure reason may be provided if the call is not completed and the failure reason is provided by the operator
    “maskId”: xxxx, // the Id we return when you create the number masking session 
    “requestReceivedAt”: "xxxx",// the date and time we received the inbound call from the operator
    “uniqueCallId”: “xxxx”,//our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “secondaryCallerId”: null,// this is not applicable to number masking use case
    “callId”: “xxxx”,//this is the Id we return in the initial response to your outbound API call request
    “campaignId”: null // this is only relevant to voice campaigns uploaded and dispatched via our Unifonic console
}

Sample of a webhook notification sent to you for number masking (outbound leg)

text

{
    “applicationId”: “xxxx”,
    “callSid”: “xxxx”,// our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “parentCallSid”: null,// our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “from”: “+96611xxx”,// the masking number (i.e. the caller ID)
    “to”: “+96656xxxx”,// the phone number of the called party
    “duration”: 17, // duration of the call (in seconds)
    “direction”: “OUTBOUND”,
    “status”: “COMPLETED”,
    “initiatedAt”: "xxxx",// the date and time we initiated the outbound call to the operator
    “completedAt”: xxxx, // the date and time that we received the final call status feedback from the operator
    “useCase”: “NUMBER_MASKING”,
    “accountId”: “xxxx”,// customer's unique account ID in Unifonic
    “referenceId”: “xxxx”,// this is your internally generated unique Id that you may have attached to the API request for your internal correlation
    “externalCallsId”: “xxxx”,// our internal reference Id which is generated after the call is successfully terminated to the carrier for delivery
    “recordingUrl”: “”,//a link to download the recording would be returned if the call was set to be recorded
    “failureReason”: xxxx,// failure reason may be provided if the call is not completed and the failure reason is provided by the operator
    “maskId”: xxxx, // the Id we return when you create the number masking session 
    “requestReceivedAt”: "xxxx",// the date and time we received the inbound call from the operator
    “uniqueCallId”: “xxxx”,//our internal reference Id which are generated after the call is successfully terminated to the carrier for delivery
    “secondaryCallerId”: null,// this is not applicable to number masking use case
    “callId”: “xxxx”,//this is the Id we return in the initial response to your Outbound API call request
    “campaignId”: null // this is only relevant to voice campaigns uploaded and dispatched via our Unifonic console
}

New feature

Following our latest release, if there were a call recording activity during the call, a recording URL will appear in the webhook payload. The recording URL would be accessible for 72 hours. Thereafter, this URL will expire. The recording can still be downloaded from the Unifonic Console, depending on the Service Agreement you have with Unifonic.

Retrieve existing webhook

Check what is the configured endpoint to receive your call status updates.

curl --location --request GET '<https://voice.unifonic.com/v1/providers/webhook>'  
--header '_AppsId: 'XXXXXXXXXXXXXX_'  
--header 'Content-Type: application/json'  
}'