Webhooks

Webhooks #

Post call webhooks provide information about each call that completed on the system. This information can be used to update external systems or start work-flow automations, using products like Azure Logic Apps or Zapier.

Example use cases:

  • Add a call history event against a CRM record
  • Add call recording playback details to a CRM record
  • Record successful sales in CRM
  • Track customer complaints in an external system
Information Circle info
Multiple Webhooks can be configured (licence depending) to provide post call information to different external systems as required.

Configuring a Webhook #

Filter Conditions #

By default, a webhook will fire for all call sessions unless a filter is applied. Filters can be added for most call properties to allow the webhook to be restricted to only fire on 'External' calls for example, or call which match a specific 'DDI' number.

Add filter options as required. When multiple filter fields are added, they are combined using an 'AND' operator.

Information Circle info
For more information on filtering, refer here

Action #

Parameter Options Description
URL https:// Provide an HTTPS URL that the trigger will call when fired.
Request method GET, POST, PUT Choose the required request method for the webhook.
Request format JSON, Form Data Choose the required request format for the webhook if POST or PUT are selected as the Request method.
Additional payload data Key/value pair If required, additional static information can be added to the webhook payload. Enter any additional data as key/value pairs as required.
Retry attempts 0 - 10 Default 1. Enter the number of times that the webhook should retry if the at any point there is an unsuccessful
Hand Left warning
Webhook trigger configuration is cached to improve performance. Any new triggers or changes to existing triggers may take up to 10 minutes before they take effect.
Information Circle info
The timeout for a webhook request is 10 seconds. The time between retry attempts is equal to the Attempt Number x 2 Seconds

Payload Data

The table below shows the data provided in the trigger payload.

Parameter Description
triggerID The unique id for the trigger the web hook request is being fired for.
id The id of the entity which is changing (user Id or tenant Id).
tenantId The customer tenant Id that the event is associated to.
cdr The call data payload
customData If configured against the trigger, any additional payload key/value pair information will be passed here.

CDR Data

Parameter Description
id The session id for the CDR record.
dType CDR record type - "CloudSessionCdr"
sVer CDR version - 1
pbxId ~.Dimensions.~ id for the communications platform the CDR is from (e.g. ~.pbx.kazoo.name.~)
pbxName The configured name of the communications platform
tz TZ identifier for the call times.
start Start time of the call session.
answer Time the calls was first answered.
end End time of the call session.
dur Duration of the call in seconds.
ring Ring time of the call in seconds.
talk Talk time of the call in seconds.
hold Hold time of the call in seconds.
park Park time of the call in seconds.
lost Indication of whether the call was abandoned - 1/0
lostinPark Indication of whether the call was abandoned whilst parked - 1/0
aban Indication of whether the call was a short ringing call or not - 1/0
ans Indication of whether the call was ans - 1/0
short Indication of whether the call was called as having a short duration - 1/0
cause Clear down cause for the call.
dir Call direction. 0 - Unknown, 1 - Internal, 2 - Incoming, 3 - Outgoing, 4 - Both
type Call type. 0 - Unknown, 1 - Internal, 2 - External
t2t Indication of whether the call was a trunk to trunk call - 1/0
cliNum Caller Id (CLI) number in E.164 format.
cliName Caller name
cliLoc CLI Location
cliArea CLI area code
cliState CLI state (US-Only)
cliCtry CLI country
ddiNum DDI number in E.164 format.
ddiName DDI name
fRngDevNum First rang device number.
fRngDevName First rang device name.
lRngDevNum Last rang device number.
lRngDevName Last rang device name.
ansDevNum Answering device number.
ansDevName Answering device name.
lAnsDevNum Last answering device number.
lAnsDevName Last answering device name.
fRngUsrNum First rang user number.
fRngUsrName First rang user name.
lRngUsrNum Last rang user number.
lRngUsrName Last rang user name.
ansUsrNum Answering user number.
ansUsrName Answering user name.
lAnsUsrNum Last answering user number.
lAnsUsrName Last answering user name.
fRngAgtNum First rang agent number.
fRngAgtName First rang agent name.
lRngAgtNum Last rang agent number.
lRngAgtName Last rang agent name.
ansAgtNum Answering agent number.
ansAgtName Answering agent name.
lAnsAgtNum Last answering agent number.
lAnsAgtName Last answering agent name.
rteID Prefix number. Any number added to the CLI as prefix during routing through the communications platform.
rteName Prefix name. Any string added to the Caller Name as prefix during routing through the communications platform.
fRngGroupName First rang group name.
lRngGroupName Last rang group name.
ansGroupName Answering group name.
hasRec Indication of whether the call was recorded - 1/0
rate Indication of whether the call has been rated - 1/0
rateCost The rate cost (double).
rateBand The band name for the rate.
rateName The name of the rate applied.
recordingIds String array of Ids for any recordings associated with this call session.
directorymatches Contact directory item Array of any contacts matched to the call.
tags Array containing a key/value pair of any tags applied to the call.

