The platform implements a system of guaranteed hook delivery.
The system expects a 200th code in response for each hook sent. Otherwise, messages will be resent for 24 hours with the resend intervals increasing according to an exponential formula (the more attempts, the larger the interval of attempts will be).
Inter-server communication waits for confirmation in receiving the sent data.
If you only need one type of hook, you can respond with 200 code to all other transmissions and do nothing with the received data. The decision what to process and what to ignore is on the business logic side of the customer's company.
Webhook with information about a call transferred to an operator. To send it, you need to configure transfer to operator in the bot dialog. It is sent for both incoming and outgoing calls.
The event is sent by the first hook to inform the third-party system that the call has been transferred to the KC.
Request body:
{
"event": "CALL_REDIRECTED",
"id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"redirectAdditional": null,
"redirectAnons": null,
"redirectDestination": "ch",
"redirectDestinationId": "10103",
"callbackData": []
}
Field Description:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| event | string | yes | Event Type. Possible values: - CALL_REDIRECTED (The call has been transferred). |
| id | string | yes | Call ID. |
| redirectAdditional | string | yes | Additional data that goes into the SIP exchange. |
| redirectAnons | string | yes | The accompanying translation text specified in the bot's settings when transferring a call. |
| redirectDestinationId | string | yes | Translation type (customizable in the bot script): - ch (translation channel); - custom (arbitrary translation). |
| | callbackData | Object | yes (can be empty) | The candidate information passed in when the candidate was added (see the method for adding a candidate). |
Webhook with information about the call attempt. Sent at the end of the call for both incoming and outgoing calls.
Request body:
{
"event": "CALL_ENDED",
"type": "OUTGOING",
"companyId": 5,
"botId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"externalId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"taskId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"candidateId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"status": "ANSWERED",
"callFrom": "74992868344",
"callTo": "74992868344",
"startedAt": "2023-06-13T10:49:36+00:00",
"finishedAt": "2023-06-13T10:49:38+00:00",
"billedAt": "2023-06-13T10:49:55+00:00",
"variables": {
"age": "35",
"name": "John Smith",
"tryNumber": 0,
"recordPath": "https://tcl.twin24.ai/record/bce7d22e-dde6-4427-b391-ebbdfda44de6/download",
"humanNumber": 0,
"resultNumber": 0,
"tryCandidate": 0,
"answeredNumber": 0,
"humanCandidate": 0,
"resultCandidate": 0,
"answeredCandidate": 0
},
"result": {
"nps": "test",
"date": "-",
"evaluation": "-",
"confirmation": "-",
"markers": [
"Marker 1",
"Marker 2",
"Marker 3"
],
"initialVariables": {
"customVariable1": "The value of the first user variable.",
"customVariable2": "The value of the second user variable.",
"phone": "74992868344",
"tryNumber": 0,
"recordPath": "https://tcl.twin24.ai/record/bce7d22e-dde6-4427-b391-ebbdfda44de6/download",
"humanNumber": 0,
"resultNumber": 0,
"tryCandidate": 0,
"answeredNumber": 0,
"humanCandidate": 0,
"resultCandidate": 0,
"answeredCandidate": 0
},
"key_1": "value 1",
"key_2": "value 2"
},
"amd": "MACH",
"recordPath": "/180/2023/6/13/1000000000.0000000_74992868344_180.mp3",
"flow": [
{
"botId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"start": "2023-06-13 13:49:37.016654+03",
"end": "2023-06-13 13:49:37.016654+03",
"messages": [
{
"text": "Hi and bye.",
"author": "BOT",
"time": "2023-06-13 13:49:37.016654+03"
}
]
}
],
"gmtOffset": 0,
"hungUpBy": null,
"duration": 2,
"totalCost": 0.09,
"robotCallDuration": 1,
"robotCallTotalCost": 0.05,
"mainCallCost": 1.45,
"mainCallDiscount": 0,
"mainCallDuration": 2,
"mainCallTotalCost": 0.05,
"autoCallCost": 0,
"autoCallDiscount": 0,
"autoCallDuration": 0,
"autoCallTotalCost": 0,
"robotCallCost": 2.5,
"robotCallDiscount": 0,
"transferCallCost": 0,
"transferCallDiscount": 0,
"transferCallDuration": 0,
"transferCallTotalCost": 0.05,
"clientExternalId":null,
"isEffective": true,
"hangUpCause": 16,
"callbackData": []
}
Field Description:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| event | string | yes | Event Type. Possible values: - CALL_ENDED (The challenge is over). |
| type | string | yes | Call Type. Possible values: - INCOMING (Incoming); - OUTGOING (Outgoing). |
| companyId | int | yes | Company Identifier. |
| botId | string | yes | Scenario ID. |
| id | string | yes | Call ID. |
| externalId | string | yes | The identifier passed in the initialization request (callId). |
| taskId | string | yes | Call job identifier. |
| candidateId | string | yes | Caller ID. |
| status | string | yes | Call Status. Possible values: - CANCEL (Call canceled); - ANSWERED (Challenge accepted); - NOANSWER (No answer); - BUSY (Busy); - CONGESTION (The operator rejected the call); - CHANUNAVAIL (Trunk's unavailable); - FAILED (System error during call processing); - SCHEDULED (The call is scheduled); - BLACKLIST (The phone is blacklisted); - DIAL (Dialing); - INPROGRESS (There's a dialog going on); - FZ230 (Prohibition of call under 230-FZ); - INVALID (The number is not correct); - UNAVAILABLE (Remote PBX is not available); - EXPIRED (Connection not established for timeout). |
| callFrom | string | yes | Calling number. |
| callTo | string | yes | Called number. |
| startedAt | string | yes | Call Start Date. |
| finishedAt | string | yes | End date of the call. |
| billedAt | string | yes | Call Billing Date. |
| variables | Object | yes | An arbitrary key-value type dictionary that was passed before the call was initialized. Contains the source variables. |
| | customVariable | string | not | User variables passed in at the start of the call. |
| | tryNumber | int | yes | Number of dialing attempts within a dialing task. |
| | recordPath | string | yes | Link to download the audio recording of the call. |
| | humanNumber | int | yes | The number of dials to a candidate number where the person who answered was NOT an answering machine is counted from 0. |
| | resultNumber | int | yes | The number of successful dials by the candidate number, counted from 0. |
| | tryCandidate | int | yes | The number of attempts to reach the candidate, counted from 0. |
| | answeredNumber | int | yes | The number of dials by the candidate number, counted from 0. |
| | humanCandidate | int | yes | The number of dials to a candidate where the person who answered was NOT an answering machine is counted from 0. |
| | resultCandidate | int | yes | The number of successful calls to the candidate, counted from 0. |
| | answeredCandidate | int | yes | The number of dial-ins to the candidate, counted from 0. |
| result | Object | yes (can be an empty array []) | Arbitrary key-value type dictionary. The results of the robot's conversation. |
| | nps | string | not | Information from the NPS field in the Result block. |
| | date | string | not | Information from the Date field in the Result block. |
| | evaluation | string | not | Information from the Evaluation field in the Result block. |
| | confirmation | string | not | Information from the Confirmation field in the Result block. |
| | markers | Array[string] | not | Markers. |
| | initialVariables | Object | not | Initial variables. |
| | | customVariable | string | not | User variables passed in at the start of the call. |
| | | phone | string | not | Called number. |
| | | tryNumber | int | not | Number of dialing attempts within a dialing task. |
| | | recordPath | string | not | Direct link to download the audio recording of the call. |
| | | humanNumber | int | not | The number of dials to a candidate number where the person who answered was NOT an answering machine is counted from 0. |
| | | resultNumber | int | not | The number of successful dials by the candidate number, counted from 0. |
| | | tryCandidate | int | not | The number of attempts to reach the candidate, counted from 0. |
| | | answeredNumber | int | not | The number of dials by the candidate number, counted from 0. |
| | | humanCandidate | int | not | The number of dials to a candidate where the person who answered was NOT an answering machine is counted from 0. |
| | | resultCandidate | int | not | The number of successful calls to the candidate, counted from 0. |
| | | answeredCandidate | int | not | The number of dial-ins to the candidate, counted from 0. |
| | ключ_1 | string | not | Arbitrary result. Defined in the Result block with the Random Result type. |
| amd | string | yes | Result of the answering machine detector. Possible values: - HUMN (person); - MACH (answering machine); - NOT_DEF (undefined). |
| recordPath | string | yes (can be an empty string) | Audio file link. |
| flow | Array[Object] | yes (can be an empty array []) | An array of conversation fragments. |
| | botId | string | yes | Scenario ID. |
| | start | string | yes | The start time of the dialog part. |
| | end | string | yes | End time for the dialog part. |
| | messages | Array[Object] | yes | An array of dialog messages. |
| | | text | string | yes | Message Text. |
| | | author | string | yes | Who delivered the message (BOT, CLIENT). |
| | | time | string | yes | The time the message was sent. Always at UTC+0. |
| gmtOffset | int | yes | Offset in minutes from the UTC of the client's time zone. |
| hungUpBy | string | yes (can be null) | Who hung up on me (BOT, HUMAN). |
| duration | int | yes | Total duration of the conversation. |
| totalCost | float | yes | Total cost of the call. |
| robotCallDuration | int | yes | The duration of the robot's conversation. |
| robotCallTotalCost | float | yes | The cost of a discounted robot talk. |
| mainCallCost | float | yes | Cost of the call (customer trunk). |
| mainCallDiscount | float | yes | Discount per conversation (customer trunk). |
| mainCallDuration | int | yes | Length of conversation (customer trunk). |
| mainCallTotalCost | float | yes | The cost of a discounted call (customer trunk). |
| autoCallCost | float | yes | It's always 0. |
| autoCallDiscount | float | yes | It's always 0. |
| autoCallDuration | int | yes | It's always 0. |
| autoCallTotalCost | float | yes | It's always 0. |
| robotCallCost | float | yes | The cost of a robot conversation. |
| robotCallDiscount | float | yes | A discount for robot talk. |
| transferCallCost | float | yes | Cost of transferring a call. |
| transferCallDiscount | float | yes | Call transfer discount. |
| transferCallDuration | int | yes | The duration of the call after the transfer. |
| transferCallTotalCost | float | yes | The cost of the call after the transfer is discounted. |
| clientExternalId | string | yes (can be null) | An identifier that is added independently when adding a candidate. In case the identifier was not added, the value null will be returned. |
| isEffective | boolean | yes | Call effectiveness. Can be set in the script using the Fixation efficiency action in the Result block, or using the Effective call duration parameter in the call task settings. |
| hangUpCause | int | yes | Q850 telephony response code. All Q850 telephony response codes |
| callbackData | Object | yes (can be an empty array []) | The candidate information passed in when the candidate was added (see the method for adding a candidate). |
Webhook with information about the result of candidate processing. It is sent as a signal that this candidate is completely processed by the system and there will be no more calls on the candidate. It is sent only for outgoing calls.
This webhook can be relied upon to unblock a candidate in the CRM or dialer.
Request body:
{
"event": "CANDIDATE_CHANGED",
"id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"clientExternalId": null,
"taskId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"status": "FINISHED",
"lastCallId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"callbackData": []
}
Field Description:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| event | string | yes | Event Type. Possible values: - CANDIDATE_CHANGED (Status update by candidate). |
| id | string | yes | Candidate ID. |
| clientExternalId | string | yes (can be null) | The identifier (callId) passed in the initialization request. |
| taskId | string | yes | Call job identifier. |
| lastCallId | string | yes | Caller ID. |
| status | string | yes | Call Status. Possible values: - FINISHED (Candidate processing is complete, no further calls will be made). |
| callbackData | Object | yes (can be an empty array []) | The candidate information passed in when the candidate was added (see the method for adding a candidate). |
Webhook with information about a scheduled callback. Sent after scheduling a callback for a specific time from a bot script for outgoing calls only.
Request body:
{
"event":"RECALL_SCHEDULED",
"id":"bce7d22e-dde6-4427-b391-ebbdfda44de6",
"date":"2024-01-31T13:25:00+00:00",
"callbackData":[]
}
Field Description:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| event | string | yes | Event Type RECALL_SCHEDULED - indicates a scheduled callback within the current call (via the Result block). |
| id | string | yes | Call ID. |
| date | string | yes | The date and time for which the call is scheduled. |
| callbackData | Array | yes | A field for additional information. |
Webhook with information about efficiency changes. It is sent as a signal of call efficiency change for outgoing and incoming calls.
In the bot script, the call efficiency is configured in the Fixation efficiency field of the Result block.
When creating a Creating a call task, the call efficiency is customized in the Effective call duration, more field, as well as in the Not effective callback script.
The settings in the bot script take precedence over the settings in the calling-task.
Request body:
{
"event": "EFFICIENCY_REACHED",
"id": "4f29df1c-1026-43b7-a60f-15b6b0d441b2",
"state": true,
"callbackData": []
}
Field Description:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| event | string | yes | Event type EFFICIENCY_REACHED - indicates a change in performance. |
| id | string | yes | Call ID. |
| state | boolean | yes | Performance condition. If true - effective, if false - not effective. |
| callbackData | Array | yes | Additional data related to the event. |
Call 1 candidate (1 number, no transfer to operator):
Receive the hook CALL_ENDED.
Receive the CANDIDATE_CHANGED hook.
Call 1 candidate (1 number, transfer to operator):
Receive the hook CALL_REDIRECTED.
Receive the CALL_ENDED hook.
Get the CANDIDATE_CHANGED hook.
Call 1 candidate (2+ numbers, no transfer to operator):
Receive the hook CALL_ENDED.
Receive the CALL_ENDED hook.
Get the CANDIDATE_CHANGED hook.
Call 1 candidate (2+ numbers, transfer to operator):
Receive the hook CALL_REDIRECTED.
Receive the CALL_ENDED hook.
Get the CALL_REDIRECTED hook.
Get the CALL_ENDED hook.
Get the CANDIDATE_CHANGED hook.
Call 1 candidate (1 number, scheduled to call back):
Receive the RECALL_SCHEDULED hook.
Receive the CALL_ENDED hook.
Get the CALL_ENDED hook.
Get the CANDIDATE_CHANGED hook.
Call 1 candidate (1 number, scheduled to call back, change in performance):
Receive the hook RECALL_SCHEDULED.
Receive the hook CALL_ENDED.
Get the EFFICIENCY_REACHED hook.
Get the CALL_ENDED hook.
Get the CANDIDATE_CHANGED hook.
Configure to receive webhook information under hook management.