You will need an API access key (token) to work. The key allows you to identify your project and get access to it with maximum privileges without the need for prior authorization each time. You need to create a key on the personal account “API” page:
This key must be specified on each request in the Authorization header. All relative paths of all methods described in this documentation have paths relative to https://api.unitalk.cloud/api All requests to API methods are made in the POSTmode. The example results of using the API methods in this article are shown using Postman. In Postman mode, the required authorization header and method address are specified as follows:
You can also send a key in the format “Bearer *Your key*”
If the authorization key or header is missing or incorrect, the result of the method execution will be as follows:
Only the messageand data (if present) fields will be considered further in this instruction.
Yes, we know that JSON cannot contain comments, but we are sure that it will be easier to understand this way 🙂
Pricing
Сopied
Our API is pretty fast, and most of your requests will be done in milliseconds because we love to cache everything we can. But some might be more complex, so keep an eye on how long they take.
Processing under 50ms is considered as one request. <200ms – 2 requests <500 ms – 3 requests <1000 ms – 4 requests >1000 ms – 5 requests
Recommendations for reducing costs and increasing speed: Please note that you can sometimes significantly speed up processing by using a full match filter instead of a partial match filter. Or sometimes requesting more information and filtering the result may be faster than making multiple requests with complex filters. Also, use batch requests, such as in autodialer, because adding 1,000 numbers to a autodialer with a single request is much faster and cheaper for both you and us than making 1,000 requests (and if they all come at once, our DOS protection may be triggered). And sometimes you can use the cache, as we like to do 😊 You can find information about the use of requests for your tariff in the “My tariff” section in your personal account.
Limits
Сopied
There are restrictions to avoid unnecessary load due to untargeted, malicious or excessive requests. If the restrictions presented are not sufficient for full use of the services or have led to accidental blocking, please contact technical support.
Limits on the number of any HTTP requests: · More than 30 requests in 10 seconds – temporary blocking; · Repeated exceeding – temporary blocking of increased duration; · More than 100 requests in 10 seconds – permanent blocking. Limitation on simultaneous API calls: 20 simultaneous calls. Limitation on API calls requests: 15 per second.
Autodialer
Сopied
Work with autodialers is performed using actions, method: Relative path: /autodial/action Mode: POST Content-Type: application/json
Actions are secified required actionparameter in request body and define a list of required parameters. List of possible field values:
GET_LIST
Get autodialers list
GET_WITH_DATA
Get autodialers list with full data
ADD
Add autodialer
UPDATE
Update autodialer
REMOVE
Remove autodialer
REFRESH
Re-call numbers
CANCEL
Cancel autodialer
PAUSE
Pause autodialer
UNPAUSE
Unpause autodialer
ADD_NUMBERS
Add numbers
GET_NUMBER
Get information about autodialer’s number
GET_NUMBERS
Get information about autodialer’s numbers
GET_CALLS_HISTORY
Get information about autodialer’s calls
REMOVE_NUMBERS
Remove numbers from autodialer
REMOVE_ALL_NUMBERS
Remove all numbers from autodialer
Since this method has many variations of use and various parameters, it is recommended to set up several autodialers in your personal account and familiarize yourself with their functionality visually before studying these instructions.
Obtaining complete information about autodialers with additional data
Сopied
Action”Get autodialers list with full data” allows you to get detailed information about the current configuration of the project’s autodialres in the tasks array. In addition, dictionaries, parameters and lists that may be needed to interpret and change autodilaers configurations are additionally transmitted.
List of additional lists: ·audios – an array of project audios from the “Autodialers” section · moh – an array of project audios from the “Melodies of waiting on the line and queues” section ·groups – an array of project internal line groups
·pseudoGroupOperators – an array of project internal SIP lines ·scenarios – an array of project incoming scenarios ·outScenarios – an array of project outgoing scenarios ·ttsSettings – an array of project speech synthesis settings profiles ·voiceSecretaries – an array of project voice secretaries · The triggerActionEventsData and triggerActionEventsAndTriggerActions arrays provide information about autodialer events such as a sequence number and a list of available handlers
List of additional parameters: ·triggerActionsPresent – indicates the presence of event handlers in the project ·maxAddNumbersCount – maximum number of numbers that can be added in one action ·maxRemoveNumbersCount – maximum number of numbers that can be deleted in one action ·multiAudiosLimit – maximum number of elements in the compositeAudio list ·minMultiAudioSilenceMillis – minimum number of milliseconds in the silenceMillis element of the compositeAudio array ·maxMultiAudioSilenceMillis – maximum number of milliseconds in the silenceMillis element of the compositeAudio array
Request JSON:
{
"action": "GET_WITH_DATA"
}
An example of response in case of success:
{
"audios": { // An array of audios
"1234": "Sample_audio_name", // "ID": "Title"
...
},
"moh": { // An array of melodies of waiting on the line and queues
"2345": "Sample_moh_name", // "ID": "Title"
...
},
"groups": { // An array of internal line groups
"3456": "Sample_group_name", // "ID": "Title"
...
},
"scenarios": { // An array of incoming scenarios
"4567": "Main with IVR", // "ID": "Title"
...
},
"outScenarios": { // An array of outgoing scenarios
"5678": "From a fixed number", // "ID": "Title"
...
},
"ttsSettings": { // An array of speech synthesis settings profiles
"12": "Pretty woman voice", // "ID": "Title"
...
},
"voiceSecretaries": { // An array of voice secretaries
"97": "Sample_voice_secretary_name", // "ID": "Title"
...
},
"triggerActionEvents": { // An array of autodialer events
"AUTODIAL_FINISH": "Обзвон завершен", // "Event": "Title"
...
},
"triggerActionEventsData": [ // Autodialer events information
{
"event": "AUTODIAL_FINISH", // Event
"title": "Обзвон завершен", // Title
"order": 200 // Sequence number
},
...
],
"triggerActionEventsAndTriggerActions": { // Lists of avaliable handlers for each event
"AUTODIAL_FINISH": { // "Event": {List of avaliable handlers}
"123": "[Telegram] Personal notification", // "ID": "Title"
...
},
...
},
"triggerActionsPresent": true, // Sign of presence of event handlers in the project
"autodialNumberStatesInfo": { // Autodialer number states information
"lang": { // Project language
"locale": "ru",
"shortLocaleCode": "ru",
"code": "RU"
},
"orderedStates": [ // Ordered list of states based on sequence number
"NEW",
...
],
"statesAndTitles": { // An array of states with names
"DIALING": "В процессе обзвона",
...
},
"repeatableStates": [ // List of states avalible for automatic re-call
"BUSY",
...
],
"refreshableStates": [ // List of states avalible for REFRESH action
"FAIL",
...
],
"warningStates": [ // List of states indicating possible problems in the autodialer or telephony settings
"AUDIO_ERR",
...
],
"doneStates": [ // List of statuses corresponding to completed calls
"ANSWER",
...
]
},
"taskStatuses": { // An array of autodialer statuses
"IN_PROGRESS": "В процессе обзвона",
...
},
"autodialerTypes": { // An array of autodialer types
"AUTODIAL": "Autodialer",
"GUARANTEED_DIAL": "Guaranteed autodialer",
"VOICE_ROBOT": "Voice robot"
}
"autodialerModes": { // An array of autodialer modes
"FIXED": "By number of threads",
"FREE": "By free operators",
"SMART": "Smart selection"
},
"maxAddNumbersCount": 100000, // Maximum number of numbers that can be added in one action
"maxRemoveNumbersCount": 10000, // Maximum number of numbers that can be deleted in one action
"multiAudiosLimit": 20, // Maximum number of elements in the compositeAudio list
"minMultiAudioSilenceMillis": 1, // Minimum number of milliseconds in the silenceMillis element of the compositeAudio array
"maxMultiAudioSilenceMillis": 10000, // Maximum number of milliseconds in the silenceMillis element of the compositeAudio array
"audioSynthesisDynamicValues": { // An array of dynamic values
"NA": "Autodialer number: name",
"NO": "Autodialer number: note",
"LI": "Autodialer number: data for Web Dialer",
"P1": "Autodialer number: parameter #1",
"P2": "Autodialer number: parameter #2",
"P3": "Autodialer number: parameter #3",
"P4": "Autodialer number: parameter #4",
"P5": "Autodialer number: parameter #5",
"P6": "Autodialer number: parameter #6",
"P7": "Autodialer number: parameter #7",
"P8": "Autodialer number: parameter #8",
"P9": "Autodialer number: parameter #9",
"P10": "Autodialer number: parameter #10"
},
"withdrawalCategories": { // An array of autodialer withdrawal categories
"CALL": "Making calls",
"AUTODIALER": "Autodialer",
"VOICE_SECRETARY": "Voice secretary",
"TEXT_TO_SPEECH": "Speech synthesis",
"SPEECH_RECOGNITION": "Speech recognition",
"VOICE_ANALYTICS": "Speech analytics",
"ANSWERING_MACHINE_DETECTION": "Answering machine detection",
"MESSAGE_SERVICE_MESSAGE": "Sending messages"
},
"tasks": [ // List of all autodialers
{
"id": 12345, // Autodialer ID
"name": "Обзвон окна", // Autodiler name
"autodialerType": "AUTODIAL", // Autodialer type
"autodialerMode": "FIXED", // Autodialer mode
"statistics": { // Autodialer number statistics
"totalCount": 10, // Total numbers count
"doneCount": 6, // Numbers processed
"repeatCount": 2 // Repeated calls
"callsDoneCount": // Number of completed calls
"statesCount": { // Number statistics by status
"NEW": 3, // "ID": Count
...
}
},
"finishedDate": "2020-04-21", // Autodialer finish date. Present only for autodialers in FINISHED status
"threadCount": 1, // Number of simultaneous calls. Present only for autodialers in FIXED mode
"delay": 2, // Pause between the end of audio playback and the start of the scenarion, in seconds. Present only for autodialers with AUTODIAL type
"smartSpeed": 0, // Autodialer speed control. Present only for autodialers in SMART mode
"coldBaseStartCallsMultiplier": null, // If not null, changes the number of simultaneous calls depending on the dial percentage with the specified coefficient. Present only for autodialers in FREE and SMART modes
"callDelay": 0, // Pause between calls in seconds. Present only for autodialers in FIXED mode and is only taken into account when the number of threads is 1
"callDelayOnlyAnswered": true, // The pause between calls will work only after calls answered by the operator. Present only for autodialers in FIXED mode
"compositeAudio": { // Contains information about compiste audio played when the client answers the call. Present only for autodialers with AUTODIAL type
"multiAudios": [ // List of audio parts
{
"silenceMillis": 500 // Duration of silence in miliseconds
},
{
"id": 46615 // Id of project's audio
},
{
"synthesisFromDynamicValue": { // Data for speech synthesis
"dynamicValue": "NO", // Dynamic value whose value will be synthesized
"settingsId": 117 // Speech synthesis settings profile ID, which will be used instead of the one specified in the autodialer settings. May be null
}
}
]
},
"moh": 53, // ID of the audio that the client will hear while waiting for a connection with the operator. May be null. Present only for autodialers with GUARANTEED_DIAL type
"startDate": "2020-03-15", // Autodialer period start date (inclusive)
"endDate": "2020-05-15", // Autodialer period end date (inclusive)
"timeFrom": [ // Autodialing start time by day of the week in "HH:mm" format
"09:00", // Monday
"11:00", // Tuesday
"11:00", // Wednesday
"11:00", // Thursday
"11:00", // Friday
null, // Saturday, null - autodialer on this day does not work
"14:00" // Sunday
],
"timeTo": [ // Autodialing end time by day of the week
"19:00",
"19:00",
"19:00",
"19:00",
"19:00",
null,
"17:00"
],
"voiceSecretaryId": 25 // ID of the voice secretary. Present only for autodialers with VOICE_ROBOT type
"groupId": 300, // ID of the telephony department to which autodialer calls will be redirected. Present only for autodialers with GUARANTEED_DIAL type or in FREE and SMART modes
"pseudoGroupOperators": [
"1000", ...
] // SIPs of the telephony to which autodialer calls will be redirected. If the parametr "groupId" is used, these params will be skipped.
"scenarioId": null, // The ID of the incoming scenario that will be activated if the client stays on the line after the audio ends. May be null. Present only for autodialers with AUTODIAL type
"outScenarioId": null, // The ID of the outgoing scenario that will be used for autodialer calls. May be null.
"pauseOperatorNoAnswerLimit": 5, // The number of calls in a row not answered by the operator, after which he will be paused. May be null. Present only for autodialers in FREE and SMART modes
"ttsSettingsId": 18, // ID of the speech synthesis settings profile. May be null. Present only for autodialers with AUTODIAL or GUARANTEED_DIAL type
"useTaskAudioIfAudioError": false, // On audio error: true - “Use autodialer audio”, false - “End call with error”. Present only for autodialers with AUTODIAL or GUARANTEED_DIAL type
"repeatCallsSettings": { // Repeat call settings. Can be null
"earlyStart": true, // Responsible for early repeat calling. If false, or if the campaign contains more than 1,000,000 numbers, repeat calls will only start once all unprocessed numbers are finished
"highPriority": true, // Indicates whether repeat calls should be placed into the priority queue
"statesSettings": { // Array of call statuses that will be subject to repeat calling. Can be empty or null if repeatCallAttempts is null
"ANSWER": {
"attempts": 2, // Number of repeat call attempts. Allowed values: 0–10. Values 0 or null disable repeat calling
"intervalMinutes": 15, // Minimum interval between repeat calls, in minutes. Allowed values: 5–1500
"secondsThreshold": 20 // Call again if the conversation lasted less than this number of seconds
},
"NOANSWER": {
"attempts": 30, // Number of repeat call attempts. Allowed values: 0–10. Values 0 or null disable repeat calling
"intervalMinutes": 60 // Minimum interval between repeat calls, in minutes. Allowed values: 5–1500
},
...
}
},
"repeatCallAttempts": 3, // [Deprecated] Number of repeated calls. Values 0 and null mean that re-call is disabled
"repeatCallIntervalMinutes": 30, // [Deprecated] The minimum interval of repeated calls in minutes
"repeatCallHighPriority": false, // [Deprecated] True value indicates that repeated calls should be added to the priority queue
"repeatCallStates": [ // [Deprecated] List of call states that will be called repeatedly. May be empty or null if repeatCallAttempts is 0 or null
"NOANSWER",
...
],
"repeatCallEarly": true, // [Deprecated] True value indicates that repeat call starting early
"callerIdPrefix": null, // The prefix that will be displayed in the SIP client before the phone number. May be null
"crmMode": "DONT_SEND", // Defines which calls will be sent to CRM
"clientCalledMode": "NEVER", // Indicates the need to ignore the numbers of subscribers from whom calls were received
"displayName": false, // Indicates the need to show a name assigned to the number in the SIP client
"displayNote": false, // Indicates the need to show a note assigned to the number in the SIP client
"removeAfterFinish": false, // Indicates the need to delete the autodialer after completion
"markAsBusySeconds": 60, // The number of seconds for which the SIP line is marked busy after a successful call. Present only for autodialers in FREE and SMART modes
"markAsBusyMinSecondsTalk": 15, // Minimum call duration for triggering the markAsBusySeconds setting in seconds. Present only for autodialers in FREE and SMART modes
"reservedSipsBusyOnlyForAutodials": true, // Indicates that inner lines are available for calls from incoming scenarios. Present only for autodialers in FREE and SMART modes
"triggerActions": { // List of events and handlers assigned to them.
"AUTODIAL_NOANSWER": [ // Event
2, // Event handler ID
...
],
...
},
"withdrawalStatistics": { // An array with information about summarized adutodialer's withdrawal
"total": "12.47", // Sum of withdrawals of all categories
"byCategories": { // An array of withdrawal sums by categories
"CALL": "0.60",
...
}
},
"taskStatusInfo": { // Aurodialer status information
"millis": 1631828328839,
"status": "FINISHED",
"dateForDescription": "2021-09-08",
"durationMillis": 36253180657
}
},
...
],
"statesInfo": [ // Autodialer call states information
{
"state": "NEW", // State ID
"order": 10, // Ordinal number
"title": "Не обработано", // State's title
"repeatable": false, // Available for automatic repeat calling (field repeatCallStates)
"refreshable": false, // Available for REFRESH method
"warning": false // Indicates possible problems in the autodialer or telephony settings
},
...
]
}
Creating and updating autodialers
Сopied
The “Add” and “Update” actions allow you to configure a new or existing autodialer respectively. Some parameters are common to all types and modes of autodialers. Creating and updating autodialers will be discused using one request as the example, since the differences are minor: ·id – The unique identifier of the autodialer being changed is not taken into account when creating ·autodialerType – The autodialer type is not taken into account when changing · When creating an autodialer, you can optionally pass a list of numbers to be processed in the numbers parameter and indicate the need to process them in the priority queue in the highPriority parameter. Numbers in the numbers array must be specified in international format; all third-party characters will be previously removed. To add numbers to an existing autodialer, use the ADD_NUMBERS action.
crmMode determines information about which calls will be transferred to CRM. Available values: ·DONT_SEND – None ·SEND_ANSWERED – Answered by subscriber ·SEND_SUCCESS – Answered by subscriber and operator ·ALL_CALLS – All
clientCalledMode indicates the need to ignore the numbers of subscribers from whom calls were received. Available values: ·NEVER – Never ·ANSWERED_CALLS – Only if the call is answered ·ALL_CALLS – Always
An example of common part of request JSON:
{
"action": "ADD", // Or "UPDATE"
"task": {
"id": 0, // ID of the existing autodialer for "UPDATE". Ignored on "ADD"
"name": "Обзвон", // Must be unique
"autodialerType": "AUTODIAL", // Autodialer type. Ignored on "UPDATE"
"autodialerMode": "FIXED", // Autodialer mode
"startDate": "2020-03-15", // Autodialer period start date (inclusive)
"endDate": "2020-05-15", // Autodialer period end date (inclusive)
"timeFrom": [ // Autodialing start time by day of the week in "HH:mm" format
"09:00", // Monday
"11:00", // Tuesday
"11:00", // Wednesday
"11:00", // Thursday
"11:00", // Friday
null, // Saturday, null - autodialer on this day does not work
"14:00" // Sunday
],
"timeTo": [ // Autodialing end time by day of the week
"19:00",
"19:00",
"19:00",
"19:00",
"19:00",
null,
"17:00"
],
"outScenarioId": null, // The ID of the outgoing scenario that will be used for autodialer calls. May be null.
"triggerActions": { // List of events and handlers assigned to them. A maximum of 5 handlers can be attached to one event
"AUTODIAL_NOANSWER": [ // Event
2, // Event handler ID
...
],
...
},
"repeatCallsSettings": { // Repeat call settings. Can be null
"earlyStart": true, // Responsible for early repeat calling. If false, or if the campaign contains more than 1,000,000 numbers, repeat calls will only start once all unprocessed numbers are finished
"highPriority": true, // Indicates whether repeat calls should be placed into the priority queue
"statesSettings": { // Array of call statuses that will be subject to repeat calling. Can be empty or null if repeatCallAttempts is null
"ANSWER": {
"attempts": 2, // Number of repeat call attempts. Allowed values: 0–10. Values 0 or null disable repeat calling
"intervalMinutes": 15, // Minimum interval between repeat calls, in minutes. Allowed values: 5–1500
"secondsThreshold": 20 // Call again if the conversation lasted less than this number of seconds
},
"NOANSWER": {
"attempts": 30, // Number of repeat call attempts. Allowed values: 0–10. Values 0 or null disable repeat calling
"intervalMinutes": 60 // Minimum interval between repeat calls, in minutes. Allowed values: 5–1500
},
...
}
},
"callerIdPrefix": null, // The prefix that will be displayed in the SIP client before the phone number. May be null
"crmMode": "DONT_SEND", // Defines which calls will be sent to CRM
"clientCalledMode": "NEVER", // Indicates the need to ignore the numbers of subscribers from whom calls were received
"displayName": false, // Indicates the need to show a name assigned to the number in the SIP client
"displayNote": false, // Indicates the need to show a note assigned to the number in the SIP client
"removeAfterFinish": false, // Indicates the need to delete the autodialer after completion
"numbers": [ // A list of numbers for autodialer. Ignored on "UPDATE". May be null
"+38(097)11-11 111",
...
],
"highPriority": true // Indicates the need to add numbers as high priority. These numbers are called first. Ignored on "UPDATE"
...
}
}
The type of autodialer being created or modified affects the list of required and allowed parametes, which will be discussed separately.
For calls with the AUTODIAL type, one of the compositeAudio and scenarioId parameters must be present. The compositeAudio parameter must contain a multiAudios object which is a list that is used to specify the audio. Each element of the multiAudios list represents a reference to an audio recording in the project (id), silence (silenceMillis) or audio synthesis (synthesisFromDynamicValue). Audio synthesis must contain a dynamicValue parameter, the value of which corresponds to one of the keys of the corresponding dictionary. The order of audio in the list corresponds to the playback order. For correct audio synthesis, it is necessary to have one of the parameters settingsId of the synthesis part and ttsSettingsId of the autodialer.
An example of specific for AUTODIALER type part of request JSON:
...
"scenarioId": 70, // The ID of the incoming scenario that will be activated if the client stays on the line after the audio ends
"compositeAudio": { // Contains information about compiste audio played when the client answers the call
"multiAudios": [ // List of audio parts
{
"silenceMillis": 500 // Duration of silence in miliseconds
},
{
"id": 46615 // Id of project's audio
},
{
"synthesisFromDynamicValue": { // Data for speech synthesis
"dynamicValue": "NO", // Dynamic value whose value will be synthesized
"settingsId": 117 // Speech synthesis settings profile ID, which will be used instead of the one specified in the autodialer settings. May be null
}
}
]
},
"ttsSettingsId": 18, // ID of the speech synthesis settings profile. May be null
"useTaskAudioIfAudioError": false, // On audio error: true - “Use autodialer audio”, false - “End call with error”
"delay": 2, // Pause between the end of audio playback and the start of the scenarion, in seconds. May be 0
...
For autodialers with GUARANTEED_DIAL type, group of internal lines must be specified in groupId parameter or pseudoGroupOperators parameter.
An example of specific for GUARANTEED_DIAL type part of request JSON:
...
"moh": 53, // ID of the audio that the client will hear while waiting for a connection with the operator. May be null
"groupId": 300, // ID of the telephony department to which autodialer calls will be redirected
"pseudoGroupOperators" : ["1000", ... ] // SIPs of the telephony to which autodialer calls will be redirected. If the parametr "groupId" is used, these params will be skipped.
"ttsSettingsId": 18, // ID of the speech synthesis settings profile. May be null
"useTaskAudioIfAudioError": false, // On audio error: true - “Use autodialer audio”, false - “End call with error”
...
For autodialers with VOICE_ROBOT type, voice secretary must be specified in voiceSecretaryId parameter.
An example of specific for VOICE_ROBOT type part of request JSON:
...
"voiceSecretaryId": 25 // Voice secretary ID
...
The mode of autodialer being created or modified affects the list of required and allowed parametes, which will be discussed separately.
For autodialers in FIXED mode, number of simultanious calls (threads) must be specified in threadCount parameter.
An example of specific for FIXED mode part of request JSON:
...
"threadCount": 1, // Number of simultaneous calls
"callDelay": 0, // Pause between calls in seconds. Only taken into account when the number of threads is 1
"callDelayOnlyAnswered": true, // The pause between calls will work only after calls answered by the operator
...
For autodialers in FREE mode, group of internal lines must be specified in groupId parameter or pseudoGroupOperators parameter. Also, additional options are available: ·coldBaseStartCallsMultiplier – Changes the number of simultaneous calls depending on the percentage of dialing with the specified coefficient. Available values from 0.1 to 1.5 ·pauseOperatorNoAnswerLimit – The number of calls in a row not answered by the operator, after which it will be paused ·markAsBusySeconds – The number of seconds for which the SIP line is marked busy after a successful call. Available values from 0 to 3600 ·markAsBusyMinSecondsTalk – Minimum call duration for triggering the markAsBusySeconds setting in seconds. Available values from 0 to 3600 ·reservedSipsBusyOnlyForAutodials – Controls whether inner lines are available for calls from incoming scenarios
An exmaple of scpecific for FREE mode part of request JSON:
...
"groupId": 300, // ID of the telephony department to which autodialer calls will be redirected
"pseudoGroupOperators" : ["1000", ... ] // SIPs of the telephony to which autodialer calls will be redirected. If the parametr "groupId" is used, these params will be skipped.
"coldBaseStartCallsMultiplier": null, // If not null, changes the number of simultaneous calls depending on the dial percentage with the specified coefficient
"pauseOperatorNoAnswerLimit": 5, // The number of calls in a row not answered by the operator, after which he will be paused. May be null
"markAsBusySeconds": 60, // The number of seconds for which the SIP line is marked busy after a successful call
"markAsBusyMinSecondsTalk": 15, // Minimum call duration for triggering the markAsBusySeconds setting in seconds
"reservedSipsBusyOnlyForAutodials": true, // Indicates that inner lines are available for calls from incoming scenarios
...
For autodialers in SMART mode, group of internal lines must be specified in groupId parameter or pseudoGroupOperators parameter. Also, additional options are available: ·coldBaseStartCallsMultiplier – Changes the number of simultaneous calls depending on the percentage of dialing with the specified coefficient. Available values from 0.1 to 1.5 ·pauseOperatorNoAnswerLimit – The number of calls in a row not answered by the operator, after which it will be paused ·markAsBusySeconds – The number of seconds for which the SIP line is marked busy after a successful call. Available values from 0 to 3600 ·markAsBusyMinSecondsTalk – Minimum call duration for triggering the markAsBusySeconds setting in seconds. Available values from 0 to 3600 ·reservedSipsBusyOnlyForAutodials – Controls whether inner lines are available for calls from incoming scenarios ·smartSpeed – Autodialer speed control. Available values from 0 от -10 to 10 proportionaly affects dialing speed
An exmaple of scpecific for SMART mode part of request JSON:
...
"groupId": 300, // ID of the telephony department to which autodialer calls will be redirected
"pseudoGroupOperators" : ["1000", ... ] // SIPs of the telephony to which autodialer calls will be redirected. If the parametr "groupId" is used, these params will be skipped.
"coldBaseStartCallsMultiplier": null, // If not null, changes the number of simultaneous calls depending on the dial percentage with the specified coefficient
"pauseOperatorNoAnswerLimit": 5, // The number of calls in a row not answered by the operator, after which he will be paused. May be null
"markAsBusySeconds": 60, // The number of seconds for which the SIP line is marked busy after a successful call
"markAsBusyMinSecondsTalk": 15, // Minimum call duration for triggering the markAsBusySeconds setting in seconds
"reservedSipsBusyOnlyForAutodials": true, // Indicates that inner lines are available for calls from incoming scenarios
"smartSpeed": 0, // Autodialer speed control
...
An example of response in case of success:
{"status": "Success", "data": 12345}
When performing the ADD action, the idof the created autodilaer is transferred to the datafield.
Possible errors:
task is null
Parameter taskis not specified in the request
Please confirm phone number
Unverified projects cannot create autodialers
Billing not allow
Autodialers are not available on this tariff, or the tariff has not been paid
Task not found
Autodialer not found by idduring UPDATE
groupId and pseudoGroupOperators is null
Autodialer’s type is GUARANTEED_DIAL or mode is FREE or SMART, but groupId parameter or pseudoGroupOperators parameter is not specified in the request
Operator not found: …
In pseudoGroupOperators parameter used invalid SIP lines
Group not found
Autodialer’s type is GUARANTEED_DIAL or mode is FREE or SMART, but group of internal lines was not foud by specified id
Wrong group type
Autodialer’s type is GUARANTEED_DIALor mode is FREEor SMART, but specified group is not a group of internal lines
Moh not found
Autodialer’s type is GUARANTEED_DIAL, but melody of waiting on the line was not foud by specified id
Wrong audio type: moh
Autodialer’s type is GUARANTEED_DIAL, but audio of another section was found by specified id
In scenario not found
Autodialer’s type is AUTODIAL, but incoming scenario was not found by specified id
Not found in scenario and audio
Autodialer’s type is AUTODIAL, but neither audio nor incoming scenario is specified in the request
voiceSecretaryId is null
Autodialer’s type is VOICE_ROBOT, but voice secretary is not specified in the request
Voice secretary not found
Autodialer’s type is VOICE_ROBOT, but voice secretary was not foud by specified id
compositeAudio
Error when specifying composite audio in autodialers with AUTODIAL type. Possible reasons: ·too many audio parts – composite audio contains more than 20 parts ·audio not found – audio was not foud by specified id ·audio type is not AUTODIAL – audio of another section was found by specified id ·synthesis dynamicValue is null – dynamicValue parameter is not specified in the speech synthesis element ·speech synthesis settings not found – speech synthesis setings profile was not foud by specified settingsId ·invalid silenceMillis – silenceMillis value is not in range from 1 to 10 000
Wrong name
Name cannot be empty or longer than 45 characters
Name already present
An autodialer with this name already exists in the project
Not found out scenario
Outgoing scenarion was not foud by specified id
Wrong dates
The call dates are not specified, or the start date of the call exceeds the end date
Wrong time ranges
The timeFromor timeToarray does not have 7 elements, any timeFrompair is later than timeToor all elements are null
Prefix is too long
The prefix must not exceed 20 characters
Handler is busy, try again later
One project can simultaneously delete or add numbers in only one autodialer. At this moment, numbers are deleted or added in one of the project autodialers. Please try again later when the previous operation completes. Can only occur if the numbers numbers is specified during an ADD action
Wrong numbers
The numbersarray contains incorrect numbers. The datafield will contain an array of numbers elements that did not pass validation
Repeat call states is empty
repeatCallAttemptsindicates the need for automatic re-call, but repeatCallStates is empty or null
Repeat call state is not allowed
An invalid callState was passed in the repeatCallStatesarray
Not found text to speech settings
speech synthesis setings profile was not foud by specified id
Wrong trigger action event
An invalid triggerActionEvent was passed in the triggerActionsarray
triggerActionIds is null
Null triggerActionEventwas passed in the triggerActionsarray
Too many trigger actions
An array with more than 5 handlers is passed in the triggerActionsarray for one of the triggerActionEvent
Trigger action not found
No handler was found for one of the idspecified in triggerActions
Few trigger actions with same type
In the triggerActionsarray, one of the triggerActionEventcontains 2 event handlers with the same action type
Not compatible trigger action
In the triggerActionsarray, one of the triggerActionEventcontains an event handler idthat is incompatible with this triggerActionEvent
crmMode is null
The crmMode field is not specified in the request
clientCalledMode is null
The clientCalledMode field is not specified in the request
Tasks limit exceeded
The maximum number of autodiales in the project has been exceeded
Autodialer removal
Сopied
Request JSON example:
{
"id": 1307, // Targe autodialer ID
"action": "REMOVE"
}
Response in case of success:
{"status": "Success", "message": "Removed"}
Possible errors:
Task not found
Autodialer was not found by specified id
Handler is busy, try again later
One project can simultaneously delete or add numbers in only one autodialer. At this moment, numbers are deleted or added in one of the project autodialers. Please try again later when the previous operation completes.
Re-call numbers
Сopied
The “Re-call numbers” action allows you to restart the processing of numbers in the specified statuses. The list of valid statuses for use in this action is given in the corresponding dictionary.
Request JSON example:
{
"id": 1307, // Target autodialer ID
"action": "REFRESH",
"callStates": [ // A list of statuses numbers in which will be called again
"NOANSWER",
...
]
}
Response in case of success:
{"status": "Success"}
Successful completion of this action will change the status of the selected numbers to NEW.
Possible errors:
Task not found
Autodialer was not found by specified id
states is null or empty
callStates list is empty or null
state is not allowed
The callStates array contains a status that is not valid for REFRESH
Try again later
The previous action for the specified autodialer occurred less than a minute ago
Numbers not found by states
No numbers with the specified statuses were found
Autodialer cancellation
Сopied
The “Cancel autodialer” action allows you to stop a call that is in the WAITING, IN_PROGRESS or PAUSED status. Applying this action to calls with FINISHED and CANCELED statuses will result in an error. Applying to NEW will not cause any changes.
Request JSON example:
{
"id": 1307, // Target autodialer ID
"action": "CANCEL"
}
Response in case of success:
{"status": "Success", "message": "Cancelled"}
A successful cancellation will change the status to CANCELED (while there are pending calls in the autodialer), subsequently the status will change to FINISHED
Possible errors:
Task not found
Autodialer was not found by specified id
Task is finished
It is impossible to cancel an autodialer with the FINISHED status
Task is canceled
It is impossible to cancel an autodialer with the CANCELED status
Pausing
Сopied
The “Pause” action allows you to pause an autodialer that is in the WAITING or IN_PROGRESS status. Applying this action to calls with FINISHED and CANCELED statuses will result in an error. Applying to NEW or PAUSED will not lead to any changes.
Request JSON example:
{
"id": 1307, // Target autodialer ID
"action": "PAUSE"
}
Response in case of success:
{"status": "Success"}
A successful pause will change the status from WAITING or IN_PROGRESS to PAUSED.
Possible errors:
Task not found
Autodialer was not found by specified id
Task is finished
It is impossible to pause an autodialer with the FINISHED status
Task is canceled
It is impossible to pause an autodialer with the CANCELED status
Unpausing
Сopied
The “Unpause” action allows you to continue an autodialer that is in PAUSED status. Applying this action to calls with FINISHED and CANCELED statuses will result in an error. Applying to NEW, WAITING or IN_PROGRESS will not result in any changes.
Request JSON example:
{
"id": 1307, // Target autodialer ID
"action": "UNPAUSE"
}
Response in case of success:
{"status": "Success"}
Successfully unpausing will change the status from PAUSED to WAITING or IN_PROGRESS.
Possible errors:
Task not found
Autodialer was not found by specified id
Task is finished
It is impossible to unpause an autodialer with the FINISHED status
Task is canceled
It is impossible to unpause an autodialer with the CANCELED status
Adding numbers
Сopied
The “Add numbers” action allows you to add numbers to the autodialer in two ways: by specifying only numbers in the numbers array or numbers with additional information in the numbersWithData array. If both are specified, numbers from both arrays will be added. It is possible to add up to 100,000 numbers per request, but no more than 1,000,000 numbers per autodialer.
The request must contain one of the numbers and numbersWithData parameters. Numbers in the numbers array or the phone parameter must be specified in international format; all third-party characters will be previously removed. The numbersWithData array allows you to pass numbers as elements with additional parameters; the only required parameter is phone.
The audios parameter is an array that is used to specify the audio that will be played instead of the main autodialer audio. Each element of the audios array represents a link to an audio in the project (id) or audio synthesis (tts). The element must contain one of the id and tts parameters; if both are specified, id will be used. The order of audio in the array corresponds to the order of playback. For the AUTODIAL autodialer type, the maximum number of elements is 5 (of which 2 are audio synthesis), for GUARANTEED_DIAL – 1, for VOICE_ROBOT the parameter is ignored.
For the AUTODIAL autodialer type, the id must point to an audio from the “Autodialers” section, for GUARANTEED_DIAL – “Waiting melodies”. The tts element must contain one of the text and ssml parameters; if both are specified, ssml will be used, the maximum number of characters is 2500. The ssml parameter must begin and end with the speak tag. The synthesis process occurs before the start of the call. Synthesized audio is stored for up to 7 days after the end of the autodialer, no more than 3 months from the moment of creation, and is not displayed in the list of project audios. If the synthesized text and the settings profile match, the previously synthesized audio is used.
Request JSON example:
{
"id": 1307, // Target autodialer ID
"action": "ADD_NUMBERS",
"refreshDuplicates": true, // Indicates the need to reprocess numbers that are already in the autodialer
"highPriority": true, // Indicates that the added numbers should be processed first
"numbers": [ // Array of numbers to be added
"380970000001",
...
],
"numbersWithData": [ // An array of numbers with additional information to be added
{
"phone": "380670000002",
"name": "sample_name", // Name. The first 100 characters are taken into account. May be null
"note": "sample_note", // Note. The first 500 characters are taken into account. May be null
"link": "https://...", // Data for Web Dialer. The first 500 characters are taken into account. May be null
"params": { // Parameters that will be assigned to the number in the autodialer. May be null
"1": "sample_value", // Parameter number (1-10): Parameter value. The first 500 characters are taken into account. May be null
...
},
"audios": [ // An array of audios and audio synthesis that will be played when calling a number instead of the main autodialer audio. May be null
{
"id": 4953, // Target audio ID
},
{
"tts": { // Audio synthesis data
"text": "sample_text", // Text to be synthesized
"ssml": "<speak>sample_text</speak>", // Text to be synthesized in ssml format
"settingsId": 18 // ID of the audio synthesis settings profile that will be used instead of the one specified in the autodialer settings. May be null
}
},
...
]
},
...
]
}
An example of response in case of success:
{"status": "Success", "message": "Numbers added"}
Successfully adding numbers to a completed autodialer (FINISHED) will change the status to WAITING or IN_PROGRESS.
Possible errors:
Task not found
Autodialer was not found by specified id
Numbers is null or empty
numbers and numbersWithDataare empty or null
Too many numbers
The limit of 100,000 numbers per action has been exceeded
Numbers limit exceeded
The limit of 1,000,000 numbers in the autodialer has been exceeded
Handler is busy, try again later
One project can simultaneously delete or add numbers in only one autodialer. At this moment, numbers are deleted or added in one of the project autodialers. Please try again later when the previous operation completes.
Wrong numbers
The numbersarray contains incorrect numbers. The datafield will contain an array of numbers elements that did not pass validation
Numbers not added
No numbers were added
Wrong audios
The numbersWithDataarray contains numbers with invalid audios. The data field will contain an array of numbers with the corresponding audio error. Possible reasons of the error: · Too many audios – too many elements · Too many text to speech – too many elements with audio synthesis · Audio is null – there are elements with the null value · Audio not found by id – there are id for which the audio was not found · Wrong type of audio – there are id that coresponds to the audio of an invalid section · Text to speech ‘text’ and ‘ssml’ is null – there are tts in which both text and ssml are empty · Text to speech ‘text’ not valid – there are tts in which the text exceeds 2500 characters · Text to speech ‘ssml’ not valid – there are tts in which ssml exceeds 2500 characters or does not begin and end with the speak tag · Text to speech settings not found by id – there are ttsin which the audio synthesis settings profile was not found according to the specified settingsId · Audio is empty – there are elements in which both ttsand idare null
Too many params
More than 10 parameters were passed to params
Wrong parameter key
params contains a key that is not a number from 1 to 10
Obtaining information about the autodialer number
Сopied
Request JSON example:
{
"id": 1307, // Target autodialer ID
"action": "GET_NUMBER",
"number": "380971234567" // Phone number
}
An example of response in case of success:
{
"taskId": 18700, // Autodialer ID
"phone": "380441234567", // Phone number
"state": "ANSWER", // Status of the last call made to this number
"stateDateTime": "2020-09-10 05:47:15" // The end date of the last autodialer call to this number
"calledCount": 0, // Number of calls to this number since the last autodialer start
"realCalledCount": 0, // Number of calls to this number in the autodialer
"highPriority": false, // Indicates whether the number is in the priority queue
"name": "sample_name", // Name assigned to the number in the autodialer
"note": "sample_note", // Note assigned to the number in the autodialer
"link": "https://...", // Web Dialer data assigned to the number in the autodialer
"params": { // Parameters that will be assigned to the number in the autodialer
"1": "sample_value", // Parameter number (1-10): Parameter value
...
},
"audios": [ // Audios assigned to the number in the autodialer
{
"id": 46644 // Audio ID
},
{
"tts": { // Speech synthesis parameters
"text": "sample_text",
"settingsId": 107
}
}
]
}
Possible errors:
Task not found
An autodialer was not found by the specified id
Wrong phone number
Phone number is invalid
Call not found
Number not found in the autodialer
Obtaining information about all autodialer numbers
Сopied
To obtain information about all autodialer numbers, you must specify the id of the target autodialer. The number of records that will be received does not exceed the value of the limit parameter. By default, limit is 1000, the maximum value is 5000. To obtain the next group of records, you must specify a shift relative to the beginning of the list in the offest parameter. In addition, records can be pre-filtered by target number statuses, a list of which is given in the corresponding dictionary.
Request JSON example:
{
"id": 1307, // Target autodialer ID
"action": "GET_NUMBERS",
"limit": 2000, // Maximum number of numbers that will be returned in the response
"offset": 4000, // Shift of returned records relative to the beginning of the list
"callStates": [ // Filter by callState. Can be null or empty
"NOANSWER",
...
]
}
An example of response in case of success:
[ // An array of autodialer numbers with additional information
{
"taskId": 18700, // Autodialer ID
"phone": "380441234567", // Phone number
"state": "ANSWER", // Status of the last call made to this number
"stateDateTime": "2020-09-10 05:47:15" // The end date of the last autodialer call to this number
"calledCount": 0, // Number of calls to this number since the last autodialer start
"realCalledCount": 0, // Number of calls to this number in the autodialer
"highPriority": false, // Indicates whether the number is in the priority queue
"name": "sample_name", // Name assigned to the number in the autodialer
"note": "sample_note", // Note assigned to the number in the autodialer
"link": "https://...", // Web Dialer data assigned to the number in the autodialer
"params": { // Parameters that will be assigned to the number in the autodialer
"1": "sample_value", // Parameter number (1-10): Parameter value
...
},
"audios": [ // Audios assigned to the number in the autodialer
{
"id": 46644 // Audio ID
},
{
"tts": { // Speech synthesis parameters
"text": "sample_text",
"settingsId": 107
}
}
]
},
...
]
Possible errors:
Task not found
An autodialer was not found by the specified id
Limit range is 1-5000
The limit value is not in the range from 1 to 5000
Offset cannot be negative
offset must be positive
Obtaining information about autodialer calls
Сopied
To obtain information about autodialer calls, in addition to the action, you must specify id of target autodialer and the callHistoryRequest parameter. callHistoryRequest cannot be null, but can be empty. Records are returned in descending order by id.
The number of records that will be received does not exceed the value of the limit parameter. By default, limit is 50, the maximum value is 1000. To obtain the next group of records, you can use one of two methods: · In the offest parameter, specify the offset relative to the beginning of the list; · In the maxId parameter, specify the maximum (inclusive) id of the record that will be returned.
Call records can be pre-filtered using the following parameters: ·dateFrom – minimum date and time of the call (inclusive) in the “yyyy-MM-dd HH:mm:ss” format; ·dateTo – maximum date and time of the call (not inclusive) in the “yyyy-MM-dd HH:mm:ss” format.
In addition, records can be pre-filtered in the filter parameter by: ·states – an array of autodialer call statuses. The list is given in the corresponding dictionary; ·phone – part of the subscriber’s number. All third-party characters will be previously removed; ·operatorNumber – exact operator number. All third-party characters will be previously removed; ·name – part of the name assigned to the autodialer number at the time of the call; ·note – part of the note assigned to the autodialer number at the time of the call; ·link – part of the data for Web Dialer assigned to the autodialer number at the time of the call; ·param – part of any of the parameters assigned to the autodialer number at the time of the call; ·voiceSecretaryIds – an array of voice secretaries id that were used in the call; ·voiceSecretaryEndReasons – an array of reasons for ending the voice secretary that was used in the call. The list is given in the corresponding dictionary; ·voiceSecretaryEndNodeTypes – an array of voice secretary end node types that was used in the call. The list is given in the corresponding dictionary.
Request JSON example:
{
"action": "GET_CALLS_HISTORY",
"id": 300, // Required parameter. Target autodialer identifier
"callHistoryRequest": { // Required parameter. All internal parameters can be null
"dateFrom": "2023-10-24 00:00:00", // Minimum call date and time
"dateTo": "2023-10-25 00:00:00", // Maximum call date and time
"offset": 0, // Shift relative to the start of the sample
"limit": 50, // Maximum number of calls that will be returned in response
"maxId": 150, // Maximum call ID
"filter": { // An array of additional filters. All internal parameters can be null
"states": [ // Array of target call statuses
"ANSWER",
...
],
"phone": "38097", // Part of the numbers
"operatorNumber": "2045", // Target operator line number
"name": "part of name", // Part of the name
"note": "part of note", // Part of a note
"link": "part of data for webdialer ", // Part of data for WebDialer
"param": "part of param", // Part of one of the parameters
"voiceSecretaryIds": [ // Array of target voice assistant identifiers
"118",
...
],
"voiceSecretaryEndNodeTypes": [ // Array of target voice assistant end node types
"END_SUCCESS",
...
],
"voiceSecretaryEndReasons": [ // Array of target reasons for voice secretary termination
"NORMAL",
...
]
}
}
}
An example of response in case of success:
{
"count": 140, // Number of matching results
"offset": 0, // Shift used
"limit": 50, // Limit used
"items": [ // Array of autodialer calls
{
"id": 158, // Call ID
"phone": "380681234567", // Phone number
"state": "ANSWER", // Call end status
"callEndTime": "2023-10-24 16:15:43", // Call end date and time
"operatorNumber": "2045", // Operator number. May be null
"userId": 15, // Operator ID. May be null
"calledCount": 1, // Number of call attempts
"realCalledCount": 2, // Total call attempts
"seconds": 3, // Charged call time. May be null
"secondsForClientAnswered": 16, // Waiting time until the client answers the call. May be null
"secondsDialToClient": 16, // Dialing time untill the client answers or reject the call. May be null if the call was failed by system (in sense of the call hasn`t been started)
"secondsClientWaitOperator": 5, // Operator waiting time. May be null
"secondsOperatorWaitCall": 15, // Call waiting time. May be null
"secondsForOperatorAnswered": 2, // Time until the operator responds. May be null
"secondsTalk": 10, // Talk time. May be null
"rid": 1052434886, // Random call ID
"name": "some name", // The name to the autodialer number at the time of the call. May be null
"note": "some note", // A note to the autodialer number at the time of the call. May be null
"link": "some data for web dialer", // Data for WebDialer to the autodialer number at the time of the call. May be null
"params": { // An array of parameters for the autodialer number at the time of the call. May be null
"1": "param 1 value", // "Number": "Value"
...
},
"withdrawTotal": "0.65", // Total cost of the call. May be null
"withdrawByCategories": { // An array of charges for a call by category. May be null
"SPEECH_RECOGNITION": "0.10", // Speech recognition
"TEXT_TO_SPEECH": "0.01", // Speech synthesis
"CALL": "0.50", // Making a call
"VOICE_SECRETARY": "0.02", // Voice secretary
"AUTODIALER": "0.02", // Add. cost for an autodialer
"ANSWERING_MACHINE_DETECTION": "0.25" // Answering machine detection
"MESSAGE_SERVICE_MESSAGE": "1" // Sending messages
},
"executedTriggerActionIds": [ // An array of identifiers of the handlers executed by the call. May be null
11,
...
],
"sendFirstMessageToClientSuccess": true, // Indicator of success of sending the first message on a call
"secretary": { // An array of data about the passage of the voice secretary. May be null
"id": 118, // Identifier
"duration": 3, // Duration
"endNodeType": "INTERMEDIATE", // End Node Type
"endReason": "USER_REJECT", // End Reason
"endNodeId": 1, // End Node ID
"endNodeTitle": "Action #1", // End node title
"endVoiceSecretaryId": 118, // End Secretary ID (may be different if end occured in the background)
"steps": [ // An array of information about the secretary's steps
{
"nodeId": 1, // Node ID
"actionTitle": "Action #1", // Node title
"recognizedText": "Some text", // Recognized text. May be null
"recognizedDates": [ // An array of recognized dates. May be null
"2023-10-24",
...
],
"alternativeAudioIndex": "1", // Index of alternative audio that the subscriber listened to. May be null
"jumpToNode": false, // Sign of transition to a node using the action "Go to another node"
"startBackgroundSecretaryId": null, // ID of the background secretary to whom the transition was made. May be null
"endBackgroundSecretaryId": null // ID of the background secretary from which they exited. May be null
},
...
]
}
},
...
]
}
Possible errors:
Task not found
An autodialer was not found by the specified id or id not specified
Limit range is 1-5000
The limit value is not in the range from 1 to 5000
Offset is less than 0
offset must be positive
callHistoryRequest is null
callHistoryRequest parameter not specified
Invalid date from
Incorrect “from” date and time in filters
Invalid date to
Incorrect “to” date and time in filters
Deleting numbers
Сopied
The “Delete numbers” action allows you to remove numbers from the autodialer in two ways: by specifying the numbers or statuses of the numbers to be deleted. The list of required numbers is specified in the numbers request parameter and can contain a maximum of 10,000 numbers. Numbers must be specified in international format; all third-party characters will be previously removed. The statuses of the numbers are specified in the callStates request parameter and are listed in the corresponding dictionary. The request must contain one of the callStates and numbers fields; if both are specified, numbers is used.
Request JSON example:
{
"action": "REMOVE_NUMBERS",
"id": 1307, // Target autodialer ID
"callStates": [ // Array of statuses numbers in which will be deleted
"NOANSWER",
...
],
"numbers": [ // Array of numbers that will be deleted
"380970000001",
...
]
}
An example of response in case of success:
{
"status": "Success",
"data": [ // An array of invalid numbers
"389833883838383838383838",
...
]
}
If at least one number is successfully deleted using the numbers array, the response will contain an array of invalid numbers in the data field.
Possible errors:
Task not found
An autodialer was not found by the specified id
numbers and states is null
Both numbers and callStates fields are null or empty
Too many numbers
The numbersarray contains more than 10,000 numbers
Phones not found
numbers array does not contain any numbers
Numbers not found
None of the numbers in the numbers array were found in the autodialer
Numbers not found by states
Based on the statuses from the callStates array, not a single number was found in the autodialer
Handler is busy, try again later
One project can simultaneously delete or add numbers in only one autodialer. At this moment, numbers are deleted or added in one of the project autodialers. Please try again later when the previous operation completes.
Delete all numbers
Сopied
Request JSON example:
{
"action": "REMOVE_ALL_NUMBERS",
"id": 1307 // Target autodialer ID
}
An example of response in case of success:
{"status": "Success", "message": "Removed"}
Possible errors:
Task not found
An autodialer was not found by the specified id
Numbers not found
There are no numbers in the specified autodialer
Handler is busy, try again later
One project can simultaneously delete or add numbers in only one autodialer. At this moment, numbers are deleted or added in one of the project autodialers. Please try again later when the previous operation completes.
Dictionaries
Сopied
autodialerType
Сopied
Types of autodialers:
AUTODIAL
Autodialer. Used primarily to inform clients or conduct surveys. Autodialer’s calls proceed in accordance with the specified incoming scenario
GUARANTEED_DIAL
Guaranteed autodialer. Used primarily to optimize operators’ working time. Guaranteed autodialer’s calls are distributed directly to operators of the specified group of internal lines
VOICE_ROBOT
Voice robot. Used primarily to inform clients or conduct surveys. The specified voice assistant is reproduced on voice robot’s calls
autodialerMode
Сopied
Modes of autodialers:
FIXED
By the number of threads
FREE
By free operators
SMART
Smart matching
taskStatus
Сopied
Statuses of autofialers:
NO_NUMBERS
No numbers have been added
IN_PROGRESS
Dialling at the moment
WAITING
Waiting for the start of the autodial
WAITING_OPERATORS
Waiting for free operators
WAITING_REPEAT
Waiting for the “Repeat call” setting to be triggered
PAUSED
On pause
CANCELED
Canceled, but not completed yet (some of the call numbers are in DIALING status)
FINISHED
Completed
audioSynthesisDynamicValues
Сopied
Dynamic values for audio synthesis:
NA
Autodialer number: name
NO
Autodialer number: note
LI
Autodialer number: data for Web Dialer
P1
Autodialer number: parameter #1
P2
Autodialer number: parameter #2
P3
Autodialer number: parameter #3
P4
Autodialer number: parameter #4
P5
Autodialer number: parameter #5
P6
Autodialer number: parameter #6
P7
Autodialer number: parameter #7
P8
Autodialer number: parameter #8
P9
Autodialer number: parameter #9
P10
Autodialer number: parameter #10
callState
Сopied
Autodiale’s number states:
State
State name
Available for automatic repeat calling (repeatCallStates field)
Available for REFRESH method
Indicates possible problems in the autodialer or telephony settings
Is call’s state
NEW
Not processed
–
–
–
—
DIALING
In the process of calling
–
–
–
—
ANSWER
Answered by subscriber and operator
–
+
–
+
ANSW_RJCT
Answered by the subscriber and there was no call to the operators
+
+
–
+
NOANSWER
No answer
+
+
–
+
BUSY
Busy or reset
+
+
–
+
FAIL
Connection failure
+
+
–
+
BLOCKED
Blocked
–
+
–
—
TALKING
Answering machine: the caller is talking
+
+
–
+
UNREACHABLE
Answering machine: the caller is unavailable
+
+
–
+
NOT_EXIST
Answering machine: number does not exist
+
+
–
+
VOICE_MAIL
Answering machine: voice mail
+
+
–
+
CLIENT_CALLED
The caller made the call himself or it was an outgoing call
–
+
–
—
CANCEL
Canceled
–
+
–
—
ANSW_NF_OP
Answered by a subscriber and there were no available operators
+
+
+
+
ANSW_OP_NA
Answered by a subscriber and operators did not accept the call
+
+
+
+
BUSYOUT
Not enough lines
+
+
+
+
AUDIO_ERR
Audio error
–
+
+
+
WRONG_DIR
Wrong direction
–
+
+
+
AUTOCANCEL
Canceled automatically
–
+
+
—
triggerActionEvent
Сopied
События обзвонов и звонков обзвонов:
AUTODIAL_ANSWER
Call completed – answered by subscriber and operator
AUTODIAL_ANSW_RJCT
Call completed – answered by the subscriber and there was no call to the operators
AUTODIAL_ANSW_NF_OP
Call completed – answered by a subscriber and there were no available operators
AUTODIAL_ANSW_OP_NA
Call completed – answered by the subscriber and the operators did not accept the call
AUTODIAL_NOANSWER
Call completed – no answer
AUTODIAL_BUSY
Call completed – busy or reset
AUTODIAL_CALL_FAIL
Call completed – connection failure
AUTODIAL_TALKING
Call completed – the caller is talking
AUTODIAL_UNREACHABLE
Call completed – the caller is unavailable
AUTODIAL_NOT_EXIST
Call completed – the number does not exist
AUTODIAL_BUSYOUT
Call completed – not enough lines
AUTODIAL_WRONG_DIR
Call completed – wrong direction
AUTODIAL_AUDIO_ERR
Call completed – audio error
AUTODIAL_NUMBER_BLOCKED
Phone number is blocked by the project settings
AUTODIAL_REPEAT_ATTEMPTS_ENDED
Сall completed unsuccessfully and the number of re-ring attempts has been exceeded
AUTODIAL_CLIENT_CALLED
The caller made the call himself or it was an outgoing call
AUTODIAL_USER_PAUSED
User paused by autodialer. Only available for guaranteed autodial
AUTODIAL_STATUS_CHANGED
Autodialer status changed
AUTODIAL_CANCEL
Autodialer is canceled
AUTODIAL_AUTOCANCEL
Autodialer canceled automatically
AUTODIAL_FINISH
Autodialing completed
voiceSecretaryEndNodeTypes
Сopied
Types of voice assistant end nodes:
INTERMEDIATE
Intermediate
END_SUCCESS
Successful
END_FAIL
Unsuccessful
BACKGROUND
Background
BACKGROUND_DEFER
Background – call transfer
voiceSecretaryEndReasons
Сopied
Reasons for ending voice secretaries:
NORMAL
Ended fine
USER_REJECT
The subscriber ended the call
GREETING_SILENCE
The subscriber was silent during the greeting
ANSWERING_MACHINE
Answering machine recognized
RECOGNITION_ERROR
Speech recognition was interrupted due to technical reasons
JUMP_LIMIT
The limit of completed actions “Move to another node” has been exceeded
NODE_LIMIT
The limit of crossed nodes has been exceeded
FAIL
Unknown error
Calls initiation
Сopied
Direct SIP call -> GSM
Сopied
This method allows you to integrate with your software and, by pressing one button, immediately call the client’s number without having to enter the number manually on the SIP phone. This is commonly used in CRM systems. How it works: call this method — the sip client calls as an incoming call. After the answer, a call immediately goes to the specified number. The main point is that you do not need to enter the number by hand. /phones/directCall Mode: POST Content-Type: application/x-www-form-urlencoded Submit the form with two parameters: String sip— this is the internal line number. String number— gsm number sent in international format. For example: 380504443322. String meta— String for 1000 characters. This is any information that should be displayed in webhooks. May be null.
If successful, example response:
{"status": "Success","message": "Called"}
Possible mistakes:
Sip not found
Sip not ready
specified line is offline or busy
Wrong phone
Meta info is too big
meta is more than 1000 characters
Method can also be used by passing url parametes instead of body
Independent “click to call” call
Сopied
How it works: just like a regular c2c, only independence lies in the fact that you do not need to first create a website, add a callback button to it The method allows you to create an immediate c2c call. This call will not be visible in tickets and CRM systems, but will be in the call history and webhooks. For its operation, you do not need to preliminarily create a website and connect a callback button to it. POST /calls/originateC2c
clientNumber — Client’s number who needs to call steps — array of redirect steps. You can specify several. steps.type — GSM, SIP, GROUP steps.to — operator number steps.awaitingTime —call time from 5 to 300 seconds
in steps.to you must specify: GSM-> customer number in international format (for example 380501112233) SIP -> internal line number (for example 5455) GROUP -> group (department) id. Id is displayed at the top right on each department in your account
Creating a new call
Сopied
The method is used if it is necessary to call the subscriber in order to inform him about something. After the subscriber listens to the audio recording — the call ends. The audio recording must first be added to the “API calls” category here: https://my.unitalk.cloud/new/index.html#audio. After downloading you will see its ID
Pay attention! Informational calls are not included in the call history of the project.
/calls/originateNew Mode: POST Content-Type: application/json JSON request example:
{
"phone": "380503332211", // number of subscriber to call. Not null.
"outerLine": null, // external line to call the subscriber. If null - then the line will be selected automatically, according to the rules of outgoing scripts.
"meta": "238", // String for 1000 characters. This is any information that should be displayed in webhooks. May be null.
"ivrId": 211, // id of the voice menu that will be played back to the subscriber who answered the call. If audios are specified - will be played after them. May be null if the audios or voiceSecretaryId parameter is specified. Only actions are allowed in the voice menu: "Call transfer to internal line", "Call transfer to a group of numbers" and only a group of internal lines (SIP) is allowed, "Voice message playback".
"voiceSecretaryId": 321, // id of the voice secretary that will be launched when the subscriber answers the call. If audios are specified - will be launched after them. May be null if the audios or ivrId parameter is specified. Not allowed actions in the voice secretary: "Call transfer to GSM number", "Scenario activation", "Voice menu activation" and "Transferring a call to a department" with GSM numbers.
"audios": [ //an array of audio recordings and text for voicing from which audio will be synthesized, which will be played back to the subscriber as soon as he answers the call. In what order the audios are in the array, in this they will be played. Maximum of 5 elements, of which the maximum of voicings is 2. Audio recordings voiced from the text are not displayed in the list of audio recordings of the project. May be null.
{
"id": 4953, //id of preloaded audio for calls API. May be null, in which case tts should not be null. If both id and tts are not null, id will be used.
"tts": null //data for reading text, can be null if id is specified
},
{
"id": null,
"tts": { //data for reading text, can be null if id is specified
"text": "text for voiceover", //text to be voiced cannot exceed 4960 characters. Can be null if ssml is specified. If both text and ssml fields are specified, ssml will be used
"ssml": "text for voiceover", //alternative to the text field - text in ssml format. Cannot exceed 5000 characters. Must start and end with the speak tag. Can be null if a text field is specified. If both text and ssml fields are specified, ssml will be used
"settingsId": 18 //speech synthesis settings that will be used for voiceover. Cannot be null
}
}
]
}
In case of success:
{"status": "Success"}
Possible mistakes:
Call already in progress
the previous call to this subscriber has not ended yet
Outer line not found
specified external line for outgoing calls was not found in the project
Outer line is tracked
specified external line participates in tracking. You cannot make outgoing calls from it
Meta info is too big
meta is more than 1000 characters
No audio and IVR
audios, ivrId and voiceSecretaryId are not specified, at least one must be specified
IVR can be used for SIPs only
voice menu contains unauthorized actions
Service not paid
tariff is not active, there may be no funds on the account, or there are no API calls in tariff
Limit of Simultaneously calls has reached
limit of 20 simultaneous calls reached
Wrong phone
subscriber’s phone number is incorrect
audios: Too many audios
there are too many elements in audios array
audios: Too many text to speech
there are too many elements in audios there are too many elements in the audios array with voiceover text tts
audios: Audio is null
there is a null element in the audios array
audios: Audio not found by id
the audio recording was not found in the project by the specified id
audios: Wrong type of audio
the audio recording specified in audios is not in the calls API category
audios: Text to speech ‘text’ and ‘ssml’ is null
in ttstext and ssml fields are empty, at least one must be non-null
audios: Text to speech ‘text’ not valid
in tts the text field is longer than 4960 characters
audios: Text to speech ‘ssml’ not valid
in tts the ssml field is longer than 5000 characters or does not start and end with the speak tag
audios: Text to speech ‘settingsId’ is null
id of speech synthesis settings in tts is not specified
audios: Text to speech settings not found by id
speech synthesis settings were not found in the project by id specified in tts.settingsId
audios: Audio is empty
there is an element in the audios array in which id and tts are null
audios: Text to speech failed
error when synthesizing audio from text
Call termination
Сopied
This method allows you to reset an active call by its id, which you get in webhooks, or by internal/external line number
/calls/hangup Mode: POST Content-Type: application/json JSON request example:
{
"number": null,
"id": 1474427802
}
In case of success:
{"status": "Success","message": "Found: 1"}
Possible mistakes:
Empty request
No id or number specified
Calling the prompter
Сopied
To initiate the connection of the prompter, you need to specify two mandatory parameters: ·target – The number of the internal line in the call to which the prompter will be connected; ·source – The number of the internal line that will be connected as the prompter to the active call.
Relative path: /calls/connectAsPrompter Mode: POST Content-Type: application/json
The rights to call the prompter by the users of corresponding internal lines are not taken into account when executing the request
Request JSON example:
{
"target":"1111",
"source":"2222"
}
An example of response in case of success:
{"status": "Success"}
Possible errors:
Target not found
The target line not found in project
Target is not in call
The target line is not in the call
Source not found
The prompter line not found
Source is offline
The prompter line is offline
Voice analytics
Сopied
To activate voice analytics for a call, you need to specify two mandatory parameters: ·callId – Call identifier. Can be obtained via call history API or in call webhooks; ·profileId– Identifier of the analytics profile. Can be obtained on the personal account «Voice analytics» page in the header of the target profile.
Relative path: /calls/analytics/create Mode: POST Content-Type: —
Analytics can only be run on calls for which separate records have been saved. The response to the request will be sent after the call has been processed, so it is recommended to significantly increase the response timeout for requests to this method. The maximum number of simultaneous calls in processing is 50.
{
"profileId": 123, // Profile identifier used for the speech analytics request
"profileName": "Sample Name", // Name of the speech analytics profile used
"transcription": "00:00:00,000-->00:00:15,000\nOperator: Hello! This is sample speech", // Escaped dialogue transcription
"operatorTag": "Operator", // The entity considered as the operator
"analyticsJson": "{\"dialogTopic\":{\"metricId\":1234,\"metricName\":\"Dialog topic\",\"value\":\"Voice message\",\"position\":0}, ... }",
// An escaped string containing JSON with the call analytics results (metrics).
// Each key (e.g., "dialogTopic", etc.) represents a metric,
// which has the following parameters:
// - metricId: a unique metric identifier;
// - metricName: the name of the metric;
// - value: the value of the metric (number, string, boolean yes/no, list, or object);
// - position: the position of the metric for sorting or display.
"analyticsSchema": "{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"type\":\"object\",\"properties\":{\"dialogTopic\":{\"type\":\"object\",\"properties\":{\"metricId\":{\"type\":\"integer\"},\"metricName\":{\"type\":\"string\"},\"value\":{\"type\":\"string\"},\"position\":{\"type\":\"integer\"}}}, ... }}",
// A string containing the JSON Schema that describes the structure of the analyticsJson object.
// The schema is used for validating metrics and contains type definitions for each parameter.
"languageData": { // An object containing language data for the analytics
"operatorLanguage": "english", // The spoken language of the operator
"clientLanguage": "english", // The spoken language of the client
"transcriptionLanguageCode": "en", // ISO code of the transcription language
"analyticsLanguageCode": "en", // ISO code of the language in which the analytics results were generated
"translatedLangCode": null, // ISO code of the language to which the analytics were translated. If translation was not performed, the value is null.
"translatedLangName": null // Name of the language to which the analytics were translated. If translation was not performed, the value is null.
},
"plainTranscription": "Operator: Hello! This is sample speech" // Dialogue transcription
}
The transcription response parameter contains dialogue transcription lines in the format: · *Start time of replica interval*–>*End time of replica interval* – For example, «00:00:00,000–>00:00:15,000»; · *Acting person*: *Transcription of the line* – For example, «Operator: Hello! This is a sample speech»; · The next replica in a similar format; · Time intervals and transcriptions of replicas are separated from each other by control characters of line transfer («\n»); · In the transcription parameter, unlike plainTranscription , the control characters are escaped («\\n»), besides, plainTranscription does not contain replica time intervals.
Possible errors:
Only 50 concurrent requests are allowed
The limit of simultaneously processed calls has been exceeded
Call does not exist
No call found by the specified callId
Profile does not exist
No profile found by the specified profileId
Analytics is not available for this call
It is not possible to generate voice analytics because there are no separate records for the specified call
Voice analytics is already in progress
Voice analytics processing for the specified call has already started
Voice analytics is not available
The voice analytics service is unavailable
Insufficient funds
There are insufficient funds on the project balance
Audio
Сopied
Adding audio files to the project
Сopied
/audio/upload Mode: POST Content-Type: multipart/form-data Send multipart with three parameters:
name (String)
Cannot be null. Maximum 200 characters
type (String)
GENERALScriptsIVRVoice menusMELODYMelodies of waiting on the line and queuesAUTODIALAuto callsAPIAPI calls
file (File)
Maximum size: 15mb. Audio or video file of any format is allowed. Its audio track will be converted and normalized to 0db.If the duration of the file exceeds these parameters – will be automatically truncated:IVR90 secondsAUTODIAL, MELODY, API300 secondsGENERAL30 seconds
temp (Boolean)
Optional parameter. If true, the file is marked as temporary and will be automatically deleted at 04:00
If successful, message will return the id of the loaded audio file:
{"status": "Success","message": "432"}
Synthesizing audio from text
Сopied
The method synthesizes audio from text and adds audio recordings to the project, with the specified name, and to the specified section. You can play up to 5 audios at a time. /audio/tts Mode: POST Content-Type: application/json JSON request example:
{
"data": [ //data array for audio synthesis. Maximum 5 items
{ //the first voiceover element
"name": "audio for calling", //the name with which the audio will be added to the project
"type": "AUTODIAL", //the audio section in which the audio recording will be added. Possible values: GENERAL (Scripts), IVR (Voice menus), MELODY (Waiting and queue melodies), AUTODIAL (Auto calling), API (API calls)
"tts": { //text-to-speech data
"text": "text for voiceover", //the text to be voiced cannot exceed 4960 characters. Can be null if the ssml field is specified. If both text and ssml fields are specified, ssml will be used
"ssml": null, //alternative to the text field - text in ssml format. Cannot exceed 5000 characters. Must start and end with the speak tag. Can be null if a text field is specified. If both text and ssml fields are specified, ssml will be used
"settingsId": 18 //speech synthesis settings that will be used for dubbing. Cannot be null
}
},
{ //the second voiceover element
"name": "audio for api call",
"type": "API",
"tts": {
"text": null,
"ssml": "text for voiceover",
"settingsId": 16
}
}
]
}
In case of success:
{
"status": "Success",
"message": "Success",
"data": [ //an array with the result of the synthesis, for each audio. If the audio is synthesized successfully, the id with which it was saved to the project will be indicated. In case of an error, the id will be null, and the error field will contain the error text
{ //successfully synthesized audio (id present)
"name": "audio for calling", //audio title
"id": 4962, //new audio id (in case of success)
"error": null //error text (in case of failure)
},
{ //synthesis failed or not fulfilled (no id, there is an error)
"name": "audio for api call",
"id": null,
"error": "Same name already present"
}
]
}
Possible values of the error field for each of the voicing elements on Success:
type is null
audio section not specified
Name is empty
audio name not specified or empty
Name length more than 200 chars
audio name is too long, maximum 200 characters allowed
Same name already present
audio with the same name already exists in the project
tts is null
data for voicing the text is not specified
Text to speech ‘text’ and ‘ssml’ is null
in ttstext and ssml fields are empty, at least one must be non-null
Text to speech ‘text’ not valid
in ttstext field is longer than 4960 characters
Text to speech ‘ssml’ not valid
in ttsssml field is longer than 5000 characters or does not start and end with the speak tag
Text to speech ‘settingsId’ is null
id of speech synthesis settings in tts is not specified
Text to speech settings not found by id
speech synthesis settings were not found in the project by id specified in tts.settingsId
Text to speech failed
error when synthesizing audio from text
Internal error
unknown error during audio synthesis
Possible mistakes:
Allowed only one simultaneous text to speech request per project
The same project cannot call this method multiple times at the same time. Wait until the previous request completes.
data is null
There is no data parameter in the request
data is empty
There are no elements in the data parameter
Too many elements in data
There are too many elements in the data parameter. A maximum of 5 voicings per 1 request is allowed.
Service not paid
Tariff is not active, there may be no funds on the account
Lists
Сopied
Work with lists is performed using actions, method:
Relative path: /lists Mode: POST Content-Type: application/json
The target list is specified in the request body in the required list parameter. List of existing lists: ·BLOCKED_PHONES– A list of blocked numbers in international format, interaction with which is rejected; ·BLOCKED_FOR_AUTODIAL_PHONES– A list of numbers in international format that cannot be added to autodialers. Actions are specified in the request body in the required operation parameter. List of existing actions: ·GET – Getting the current list; ·ADD– Adding elements to the list; ·REMOVE– Removing items from the list. For ADDand REMOVE actions, it is necessary to specify an array of elements that will be added or removed in the items parameter. The maximum number of elements in the items array is 100.
Blocked phones
Сopied
A list of blocked numbers in international format, interaction with which is rejected. To work with a list of blocked numbers, you must specify «BLOCKED_PHONES» in the required list parameter. For ADDand REMOVE actions, the items parameter must be an array of numbers in international format.
A list of numbers in international format that cannot be added to autodialers. To work with a list of numbers that cannot be added to autodialers, you must specify «BLOCKED_FOR_AUTODIAL_PHONES» in the required list parameter. For ADDand REMOVE actions, the items parameter must be an array of numbers in international format.
Work history allows you to get summarized information about the time users spent in different work statuses for a certain date. To do this, you must specify the target date in the mandatory date parameter in the «yyyy-MM-dd» format.
Relative path: /users/workHistory Mode: POST Content-Type: —
Request example:
/users/workHistory?date=2024-01-01
An example of response in case of success:
{
"users": {
"12345": { // "Unique user identifier": An array containing information about the corresponding user
"firstName": "John", // User Name
"lastName": "Callid", // User's last name. May be null
"phone": 1234, // Number assigned to the user. May be null
"userTimeSeconds": { // An array with information about the time spent in different statuses
"byPauses": { // An array with information about the time spent in different types of pauses
"Launch": 1800, // "Name of the status type": The number of seconds spent in the corresponding type of the status
...
},
"byWork": { // An array with information about the time spent in different types of "Working" status
"Cold Calling": 18000, // "Name of the status type": The number of seconds spent in the corresponding type of the status
...
},
"byStop": { // An array with information about the time spent in different types of "Not working" status
"Non-working hours": 54000, // "Name of the status type": The number of seconds spent in the corresponding type of the status
...
},
"stop": 54000, // Number of seconds in "Not working" status
"work": 28800, // Number of seconds in "Working" status
"pause": 3600 // Number of seconds on pause
},
"middleName": "Triple" // Middle name. May be null
},
...
}
}
Counting the number of seconds spent by a user in a certain status begins with the first status change after the user is created and added to the project.
Possible errors:
Future data is absent
Future date specified, corresponding data missing
Users list
Сopied
To get a list of users and data about them, you need to send an empty request.
Relative path: /users/list Mode: POST Content-Type: —
An example of response:
[
{
"email": "example@gmail.com",
"firstName": "John", // User Name
"lastName": "Callid", // User's last name. May be null
"middleName": "Triple" // Middle name. May be null
"phone": 1234, // Number assigned to the user. May be null
"role": "ADMIN", // User's role in project
"id": 12345, // Unique user identifier
"workStatus": "WORK", // User's work status
"workStatusName": "Cold Calling" // User's work status name. May be null
},
...
]
Obtaining user statuses
Сopied
To get a list of users and their work status data, you need to send an empty request.
Relative path: /users/getStatus Mode: POST Content-Type: —
An example of response:
[
{
"firstName": "John", // User Name
"lastName": "Callid", // User's last name. May be null
"middleName": "Triple" // Middle name. May be null
"phone": 1234, // Number assigned to the user. May be null
"workStatus": "WORK", // User's work status
"workStatusName": "Cold Calling" // User's work status name. May be null
},
...
]
Changing work status
Сopied
To change the user’s work status, you must specify the operator line number in the numberparameter, and the new work status in the status parameter. Valid values: WORK (“Working”), STOP (“Not working”), PAUS (“Pause”). Optionally, in the statusName parameter, you can specify the name of the work status, which must completely match one of those existing in the project.
Relative path: /phones/inner/setStatus Mode: POST Content-Type: —
To get a list of internal lines and their current status, you need to send an empty request. The response will return an associative array, where the key is the internal line number, and the value is its current status. Possible statuses: online (line online and not busy), busy (line online and busy with a call) and offline (line not online).
Relative path: /phones/inner Mode: POST Content-Type: —
{
"status": "Success",
"data": [
{
"id": 455, // group id
"name": "Sales department", // group name
"phones": [ // array of numbers the group contains
{
"number": "4030", // number
"firstName": "Alexander", // Username, if it exists
"lastName": "Maksimov" // User surname, if it exists
}
]
}
]
}
Deleting a number from a group
Сopied
POST /groups/action Body JSON request example:
{
"action": "REMOVE_NUMBER",
"groupId": 141, // group id
"number": "2561" // number to be deleted
}
To obtain statistics by project operators, you must specify the beginning and end of the target period in the from and to parameters respectively, in the format “yyyy-MM-dd HH:mm:ss”.
Relative path: /operator/statistic Mode: POST Content-Type: application/json
Additionally, records can be pre-filtered in the optional filter parameter by: · callTypes — List of call types for which statistics will be generated. The list of permissible values is given in the corresponding dictionary; · innerPhones — List of numbers of internal lines for which statistics will be generated; · minTimeSeconds — Minimum conversation duration in seconds; · minTimeAwaitingSeconds — Minimum waiting time in seconds; · maxTimeAwaitingSeconds — Maximum waiting time in seconds.
[
{
"operatorName": "1234 (Sample Name)", // General statistics: Operator
"operatorPhone": "1234", // Operator phone number
"totalCount": 123, // General statistics: Calls
"inCount": 123, // General statistics: Incoming
"outCount": 123, // General statistics: Outgoing
"totalDuration": "59:59", // General statistics: Conversation duration
"inUniqueCount": 123, // General statistics: Unique incoming
"answOpNaCount": 0, // General statistics: Missed ones that were not answered
"outAnsweredCount": 123, // By outgoing: Successful
"outAnsweredPercentage": "100.0%", // By outgoing: Percentage of answered calls
"outMissedCount": 0, // By outgoing: No Answer
"outUniqueCount": 123, // By outgoing: To unique phone numbers
"outUniqueAnsweredCount": 123, // By outgoing: The number of successful calls to unique numbers
"outUniqueAnsweredPercentage": "100.0%", // By outgoing: Percentage of successful calls to unique numbers from the total number of outgoing
"outDuration": "59:59", // By outgoing: Conversation duration
"outAverageDuration": "05:30", // By outgoing: Average conversation time
"inAnsweredCount": 123, // By incoming: Accepted
"inAnsweredPercentage": "100.0%", // By incoming: Percentage of calls answered
"inMissedCount": 0, // By incoming: Missed ones that were not answered
"inHangupByOperatorCount": 123, // Count of incoming calls dropped by operator
"inHangupByClientCount": 123, // Count of incoming calls dropped by client
"inUniqueAnsweredCount": 123, // By incoming: Answered calls from unique numbers
"inUniqueAnsweredPercentage": "100.0%", // By incoming: Percentage of answered calls from unique numbers
"inAnsweredNewLeadCount": 123, // By incoming: Accepted from new customers
"inLostCount": 0, // By incoming: The lost
"inAverageAwaitingTime": "00:15", // By incoming: Average response time
"inTotalAwaitingTime": "02:30", // By incoming: Total response time
"inDuration": "59:59", // By incoming: Conversation duration
"inAverageDuration": "05:30", // By incoming: Average conversation time
"inUniqueRegularCount": 123, // By unique: Direct call
"inUniqueTrackingCount": 123, // By unique: Call tracking
"inUniqueC2cButtonCount": 123, // By unique: Click to call
"inUniqueC2cFormCount": 123, // By unique: Form
"inUniqueC2cApiCount": 123, // By unique: Click to call API
"inUniqueAutodialCount": 123, // By unique: Autodialer
"inUniqueCallbackCount": 123, // By unique: Automatic callback
"inUniqueAutoCallbackCount": 123, // By unique: Callback
"inUniqueApiCount": 123, // By unique: API call
"inRegularCount": 123, // By sources: Direct call
"inTrackingCount": 123, // By sources: Call tracking
"inC2cButtonCount": 123, // By sources: Click to call
"inC2cFormCount": 123, // By sources: Form
"inC2cApiCount": 123, // By sources: Click to call API
"inAutodialCount": 123, // By sources: Autodialer
"inCallbackCount": 123, // By sources: Callback
"inAutoCallbackCount": 123, // By sources: Automatic callback
"inApiCount": 123, // By sources: API call
"inMissedAnsweredCount": 0, // By missed: Missed, answered
"inMissedNewLeadCount": 0, // By missed: Missed from new customers
"inMissedPercentage": "0.0%", // By missed: Percentage of missed calls from all calls
"inMissedAverageAwaitingTime": "00:00", // By missed: The average waiting time for an operator's response
"logInTime": "2024-01-30 08:40:00", // Login
"logOutTime": "2024-02-05 18:30:00", // Logout
"availableNotInWorkTime": "02:30:00", // Total Available
"pauseTime": "05:30:00", // Pause
"wrapUpTime": "", // Total Wrap-up Time
"compoundTime": 123 // Total Compound Time
},
...
]
The start date and time of the target period is not specified or is incorrect
Wrong TO date
The end date and time of the target period is not specified or is incorrect
Call history
Сopied
To obtain the call history of the project, you must specify the beginning and end of the period of interest in the dateFrom and dateTo parameters, respectively, in the format “yyyy-MM-dd HH:mm:ss”. Records are returned in descending order by id. The number of records that will be received does not exceed the value of the required limit parameter. The valid limit range is from 1 to 1000. To obtain the next group of records, you must specify a shift relative to the beginning of the list in the offest parameter.
Relative path: /history/get Mode: POST Content-Type: application/json
In addition, records can be pre-filtered in the optional filter parameter by: · direction — Call direction. Acceptable values: IN – incoming, OUT – outgoing, INNER – internal; · minDuration — Minimal conversation duration in seconds; · calledFrom — An array of number parts from which the call was made; · calledTo — An array of number parts that were called; · outerNum — An array of external lines numbers to which calls were received or through which calls were made; · exactPhone — An array of full numbers that made or received calls; · newLead — Sign of the first call to the client number. Acceptable values: true – only the first ones, false – only not the first ones; · answered — Sign of an answered call. Acceptable values: true – only answered, false– only not answered; · lost — Sign of a lost call (missed call that was not called back). Acceptable values: true – only lost, false – only not lost; · voiceMessage — Sign of a left voice message in a call. Acceptable values: true – only with a voice message, false – only without.
{
"count": 100, // Number of calls according to the specified criteria
"calls": [ // Calls array
{
"id": 19990701, // Random call id
"dbid": 603, // Call id in the project
"date": "2023-12-20 15:28:00", // Date and time of the call
"source": "REGULAR", // Call source
"direction": "IN", // Call direction
"from": "380955555555", // Caller number
"to": ["3333"], // An array of numbers that received a call
"lastGroupName": "Sales managers", // Name of the last group of internal lines, to which call was transferred
"secondsFullTime": 300, // Full call duration
"secondsTalk": 285, // Duration of conversation
"link": "https://api.unitalk.cloud:8443/tracking/rec/1531144732.920/2023-12-20", // Call recording link
"comment": "That one was successful!", // A comment
"state": "ANSWER", // Call state
"cause": 16, // Termination reason code
"callback": false, // Automatic callback sign
"utmSource": "google", // Analytics Label
"utmMedium": "search", // Analytics Label
"utmCampaign": "web", // Analytics Label
"utmTerm": "best+product", // Analytics Label
"utmContent": "content", // Analytics Label
"outerNumber": "site.ua", // Analytics Label
"googleId": "1182768620.1182768620", // Analytics Label
"facebookClientId": "fb.1.1234567890" // Analytics Label
"referer": "google.com" // Analytics Label
},
...
]
}
Possible errors:
Wrong FROM date
The start date and time of the target period are not specified or are incorrect
Wrong TO date
The end date and time of the target period are not specified or are incorrect
Limit range is 1-1000
The limit parameter is not specified or is incorrect
Webhooks
Сopied
You can use the webhook system to get information about telephony events. In addition, UniTalk supports incoming webhooks.
Balance Movement
Сopied
The “Balance movement” webhook provides information on each project balance change operation and cannot be configured, since events of this category are processed automatically by the system. To work with this webhook, your web application must accept JSON using the POST method at the URL specified on the “API” page of your personal account.
There are 5 types of operations in total:
MAIN_REFILL
Main account top up
BONUS_REFILL
Bonus account top up
CALL
Write-off for a paid call
SMS
Write-off for sending SMS
SERVICES
Write-off for services
Example of sent JSON:
{
"date": "2022-11-12 19:12:50", // Operation time
"type": "MAIN_REFILL", // Operation type
"sum": 500000, // Transaction amount. 1000 corresponds to the project currency unit
"sumV2": 500000000, // Transaction amount. 1000,000 corresponds to the project currency unit
"mainBalance": 15500000, // Main balance upon completion of the transaction. 1000 corresponds to the project currency unit
"mainBalanceV2": 15500000000, // Main balance upon completion of the transaction. 1000,000 corresponds to the project currency unit
"bonusBalance": 350000, // Bonus balance upon completion of the transaction. 1000 corresponds to the project currency unit
"description": "Пополнение баланса на 500.00 UAH через LiqPay" // Operation description
}
Event handling
Сopied
Sending a webhook can be selected as an action type when creating or editing actions on the “Event handling” page of your personal account. When configuring an action of this type, you can specify: 1) URL to which the webhook will be sent; 2) HTTP method to be used; 3) HTTP headers; 4) URL parameters; 5) Request body type (For POST, PUT, PATCH); 6) The content of the request body (For types “Specified JSON” and “Form (urlencoded)”). There are 4 event types that you can assign actions to: Event types
Events in autodialers
They are configured for each individual autodialer when creating or editing through the API or in the corresponding section of your personal account, for example, “Autodial completed”.
They are configured on the “API” page of your personal account, for example, “End call“. Please note that the action is assigned to the call event, regardless of the external line that is involved
For more information about the event handling process, see the event handling instructions. Sending a webhook with a “Standard JSON” body type means generating a request body based on the type of event on which the webhook was sent: Standard JSON for call events:
{
"event": "CALL_END", // The event that the webhook was sent on
"call": { // Call data array
"id": 1091944, // Randomly generated call id to associate it with other call events
"dbid": 275, // id under which this call was saved to the database. Subsequently, the call has this id
"from": "380505557182", // The number from which the call was made
"to": [ // Array of numbers to which the call was redirected
"2000"
],
"lastGroupName": "Sales managers", // Name of the last group of internal lines, to which call was transferred
"outerNumber": "site.ua", // The outer line that was used to make or receive a call. Contains the name of the site in case of a callback
"direction": "IN", // Call direction: "IN" - incoming, "OUT" - outgoing, "INNER" - internal
"date": "2018-07-09 16:58:52", // Date and time the call was received
"secondsFullTime": 19, // Total call time. Only known in the CALL_END event
"secondsTalk": 9, // Communication time. Only known in the CALL_END event
"utmSource": "google", // Analytics label. May be null
"utmMedium": "search", // Analytics label. May be null
"utmCampaign": "web", // Analytics label. May be null
"utmTerm": "ковры", // Analytics label. May be null
"utmContent": "content", // Analytics label. May be null
"googleId": "1182768620.1530916891", // Analytics label. May be null
"facebookClientId": "fb.1.1234567890", // Analytics label. May be null
"referer": "google.com", // Analytics label. May be null
"callback": true, // Indicates whether this call is a callback. Deprecated. Use the "source" field instead
"comment": "комментарий к звонку",
"state": "ANSWER", // Call status. For CALL_NEW and CALL_REDIRECT events - null
"source": "REGULAR", // Call source
"link": "https://api.unitalk.cloud:8443/tracking/rec/1531144732.920/2018-07-09", // Link to call recording. Only present if the state field is "ANSWER"
"meta": "some info", // Additional information that can be set when initiating a call via the API
"cause": 16 // Call end code
}
}
“to” array
On the CALL_NEW event of an incoming call
Always empty
On CALL_REDIRECT event
Contains one or more numbers
On CALL_ANSWER event
Contains one number
On CALL_END event
May be empty or contain the numbers of the operators who received the call
For API calls
May be absent if the call was not redirected to anyone
“state” field
ANSWER
The call was accepted
BUSY
Line was busy
FAIL
Failure
NOANSWER
The call was not accepted
CHANUNAVAIL
The number you called was not available
NOMONEY
Not enough funds to make the call
BUSYOUT
All external lines were busy during the call
WRONGDIR
Wrong call direction
BLOCKED
The call was blocked according to the project settings
DIALING
Call in progress
UNREACHABLE
The subscriber is unreachable or out of network coverage
NOT_EXIST
Called number does not exist
“source” field
REGULAR
Regular direct call
TRACKING
Call tracking call
CLICK2CALL
ClickToCall from the button
LEAD_CATCHER
ClickToCall from the popup
FORM
ClickToCall from the form
CALLBACK
Call based on callback attribute on an outer number
AUTO_CB
Automatic callback for missed call
AUTODIAL
Call from an autodialer
API_CALL
Call initiated via API
C2C_API
с2с call initiated via API
Standard JSON for voice menu events:
{
"ivrName":"Распределение по отделам", // Name of the voice menu
"from":"380971234567", // Subscriber's phone number
"outerNumber":"380441234567", // The outer line that was used to make or receive a call. Contains the name of the site in case of a callback
"pressedDigit":2, // The number pressed by the subscriber. May be null
"actionType": "MAIN", // Action type. "MAIN" - main action, "NO_CHOICE" - no choice action, "WRONG_DIGIT" - wrong choice action
"projectName": "myproject", // Project name
"utmCampaign": "sale2021", // Analytics label. May be null
"utmSource": "google", // Analytics label. May be null
"utmMedium": "email", // Analytics label. May be null
"utmTerm": "term", // Analytics label. May be null
"utmContent": "content", // Analytics label. May be null
"googleId": "11111.11111", // Analytics label. May be null
"facebookClientId": "fb.1.1234567890" // Analytics label. May be null
}
Standard JSON for autodialers calls completion events:
{
"from": "380971234567", // Subscriber's phone number
"operatorNumber": "2040", // Operator's internal line. May be null
"callName": "Владимир", // Name assigned to the autodialers number
"callNote": "покупал окна", // Note to the autodialers number
"calledCount": 1, // Number of calls to this number in the autodialer
"callState": "ANSWER", // Call end status. More details in the section "Autodialers" - "General information"
"dialName": "обзвон-окна", // Autodialer name
"totalCount": 2000, // Count of numbers in the autodialer
"doneCount": 537, // Cunt of processed numbers in the autodialer
"projectName": "myproject" // Project name
}
Standard JSON for non-call autodialer events
{}
Standard JSON for voice queue events:
{
"from":"380971234567", // Subscriber's phone number
"projectName":"my-project", // Project name
"utmCampaign": "sale2021", // Analytics label. May be null
"utmSource": "google", // Analytics label. May be null
"utmMedium": "email", // Analytics label. May be null
"utmTerm": "term", // Analytics label. May be null
"utmContent": "content", // Analytics label. May be null
"googleId": "11111.11111", // Analytics label. May be null
"facebookClientId": "fb.1.1234567890", // Analytics label. May be null
"gclid": "gclid..." // Analytics label. May be null
"cdid": "cdid...", // Analytics label. May be null
"referer": "https://unitalk.cloud", // Analytics label. May be null
"ip": "111.111.111.111" // !
}
Removing Scheduled Event Handlers
Сopied
To remove scheduled event handlers, you must specify a list of phone numbers in international format for which event handlers will be removed.
Relative path: /api/eventHandlers/removeScheduledByPhones Mode: POST Content-Type: application/json
If the request is successfully executed, the number of removed handlers will be returned in the data parameter.
Possible errors:
Phones is not specified
phones parameter is not specified or empty
Too many phones
More than 100 elements were passed in the phones parameter
Invalid phones
The phones parameter contains invalid numbers. The data response parameter will contain an array of phones elements that did not pass validation.
Wait until the previous request is processed
One project can simultaneously run one deletion process for scheduled event handlers. At this moment, deletion is in process in the project. Please try again later when the previous operation completes.
Incoming webhooks
Сopied
UniTalk can accept webhooks with a specific structure and perform actions on them. Actions currently available: 1) “AUTODIAL_ADD” – Add numbers to autodialer 2) “AUTODIAL_REMOVE” – Remove numbers from autodialer To use incoming webhooks on the “API” personal account page, you must: 1) Generate a token:
2) Click the “Generate link” button:
3) Select the action, the autodialer that it will be applied to, specify additional options and click the “Generate” button:
4) Fill in the link parameters and send a POST request to it. Parameters that are filled in automatically during generation:
token
Token for incoming webhooks
action
Webhook action type
id
Autodialer id
Add numbers to autodialer
Сopied
An example of a generated link: https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=¬e=&link=&phones= Parameters to be filled in:
phones
Phone number or a list of phone numbers separated by commas to be added to the autodialer
name
The name that will be assigned to the added numbers. Maximum 100 characters. Optional field
note
A note that will be assigned to the added numbers. Maximum 500 characters. Optional field
link
A data for Web Dialer that will be assigned to the added numbers. Maximum 500 characters. Optional field
An example of a completed link: https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=vasya¬e=okna&phones=380971234567 When sending a POST request to this link, the phone number “380971234567”, with the name “vasya” and the note “okna” will be included to the autodialer with id “20461” In case of success:
{"status": "Success"}
Possible errors:
Token not found
Transferred token not found in UniTalk
Action not found
Missing action parameter in link
Id is null
Missing id parameter in link
Autodial not found
Autodialer not found by id
Empty phones
phones parameter is not specified or empty
Phones not found
The phones parameter is not empty, but at least one valid phone number was not found in it
Phones not added
Failed to add numbers to the autodialer. Perhaps the numbers have already been added to the autodialer
Remove numbers from autodialer
Сopied
An example of a generated link: https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_REMOVE&id=20461&phones= Parameters to be filled in:
phones
Phone number or a list of phone numbers separated by commas to be added to the autodialer
An example of a completed link: https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_REMOVE&id=20461&phones=380971234567,380670001000 When sending a POST request to this link, the numbers “380971234567” and “380670001000” will be removed from the autodialer with id “20461”. In case of success:
{"status": "Success"}
Possible errors:
Token not found
Transferred token not found in UniTalk
Action not found
Missing action parameter in link
Id is null
Missing id parameter in link
Autodial not found
Autodialer not found by id
Empty phones
phones parameter is not specified or empty
Phones not found
The phones parameter is not empty, but at least one valid phone number was not found in it
Calls not found
Failed to delete any number. It is possible that none of the listed numbers were in the autodialer
Transferring a call to the responsible operator
Сopied
Webhook “Transferring a call to the responsible operator” allows you to take information about the call for a further choice of the responsible operator by your system. To work with this webhook, your web application must accept JSON using the POST method specified when creating or editing an incoming script on the “Incoming Scripts” page of your personal account, when choosing redirect to “To the responsible manager” and activating the “Request to Your API” option URL.
When this redirect is performed, a request with the following content will be sent to the specified URL:
{
"event": "ROUTE",
"call": {
"from": "380505557182", // Caller number
"outerNumber": "380442949168" // Outer number which received the call
}
}
In response, your application should send JSON with the following structure:
{
"operatorNumber": "2048", // Phone number of the responsible operator. You can specify SIP or GSM. May be null
"callerName": "Александр", // The name of the subscriber that will be displayed in the SIP client
"ivrId": 487 // id of the voice menu to be played to the subscriber. May be null
}
There is no need to pre-check whether the operator is free at the moment: if he is busy, the call wont redirected to him.
Voice queue management
Сopied
“Voice queue management” webhook allows you to get information about the call for subsequent prioritization of customer processing by your system. To work with this webhook, your web application must accept JSON using the POST method specified when creating or editing an incoming script on the “Incoming Scripts” page of your personal account, when choosing redirect to “Voice queue” and activating the “Webhook for management” URL option.
When this redirect is performed, a request with the following content will be sent to the specified URL:
{
"outerNumber": "380440000001", // Outer number that received the call
"from": "380501234567", // Subscriber number
"utmSource": null, // Analytics label. May be null
"utmMedium": null, // Analytics label. May be null
"utmCampaign": null, // Analytics label. May be null
"utmTerm": null, // Analytics label. May be null
"utmContent": null, // Analytics label. May be null
"googleId": null, // Analytics label. May be null
"facebookClientId": null, // Analytics label. May be null
"gclid": null, // Analytics label. May be null
"cdid": null, // Analytics label. May be null
"referer": null // Analytics label. May be null
}
The priority queue consists of 10 queues, which are processed in descending order. By default, UniTalk defines all calls to queue number 5. Your application can change the queue number by sending in response a JSON with the following structure:
{
"setPriority": 7 // Queue number from 1 to 10
}
Messages
Сopied
To send messages via SMS and Viber, integration with the messaging service must be enabled on the personal profile page «Message sending service» of the «Integration» section. Availability of message types and directions depends on the settings of this integration. Maximum text length for Viber is 1000 symbols, for SMS – depends on the messaging service.
Message sending
Сopied
Relative path: /message/send Mode: POST Content-Type: application/json
JSON request example for SMS:
{
"messageType": "SMS", // Message type "SMS" (required)
"alfaName": "YourSmsAlphaName", // Sender's alpha name. Relevant only for the Unitalk provider if you have more than one alpha name connected (optional parameter)
"to": "380971234567", // Recipient's phone number in international format (required)
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit" // Message text (required)
}
JSON request example for Viber:
{
"messageType": "VIBER", // Message type "VIBER" (required)
"alfaName": "YourViberAlphaName", // Sender's alpha name. Relevant only for the Unitalk provider if you have more than one alpha name connected (optional parameter)
"to": "380971234567", // Recipient's phone number in international format (required)
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit" // Message text (required)
}
Message identifier returned in data can be used to later retrieve information about message sending status.
Possible errors:
Message service not connected
Message sending service is not connected
Validation error
Validation errors. Possible causes: · Wrong recipient’s phone number · Sending messages to this destination is not allowed by the integration settings with the message sending service · Message type is not selected · SMS sending is disabled in the settings of the message sending service · Sending messages to Viber is disabled in the settings of the message sending service · Message cannot be empty · Message is too long · Message contains invalid characters
UniTalk did not allow sending
UniTalk did not allow sending. Possible causes: · Unavailable destination for sending · Insufficient funds on the balance · Project is not active
Service response
Service response. Possible causes: · Invalid authorization data · Insufficient funds on the balance · Request limit exceeded · Duplicate message · IP address is not allowed in the messaging service · Sender’s name is blocked by recipient · Recipient’s country not available · Recipient’s number is blocked · Invalid sender name · Sender name on moderation · Invalid recipient number · Invalid text · Sending messages to Viber is not available · Data is incorrect · Viber messaging service is temporarily unavailable
Unknown error
Unknown error
Bulk message sending
Сopied
Bulk message sending can be used to send multiple messages with one request. The maximum number of messages is 100. The request can be made in two versions: · Indicating the general text of messages in the textparameter and a list of recipients’ phone numbers in international format in the recipients parameter; · Indicating the recipients’ phone numbers in international format and the corresponding message texts in pairs in the messages array, where the key is the phone number and the value is the message text. If the request simultaneously contains parameters for both methods, the messages parameter will be used.
Relative path: /message/sendBulk Mode: POST Content-Type: application/json
JSON request examples:
{
"messagesType": "SMS", // Type of messages. "SMS" or "VIBER"
"recipients": [ // Recipients' phone numbers in international format
"380971234567",
"380981234567",
...
],
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit." // Text of messages
}
{
"messagesType": "SMS", // Type of messages. "SMS" or "VIBER"
"messages": { // Messages array
"380971234567": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 1", // "Phone number": "Message text"
"380981234567": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 2", // "Phone number": "Message text"
...
}
}
An example of response in case of success:
{
"status": "Success",
"data": {
"380971234567": { // Sent
"id": 123451, // Message identifier
"error": null // Message sending error text
},
"380981234567": { // Not sent
"id": 123452, // Message identifier
"error": "Sample error text" // Message sending error text
},
...
}
}
The array returned in data contains the identifier and sending error text of each of the messages being sent. The identifier can be used to later retrieve information about message sending status.
Possible errors:
Message service not connected
Message sending service is not connected
messagesType is null
No type of messages selected
Messages not specified
Neither the messages nor recipients parameter is specified in the request
Too many messages
The messages array contains more than 100 pairs
messages is empty
The messages array is empty
messages contains null key
There is an empty key in the messages array
messages contains null value
There is an empty value in the messages array
Too many recipients
The recipients list contains more than 100 numbers
recipients is empty
The recipients list is empty
recipients contains null
There is an empty value in the recipients list
text is null or empty
The recipients list is used for sending, but the text is not specified
Getting the message sending status
Сopied
To get the message sending status, you need to specify the identifier received when sending it in the id parameter.
Relative path: /message/getStatus Mode: POST Content-Type: application/x-www-form-urlencoded (It is also possible to send a request passing the parameters as url parameters, without a body)
Request exapmle:
/message/getStatus?id=12345
An example of response in case of success:
{
"status": "Success",
"data": {
"messageStatus": "ERROR", // Message sending status
"errorText": "Service response: invalid authorization data" // Error text. If status is not ERROR - null
}
}
The array returned in data contains the message sending status and the text of the sending error if the sending status is ERROR.
Sending statuses: ·SENT – Sent. There is no delivery information; ·DELIVERED – Delivered; ·NOT_DELIVERED – Не доставлено; ·ERROR – Sending error.
Possible errors:
Invalid id
The id parameter is missing or not valid
Message not found
No message was found by the specified id
Getting a list of distributions
Сopied
To get a list pf distributions and related information, you need to send an empty request.
Relative path: /messageDistribution/getAll Режим: POST Content-Type: –
Response example:
[
{
"id": 123, // Distribution identifier
"name": "Sample_name", // Name
"messageType": "SMS", // Type of messages. "SMS" or "VIBER"
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Distribution text
"startTime": "2024-07-07 12:00:00", // Start time. If started right away - null
"paused": false, // Ознака пауз. "true" - on pause, "false" - not
"totalNumbersCount": 10, // The number of numbers in the distribution
"currentNumbersCount": 10, // The number of unprocessed numbers
"status": "WAITING_START_TIME" // Distribution status
},
...
]
Distribution statuses: ·COMPLETED – Distribution completed; ·PAUSED – On pause; ·WAITING_START_TIME – Waiting for the start time; ·IN_PROGRESS – In the process of distribution; ·MESSAGE_SERVICE_NOT_CONNECTED – Message sending service is not connected.
Creating a distribution
Сopied
To create a distribution, you need to specify mandatory parameters in the request: ·name – Unique name of the new distribution. The maximum length is 45 characters; ·messageType – Type of messages. “SMS” or “VIBER“; ·numbers – List of recipients’ phone numbers in international format. The maximum number of numbers is 10000; ·text – Distribution text. Restrictions depend on the type of messages and message sending service. Optionally, the date and time of the delayed start can be specified in the startTime parameter in the “yyyy-MM-dd HH:mm:ss” format.
Relative path: /messageDistribution/create Mode: POST Content-Type: application/json
Request JSON example for SMS distribution:
{
"name": "SmsDistributionName", // Name of the distribution (required)
"messageType": "SMS", // Type of distribution "SMS" (required)
"alphaName": "YourSmsAlphaName", // Sender's alpha name. Relevant only for the Unitalk provider if you have more than one alpha name connected (optional)
"numbers": [ // Recipient phone numbers in international format (required)
"380971234567",
"380671234567",
...
],
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit", // Distribution text (required)
"startTime": "2029-07-07 12:00:00" // Scheduled start date and time. Can be null — in this case, it will be launched immediately (optional)
}
Request JSON example for Viber Promo distribution:
{
"name": "ViberDistributionName", // Name of the distribution (required)
"messageType": "VIBER", // Type of distribution "VIBER" (required)
"viberMessageType": "PROMO", // Type of Viber messages: "PROMO" (required)
"alphaName": "YourViberAlphaName", // Sender's alpha name. Relevant only for the Unitalk provider if you have more than one alpha name connected (optional)
"numbers": [ // Recipient phone numbers in international format (required)
"380971234567",
"380671234567",
...
],
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Distribution text (required)
"base64Image": "iVBORw0KGgoAAA....", // Image in base64 format to be sent with the message (optional)
"mimeType": "image/jpeg", // MIME type for your base64 image (required if base64Image is used)
"fileName": "promo_image", // Image file name (up to 20 characters). Can be used as metadata (required if base64Image is used)
"buttonText": "Buy", // Button text (up to 30 characters) (optional)
"buttonUrl": "https://example.com", // URL that opens when the button is clicked (required if buttonText is used)
"viberTTL": 3600, // "Time to Live" — how many seconds the Viber message can wait for delivery. Specified in seconds, allowed range: 60–86400 (required)
"startTime": "2029-07-07 12:00:00" // Scheduled start date and time. Can be null — if null, the distribution starts immediately (optional)
}
Request JSON example for Viber Transactional distribution:
{
"name": "ViberDistributionName", // Name of the distribution (required)
"messageType": "VIBER", // Type of distribution "VIBER" (required)
"viberMessageType": "TRANSACTIONAL", // Type of Viber messages: "TRANSACTIONAL" (required)
"alphaName": "YourViberAlphaName", // Sender's alpha name. Relevant only for the Unitalk provider if you have more than one alpha name connected (optional)
"numbers": [ // Recipient phone numbers in international format (required)
"380971234567",
"380671234567",
...
],
"text": "Your verification code is: 1234", // Message text (required)
"viberTTL": 3600, // "Time to Live" — how many seconds the Viber message can wait for delivery. Specified in seconds, allowed range: 60–86400 (required)
"startTime": "2029-07-07 12:00:00" // Scheduled start date and time. Can be null — if null, the distribution starts immediately (optional)
}
Request JSON example for Viber Carousel distribution:
{
"name": "ViberDistributionName", // Name of the distribution (required)
"messageType": "VIBER", // Type of distribution "VIBER" (required)
"viberMessageType": "CAROUSEL", // Type of Viber messages: "CAROUSEL" (required)
"alphaName": "YourViberAlphaName", // Sender's alpha name. Relevant only for the Unitalk provider if you have more than one alpha name connected (optional)
"numbers": [ // Recipient phone numbers in international format (required)
"380971234567",
"380671234567"
],
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Message text (required)
"carouselItems": [ // Number of items in the carousel, from 2 to 5 (required)
{
"title": "Sneakers A1", // Title of the first carousel item, 2–38 characters (required)
"base64Image": "iVBORw0KGgoAAA....", // Image in base64 format (required)
"mimeType": "image/png", // MIME type of your base64 image (required)
"fileName": "a1_carousel", // Image file name, up to 20 characters; can be used as metadata (required)
"primaryButton": { // Main button settings
"label": "Buy", // Button text, up to 10 characters (required)
"actionUrl": "https://example.com/a1" // URL that opens when the button is clicked (required)
},
"secondaryButton": { // Secondary button settings (optional)
"label": "Details", // Button text, up to 12 characters (optional)
"actionUrl": "https://example.com/a1/info" // URL that opens when the button is clicked (optional)
}
},
{
"title": "Sneakers B2",
"base64Image": "iVBORw0KGgoAAA....",
"mimeType": "image/png",
"fileName": "b2_carousel",
"primaryButton": {
"label": "Buy",
"actionUrl": "https://example.com/b2"
}
}
],
"viberTTL": 3600, // "Time to Live" — how many seconds the Viber message can wait for delivery. Specified in seconds, allowed range: 60–86400 (required)
"startTime": "2029-07-07 12:00:00" // Scheduled start date and time. Can be null — if null, the distribution starts immediately (optional)
}
Request JSON example for Viber+SMS fallback distribution:
{
"name": "ViberWithSmsFallback", // Name of the distribution (required)
"messageType": "VIBER", // Type of distribution "VIBER" (required)
"viberMessageType": "PROMO", // Type of Viber message: "PROMO", "TRANSACTIONAL", or "CAROUSEL" (required)
"alphaName": "YourViberAlphaName", // Sender's alpha name. Relevant only for the Unitalk provider if you have more than one alpha name connected (optional)
"numbers": [ // Recipient phone numbers in international format (required)
"380971234567",
"380671234567"
],
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit", // Viber message text (required)
"viberTTL": 3600, // "Time to Live" — how many seconds the Viber message can wait for delivery. Specified in seconds, allowed range: 60–86400 (required)
// For each viberMessageType, all corresponding parameters described above are inherited
...
"sendSmsAfterViber": true, // Parameter that enables the Viber+SMS fallback distribution (required)
"smsText": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit", // SMS message text (required)
"smsAlphaName": "YourSmsAlphaName", // Sender's alpha name for SMS. Relevant only for the Unitalk provider if you have more than one alpha name connected (optional)
"startTime": "2029-07-07 12:00:00" // Scheduled start date and time. Can be null — if null, the distribution starts immediately (optional)
}
The distribution identifier returned in data can be used for further interaction with it.
Possible errors:
The project does not have a messaging service connected
Message sending service is not connected
The name cannot be empty or contain more than 45 characters
Distribution name is not specified or exceeds 45 characters
The name already exists
A distribution with that name already exists
No customer numbers are listed
The numbers in the numbers list are not specified
There can be no more than 10000 numbers in the message distribution
The number of numbers in the numbers list exceeds 10000
Wrong numbers
There are incorrect numbers in the numbers list. A list of incorrect numbers will be returned in the data response parameter
Incorrect time format
The format of the startTime parameter is incorrect
Validation error
Validation errors. Possible causes: · Message type is not selected · SMS sending is disabled in the settings of the message sending service · Sending messages to Viber is disabled in the settings of the message sending service · Message cannot be empty · Message is too long · Message contains invalid characters
Updating a distribution
Сopied
To update a distribution, you need to specify mandatory parameters in the request: ·id – Distribution identifier; ·name – Unique name of the distribution. The maximum length is 45 characters; ·messageType – Type of messages. “SMS” or “VIBER“; ·text – Distribution text. Restrictions depend on the type of messages and message sending service. Optionally, the date and time of the delayed start can be specified in the startTime parameter in the “yyyy-MM-dd HH:mm:ss” format.
Relative path: /messageDistribution/update Mode: POST Content-Type: application/json
Request JSON example:
{
"id": 1234, // Distribution identifier
"name": "Sample_name", // Name
"messageType": "SMS", // // Type of messages. "SMS" or "VIBER"
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Distribution text
"startTime": "2024-07-07 12:00:00" // Date and time of the delayed start. May be null, in which case it will be started immediately
}
Response in case of success:
{"status": "Success"}
Possible errors:
The project does not have a messaging service connected
Message sending service is not connected
id is not specified
The required id parameter is not specified
Message distribution not found
No distribution was found by the specified id
Message distribution completed
Distribution is already completed
The name cannot be empty or contain more than 45 characters
Distribution name is not specified or exceeds 45 characters
The name already exists
A distribution with that name already exists
Incorrect time format
The format of the startTime parameter is incorrect
Validation error
Validation errors. Possible causes: · Message type is not selected · SMS sending is disabled in the settings of the message sending service · Sending messages to Viber is disabled in the settings of the message sending service · Message cannot be empty · Message is too long · Message contains invalid characters
Removing a distribution
Сopied
To remove a distribution you need to specify its identifier in id parameter.
Relative path: /messageDistribution/remove Mode: POST Content-Type: application/x-www-form-urlencoded (It is also possible to send a request passing the parameters as url parameters, without a body)
Request example:
/messageDistribution/remove?id=1234
Response in case of success:
{"status": "Success"}
Possible errors:
id is not specified
The required id parameter is not specified
Pausing and unpausing a distribution
Сopied
To pause and unpause a distribution you need to specify its identifier in id parameter and an action in paused parameter: ·true – Pause; ·false – Unpause.
Relative path: /messageDistribution/setPaused Mode: POST Content-Type: application/x-www-form-urlencoded (It is also possible to send a request passing the parameters as url parameters, without a body)
Request example:
/messageDistribution/setPaused?id=1234&id=true
Response in case of success:
{"status": "Success"}
Possible errors:
id is not specified
The required id parameter is not specified
Message distribution not found
No distribution was found by the specified id
Message distribution completed
Distribution is already completed
Web Dialer
Сopied
To work with Chrome widget (hereinafter Web Dialer) methods grouped at the path /widget/ are used
Sending notifications to Web Dialer
Сopied
To send notifications to Web Dialer, you must specify: · An array of IDs of users to whom you want to display the notification in the userIds parameter; · At least one notification parameter in a data object.
Relative path: /widget/sendNotification Mode: POST Content-Type: application/json
Request JSON example:
{
"userIds": [ // An array of user IDs
1234,
...
],
"data": { // Notification parameters
"contactName": "John", // Contact name
"contactLink": "https://www.example-crm.com/leads/1", // Contact link
"entityName": "Best deal", // Name of the entity associated with the contact
"entityLink": "https://www.example-crm.com/deals/1", // Link to an associated entity
"responsible": "Manager #1" // Name of responsible manager
}
}
An example of response in case of success:
{
"status":"Success",
"data": {
"notificationId": 1234567890 // Sent notification ID
}
}
The notificationId parameter returned in data can be used to later hide sent notifications.
Possible errors:
No users was specified for notifications send
No user has been specified to send the notification
Data fields is all null
The value of any field of the object is not specified data
User with id *xxxx* not found
The user with the specified ID was not found
No users with connected chrome extension was found
The specified users have not connected Web Dialer
Hiding notifications in Web Dialer
Сopied
To hide sent notifications in Web Dialer, you must specify: · An array of IDs of users to whom you want to hide the notification in the userIds parameter; ·notificationId parameter, received when sending the notification.
Relative path: /widget/hideNotification Mode: POST Content-Type: application/json
Request JSON example:
{
"userIds": [ // An array of user IDs
1234,
...
],
"notificationId": 1234567890 // Target notification ID
}
Response in case of success:
{"status": "Success"}
Possible errors:
No users was specified for notifications hide
No user has been specified to hide the notification
NotificationId not specified
notificationIdnot specified
The specified users are not found or chrome extension not connected
The specified users are not found or they have not connected Web Dialer
Dictionaries
Сopied
Main Entities
Сopied
Retrieve the IDs and names of project entities:
POST: /dictionary?type=… Possible values for the type parameter:
IVR
ID and name of voice menus
INNER_PHONE
SIP line number and the name of the operator assigned to it
USER
ID and name of users
SITE
ID and name of sites
IN_SCENARIO
ID and name of inbound scenarios
OUT_SCENARIO
ID and name of outbound scenarios
TTS_PROFILE
ID and name of audio synthesis profile settings
STT_PROFILE
ID and name of speech recognition profile settings
PHONE_GROUP
ID and name of telephony departments
TRIGGER_ACTION
ID and name of event handlers
VOICE_ROBOT
ID and name of voice robots
MESSAGE_DISTRIBUTION
ID and name of message campaigns
CONTACT_FORMS
ID and name of contact forms
VOICE_ANALYTICS_PROFILE
ID and name of speech analytics profiles
AUDIO_ALL
ID and name of audio of all types
AUDIO_GENERAL
ID and name of audio with type “Scenarios”
AUDIO_IVR
ID and name of audio with type “Voice Menus”
AUDIO_AUTODIAL
ID and name of audio with type “Autodial”
AUDIO_MELODY
ID and name of audio with type “On-hold and Queue Melodies”
AUDIO_API
ID and name of audio with type “API Calls”
AUDIO_VOICE_ROBOT
ID and name of audio with type “Voice Robots”
AUDIO_VOICE_QUEUE
ID and name of audio with type “Voice Queue Calls”
AUTODIAL_ALL
ID and name of autodials of all types
AUTODIAL_AUTODIALER
ID and name of autodials with type “Autodialer”
AUTODIAL_PREDICTIVE
ID and name of autodials with type “Predictive Dialing”
AUTODIAL_ROBOT
ID and name of autodials with type “Voice Robot Dialing”