CDR Contact Directory Item

Key Description Type
title Contact title (Mr, Mrs, Dr etc.) string
fullName Full name for the contact. This is used in reports and ~.UcClient.~ clients to help users identify callers. string
companyName The name of the company the contact works for. string
jobTitle The contact position with the company. string
phone1 to phone4 A contact email address for the contact. E.164
email Up to 4 different contact telephone number fields string
crmId A unique id for the contact record from an external CRM system string
field1 to field 10 10 fields for carrying any custom data for the contact record string
Color Wand tip
The triggerId can be found by editing a configured trigger in the Customer Portal and copying the GUID from the end of the URL. e.g. https://myreports.com/en-GB/webhooks/00000000-0000-0000-0000-000000000000

Example JSON payload

Example JSON payload format for PUT/POST requests:

{
    "triggerId": "00000000-0000-0000-0000-000000000000",
    "id": "00000000-0000-0000-0000-000000000000",
    "tenantId": "00000000-0000-0000-0000-000000000000",
    "cdr": {
        "id": "00000000-0000-0000-0000-000000000000",
        "dType": "CloudSessionCdr",
        "sVer": 1,
        "pbxId": "00000000-0000-0000-0000-000000000000",
        "pbxName": "BenDV1 - Dev - Ben",
        "tz": "Europe/London",
        "start": "2024-05-29T09:37:35+01:00",
        "end": "2024-05-29T09:37:45+01:00",
        "dur": 10,
        "ring": 10,
        "lost": 1,
        "cause": "NORMAL_CLEARING",
        "dir": 2,
        "type": 2,
        "cliNum": "\\u002B447000000000",
        "cliLoc": "United Kingdom",
        "cliCtry": "GB",
        "ddiNum": "\\u002B441610000000",
        "fRngDevNum": "user_**\*\***",
        "fRngDevName": "(T42S) Test User",
        "lRngDevNum": "user\_**\*\***",
        "lRgDevName": "(T42S) Test User",
        "fRngUsrNum": "302",
        "fRngUsrName": "Test User",
        "lRngUsrNum": "302",
        "lRngUsrName": "Test User",
        "fRngAgtNum": "302",
        "fRngAgtName": "Test User",
        "lRngAgtNum": "302",
        "lRngAgtName": "Test User",
        "hasRec": 1,
        "recordingIds": ["00000000-0000-0000-0000-000000000000"]["00000000-0000-0000-0000-000000000000"],
        "directoryMatches": [{
            "dirName": "My Global",
            "dirId": "00000000-0000-0000-0000-000000000000",
            "dirType": "DirectoryContactMatch",
            "contactId": "00000000-0000-0000-0000-000000000000",
            "fields": {
            "fullName": "Example Contact",
            "companyName": "Company",
            "jobTitle": "Job Title",
            "email": "Email Address",
            "field1": "field1",
            "field2": "field2",
            "field3": "field3",
            "field4": "field4",
            "field5": "field5",
            "field6": "field6",
            "field7": "field7",
            "field8": "field8",
            "field9": "field9",
            "field10": "301"
            }][{
            "dirName": "My Global",
            "dirId": "00000000-0000-0000-0000-000000000000",
            "dirType": "DirectoryContactMatch",
            "contactId": "00000000-0000-0000-0000-000000000000",
            "fields": {
            "fullName": "Example Contact",
            "companyName": "Company",
            "jobTitle": "Job Title",
            "email": "Email Address",
            "field1": "field1",
            "field2": "field2",
            "field3": "field3",
            "field4": "field4",
            "field5": "field5",
            "field6": "field6",
            "field7": "field7",
            "field8": "field8",
            "field9": "field9",
            "field10": "301"
            }],
        "tags": {
            "Support": "step1"
        }
    },
    "customData": {
        "hook": "post call"
    }
}