Справочный центр
Справочный центр
Блокировка нежелательных звонков
Документация API
Интеграция с Битрикс24
Подключение интеграции Битрикс 24 Функциональность интеграции Виджет для звонков в Битрикс24 Импорт сотрудников из Bitrix24 Всплывающая карточка контакта в Битрикс 24 Персональный менеджер из Битрикс 24 Распределение звонков по данным из Битрикс24 Интеграция с Софтфоном UIS Исходящий звонок из Битрикс 24 по клику на номер Отчет по всем звонкам Настройка передачи заявок с сайта Настройка передачи чатов Интеграция в режиме «Другая телефония» Загрузка записей разговоров в Битрикс 24 Автоматическое создание Лида и Дела в Битрикс 24 Обработка потерянных звонков в интеграции с Битрикс 24 Назначение ответственного за потерянные обращения в Битрикс24 Автозвонки по событию из Битрикс 24 Единая точка входа в компанию. Фильтрация обращений, передаваемых в Битрикс24 Передача сделок из Битрикс24 в UIS Управление дополнительными полями в интеграции с Битрикс 24 Обработка звонков, заказанных через «Обратный звонок» в Битрикс24 Работа с Коллтрекингом Битрикс 24 Сквозная аналитика: Битрикс24
Интеграция с отраслевыми CRM
1С: Медицина Стоматологическая клиника - Программа для стоматологии Интеграция с 1С: Фитнес Клуб 4Logist - CRM для транспорта и логистики APIX-DRIVE - онлайн коннектор сервисов и приложений Bnovo — система управления гостиницей, отелем, хостелом и апартаментами с подключением модулей и каналов онлайн-бронирования номеров Brizo - CRM система и управленческий учет для бизнеса CRM Systems - CRM для агентского бизнеса DarWin - CRM и BPM система в одном решении Инструкция для подключения интеграции МИС Dentist Plus и UIS DentalBase - облачная CRM для стоматологии Future-IT-Dent - уникальная система управления и автоматизации стоматологии 32top - Облачная МИС для стоматологий МИС Инфоклиника Инфоклиника - Сквозная аналитика DIKIDI – онлайн запись в салоны красоты E-Staff - CRM для подбора персонала EnvyCRM - универсальная CRM FinKoper - CRM для бухгалтерского бизнеса Flowlu - Управление проектами онлайн и CRM Gincore - облачная программа для сервисного центра или мастерской HOLLIHOP - CRM для учебных центров IDENT - Управление клиникой MEDIDEA - медицинская информационная система MegaCRM - управление продажами и заявками Neaktor - система управления проектами Okdesk - Help Desk система учета и управления заявками Omnidesk - сервис для поддержки и общения с клиентами SaleBot - Конструктор чат-ботов SalesapCRM (S2) - облачная CRM для отдела продаж SalesPlatform – облачная CRM-система для автоматизации бизнеса SberCRM StomX - программа для стоматологии Synergy CRM - облачная CRM для отдела продаж U-ON Travel - CRM для турбизнеса WireCRM - модульная система для автоматизации продаж YCLIENTS - онлайн запись и автоматизация процессов YUcrm - CRM для недвижимости Автошкола-Контроль - облачный сервис для комплексной автоматизации автошколы АльфаCRM - CRM для детского учебного центра и школы Квартира.Бурмистр.Ру – автоматизация работы бизнеса в сфере ЖКХ (УК, ТСЖ) Клиентикс CRM МИС Medesk - медицинская CRM МИС MEDODS - медицинская CRM МойСклад - торговля, склад и CRM в облаке ПланФикс - платформа для создания системы управления предприятием Програмбанк.ФронтОфис - CRM для банков ПрофСалон - Программа для салонов красоты и бьюти индустрии РемОнлайн - программа для учета и автоматизации бизнеса в сфере услуг РосКвартал - АДС на 100% - современная диспетчерская для УК Юздеск - система автоматизации работы с заявками
Интеграция с сервисами автоматизации и управления контекстной рекламой
Настройка UIS на турбо-сайтах
Отслеживание звонков и аналитика
Добавление турбо-сайта в UIS Настройка номеров для подмены на турбо сайтах Яндекс Алгоритм отслеживания звонков Настройка автоматического выбора номера Настройка рекламных кампаний Настройка динамического отслеживания звонков Добавление сайта и установка кода CoMagic Интеграция с Яндекс.Метрика в новом ЛК Инструменты маркетолога: Анализ сделок Настройка сегментов посетителей Общие настройки сайта Настройка динамического коллтрекинга Связь целей со сделками в CRM Дополнительные настройки коллтрекинга: номера-ссылки для мобильной версии Настройка подмены номера Подмена номера в динамически подгружаемых блоках Привязка телефонного номера к рекламной кампании Сохранение переадресации Резервные номера Коллтрекинг на AMP-страницах Управление номерами Настройка событий (целей) Алгоритм учета посетителей Автоперезвон по заявкам Определение канала трафика Виды обращений Инструменты маркетолога: Сквозная аналитика Инструменты маркетолога: Анализ трафика Инструменты маркетолога: Аудитория Инструменты маркетолога: Содержание Список обращений: Цели Отчет Список сделок Свойства посетителя: добавление, проверка, удаление Что делать, если расходятся данные по посещениям Дополнительные настройки отслеживания звонков: номера - ссылки для мобильной версии Автоматический выбор номера в динамически прогружаемых блоках Настройка промокода Интеграция с Universal Analytics Передача событий UIS и настройка целей в Universal Analytics Интеграция с OWOX BI Pipeline Интеграция с Google AdWords Интеграция с Google Analytics 4 Интеграция с Яндекс.Метрикой Настройка и передача статических UTM-меток для обращений Расчет охвата рекламных кампаний Инструменты атрибуции: Ассоциированные конверсии Инструменты атрибуции: Модели атрибуции Инструменты маркетолога: Воронки продаж
Справочный центр
Продукты Решения Тарифы Партнерам Блог
Получить консультацию
Связаться
Skip to content

Call API

Знакомство

Введение

Настоящий документ описывает Call API, которое позволяет совершать звонки и управлять ими. Настоящий документ описывает Call API, которое позволяет совершать звонки и управлять ими.

Управлять можно так же звонками, которые поступили на виртуальную АТС. Для этого необходимо получить уникальный идентификатор сессии звонка. Его можно получить с помощью сервера уведомлений, DATA API.

API реализован на основе спецификации JSON-RPC 2.0 без поддержки групповых операций.

При запросах к API в качестве транспортного протокола используется HTTP/1.1 с защитой соединения с помощью SSL/TLS, при этом соблюдая следующие требования:

  • Заголовок Content-Type должен быть application/json; charset=UTF-8
  • Заголовок Content-Length должен содержать корректную длину сообщения, следуя спецификации HTTP/1.1

Соглашения

Приняты следующие соглашения:

  • Пустые поля всегда возвращаются в ответе со значением null. В случае массива возвращается пустой массив, в случае объекта возвращается пустой объект;
  • Все поля связанные с датой и временем передаются согласно ISO 8601 в формате YYYY-MM-DDT hh:mm:ssZ;
  • Запросы к API выполняются всегда с помощью метода POST;
  • Все параметры в запросах/ответах, а также в структурах данных в формате JSON и название методов именуются в стиле Snake Case - разделение слов через нижнее подчеркивание;
  • Данные возвращаются только в JSON формате согласно спецификации RFC 7159;
  • Кодировка данных UTF-8;

Добавить IP-адрес в список разрешенных

По умолчанию доступ к API запрещен всем, чтобы можно было делать запросы необходимо IP-адрес хоста с которого делается запрос добавить в белый список. Это можно сделать через личный кабинет "Администратор -> Аккаунт -> Правила и настройки безопасности" вкладка "API".

Пользователи Call API

В личном кабинете "Аккаунт" -> "Управление пользователями" при подключенном компоненте Call API Базовый набор появляется возможность выбора нового набора прав доступа в виде чек-бокса Доступ к Call API.

Все эти действия могут быть выполнены только администратором.

Доступ по логину и паролю

Используется аутентификация по логину и паролю пользователя, в ответе будет получен ключ доступа к Call API

Время жизни сессии по умолчанию 1 час.

Доступ по ключу

В настройках пользователя есть возможность включить доступ по ключу, для этого необходимо в настройках пользователя поставить галку "Доступ по ключу". При этом, будьте внимательны: ключ виден в интерфейсе и доступен для копирования только в момент генерации, после сохранения настроек вы сможете его увидеть только в коде своего приложения или другом месте, куда вы сохранили этот ключ.

Ключи могут действовать до определенной даты или быть бессрочными, в зависимости от ваших настроек.

Статистика и отчеты

В личном кабинете "Отчеты" -> "Служебные" -> "Запросы к API" можно видеть все запросы к API, кроме запросов, которые закончились ошибками:

  • Если возвращются ошибки валидации JSON или структуры запроса - мнемоника "parse_error" или "invalid_request";
  • Если возвращается ошибка на вызов метода, который не существует - мнемоника "method_not_found";
  • Если возвращается ошибка связанная с аутентификацией - "access_token_blocked", "access_token_invalid", "access_token_expired", "auth_error";
  • Если возвращается ошибка при запросе с IP адреса, который не в белом списке - мнемоника "ip_not_whitelisted".

Полную информацию по звонку можно найти в "Отчеты" -> "Обращения" -> "Звонки" с фильтрацией по параметру "Индентификатор сессии звонка"

Если в фильтрах отсутствует параметр "Идентификатор сессии звонка", то его нужно добавить в доступные столбцы отчета

Управление безопасностью звонка

Управлять безопасностю звонков (мобильные, междугородние, международные направления) можно в личном кабинете на странице "Аккаунт" -> "Правила и настройки безопасности" -> "API".

По умолчанию запрещено международное направление, остальные направления разрешены.

Разрешения для направлений звонка разбиты по компонентам Call API (см. Компоненты)

Компоненты

Название для клиента Список методов Описание
Call API Базовый набор start.employee_call, start.vnumber_call, start.simple_call, login.user, logout.user, release.call Базовый пакет Call API
Call API Управление вызовами hold.call, unhold.call, make.call, disconnect.leg, tag.call, record.call, add.coach, list.calls, send.dtmf, block.contact, restore.talk, transfer.talk, list.talk_options, call.talk_option Пакет позволяет управлять звонками.
Call API Информационный вызов start.informer_call Пакет, который позволяет обзванивать клиентов и проигрывать им TTS или какой-то предустановленный файл. После окончания информационного сообщения вызов завершается
Call API Вызов сценария start.scenario_call Пакет, который позволяет совершать вызовы клиенту с использованием одного виртуального номера и набора сценариев.

Формат возвращаемых данных

Формат MIME Type
JSON application/json

По умолчанию используется формат JSON. Заголовок Accept игнорируется

Базовый URL для доступа к API

Базовый URI для доступа к API:

Копировать
https://callapi.uiscom.ru/<version>

или

Копировать
https://callapi.comagic.ru/<version>

где

<version> - версия API (см. раздел Версионность)

Версионность

Call API поддерживает версионность. Версия указывается в базовом URL как vX.Y, где X - номер мажорной версии, Y - номер минорной версии

Версия должна указываться через точку, к примеру 4.0

Если была выпущена новая версия, то старая считается устаревшей и соответственно при обращении к старой версии API в мета-параметрах (см. раздел Мета-параметры) будет возвращаться параметр current_version_depricated со значением true. Это говорит о том, что в ближайшие пару месяцев старая версия может стать недоступной.

Пример:

Копировать
https://callapi.comagic.ru/v4.0 \b https://callapi.comagic.ru/v4.0

Максимальное количество поддерживаемых версий - 2 Период поддержки устаревшей версии 2 месяца

Лимиты и ограничения

Лимиты построены по бальной системе, т.е каждый метод имеет свой вес в баллах.

Баллы списываются только за успешные запросы, т.е в отчете по запросам он помечен как успешный. Успешным считается запрос, если в result был возвращен статус success = true или идентификатор сессии звонка

Лимиты привязаны к компоненту Call API Базовый набор (см. Компоненты) и учитываются в зависимости от стоимости метода в баллах

Информация о лимитах возвращается во всех ответах в мета-парметрах (см. Мета-параметры), кроме случаев когда лимиты не учитываются;

  • Если возвращются ошибки валидации JSON или структуры запроса - мнемоника "parse_error" или "invalid_request";
  • Если возвращается ошибка на вызов метода, который не существует - мнемоника "method_not_found";
  • Если возвращается ошибка связанная с аутентификацией - "access_token_blocked", "access_token_invalid", "access_token_expired", "auth_error";
  • Если возвращается ошибка при запросе с IP адреса, который не в белом списке - мнемоника "ip_not_whitelisted".

Информация о лимитах возвращается в мета-параметрах (см. Мета-параметры)

Расширение лимитов

Лимитами можно управлять в личном кабинете на странице "Аккаунт" -> "Тарифы и опции".

Название лимитов:

  • Баллов Call API в минуту;
  • Баллов Call API в день;
  • Длина TTS сообщения.

Отсутствие лимитов в личном кабинете может быть связанно с тем, что имеются ограничения в тарифном плане. В этом случае необходимо связаться с персональным менеджером или службой технической поддержки.

Мета-параметры

Возвращаются в ответ на вызов метода. Присутствуют как в ошибочном, так и в успешном ответе

Параметр api_version возвращается только для версий которые deprecated.

Описание параметров

Название параметра Описание
day_limit Текущие лимит баллов в день
day_remaining Какое количество баллов осталось до достижения дневного лимита
day_reset Время в секундах через которое дневной лимит будет сброшен
minute_limit Текущие лимит баллов за минуту
minute_remaining Какое количество баллов осталось до достижения минутного лимита
minute_reset Время в секундах через которое минутный лимит будет сброшен
current_version_depricated Признак, говорящий, что в ближайшие пару месяцев старая версия может стать недоступной.
current_version Вызванная версия
latest_version Последняя доступная версия

JSON структура

Копировать
"metadata": {
 "api_version": {
  "current_version_depricated": "boolean",
  "current_version": "string",
  "latest_version": "string"
 },
 "limits": {
  "day_limit": "number",
  "day_remaining": "number",
  "day_reset": "number",
  "minute_limit": "number",
  "minute_remaining": "number",
  "minute_reset": "number"
 }
}

Общее

Общие поля для всех методов

Название Тип Обязательный Допустимые значения Описание
id string или number да Уникальный идентификатор запроса к API.
Не передается в уведомлениях. Фигурирует только в Статистика и отчеты параметр Идентификатор запроса
method string да Вызываемый метод (см. Список методов)
jsonrpc string да 2.0 Номер спецификации JSON-RPC
params object да Содержит тело запроса к API. В зависимости от вызываемого метода тело запроса меняется.

Диаграмма состояний звонка

Аутентификация

Метод Описание
"login.user" Вход
"logout.user" Выход и удаление ключа сессии аутентификации

Группа методов создания звонков

Метод Описание
"start_employee_call" Метод создает прямой звонок абонента с сотрудником без использования сценария.
"start.scenario_call" Метод создает звонок согласно настроенному сценарию. Для использования метода достаточно одного виртуального номера и N сценариев.
"start.vnumber_call" Вызов на виртуальный номер.
"start.informer_call" Информационный вызов с возможностью проиграть абоненту файл или текстовое сообщение. После окончания проигрывания сообщения вызов завершается автоматически.
"start.simple_call" Звонок на любые номера кроме собственных виртуальных. Это не звонок сотрудника на любой номер.

Группа методов управления вызовами

Метод Описание
"make.call" Создать звонок для трансфера или консультации.
"transfer.talk" Метод позволяет произвести трансфер звонка другому сотруднику или на внешний номер (см. раздел "Диаграмма состояний звонка").
"restore.talk" Метод позволяет вернуться в разговор с абонентом после получения консультации от другого сотрудника (см. раздел "Диаграмма состояний звонка").
"hold.call" Постановка вызова на удержание.
"unhold.call" Снятие вызова с удержания.
"tag.call" Простановка тега для активного вызова.
"disconnect.leg" Метод позволяет разъединять отдельных участников разговора. Уникальный идентификатор каждого участника разговора можно получить используя метод list.calls или сервер уведомлений.
"add.coach" Подключение тренера к разговору.
"record.call" Управление записью разговора. Отключить запись разговора, настроенную через личный кабинет невозможно.
"block.contact" Занести абонента в черный список во время разговора.
"call.talk_option" Вызов опции разговора, которая настроена в Личном кабинете виртуальной АТС.
"send.dtmf" Отправка DTMF сотрудником. Метод Используется в случае, если на стороне клиента есть IVR и требуется выбрать в нем пункт меню.
"list.talk_options" Получение списка опций разговора настроенных в Личном кабинете виртуальной АТС.
"list.calls" Получить список активных вызовов и их участников.
"release.call" Завершение звонка.

Группы кодов ошибок

Код ошибки Описание
-32700 Ошибки связанные с валидацией JSON
-32600 Ошибки связанные с валидацией параметров запроса - id, jsonrpc
-32601 Ошибки связанные с методом
-32602 Ошибки связанные с валидацией параметров в вызываемом методе
-32603 Внутренние ошибки JSON RPC сервера
В случае возникновения ошибки, необходимо обратиться в службу технической поддержки, передав запрос, который вызвал ошибку и время запроса.
-32001 Ошибки аутентификации и ошибки с ключами
-32002 Ошибки связанные с: правила безопасности запрещают звонок по указанному направлению (см. раздел Правила безопасности) и черным списком
-32003 Ошибки с правами доступа - ip адрес не в белом списке, нет прав у пользователя
-32004 Ошибки связанные с неверной последовательностью вызываемых методов
-32007 Ошибки связанные с виртуальным номером
-32008 Ошибки связанные с компонентами
-32009 Ошибки связанные с аккаунтом
В случае возникновения ошибки, необходимо обратиться в службу технической поддержки, передав запрос, который вызвал ошибку и время запроса.
-32029 Ошибки связанные с лимитами
-32099 Ошибки связанные с поддержкой различных частей спецификации JSON RPC 2.0 - Групповые операции, Уведомления

Список ошибок общих для всех методов

Текст сообщения Код Мнемоника Описание
Invalid Request The JSON sent is not a valid Request object -32600 invalid_request Ошибки связанные с валидацией параметров запроса - id, jsonrpc
Access token has been expired -32001 access_token_expired Применяется только к постоянному токену. Если время жизни постоянного токена истекло, то возвращается указанная ошибка
Access token has been blocked -32001 access_token_blocked Если постоянный токен заблокирован, то возвращается указанная ошибка
Access token is invalid -32001 access_token_invalid Указанная ошибка возвращается, если постоянный/временный токен не найден или истекло время жизни временного токена
Limit per {limit_type} has been exceeded. Value of current limit per {limit_type} is {limit_max_value} -32029 limit_exceeded Превышены установленные лимиты согласно тарифного правила (см. раздел Лимиты и ограничения)
Component {component_name} has been disabled -32008 component_disabled
Your IP {ip} is not whitelisted -32003 ip_not_whitelisted IP адрес, с которого идет запрос не находится в белом списке (см. личный кабинет "Аккаунт" -> "Call API" вкладка "IP адреса"
Login or password is wrong -32001 auth_error Некорректный логин или пароль
Your account has been disabled, contact the support service -32009 account_inactive Аккаунт заблокирован
В случае возникновения ошибки, необходимо обратиться в службу технической поддержки, передав запрос, который вызвал ошибку и время запроса.
Call session not found -32602 call_session_not_found Если передали ID сессии, который неизвестен
Internal error, contact the support service -32603 internal_error
В случае возникновения ошибки, необходимо обратиться в службу технической поддержки, передав запрос, который вызвал ошибку и время запроса.
Data supplied is of wrong type -32602 data_type_error К примеру, если ожидаем string а передали int
The method does not exist / is not available -32601 method_not_found Вызывается метод, который отсутствует в спецификации (см. раздел Список методов)
Permission denied -32003 forbidden Нет прав на доступ к методу или API, или запрещено выполнять какое-либо действие
Invalid JSON was received by the server. -32700 parse_error Невалидный JSON
Batch operations not supported -32099 batch_opreations_not_supported Групповые операции не поддерживаются (см. JSON-RPC 2.0)
Notifications not supported -32099 notifications_not_supported Уведомления не поддерживаются (см. JSON-RPC 2.0)
The required parameter has been missed -32602 required_parameter_missed Обязательный параметр не передали
Invalid parameter value -32602 invalid_parameter_value Возвращается во всех случаях, если было передано некорректное значение параметра или переданное значение не соответствует требуемому формату ввода
Unexpected method parameter(s) -32602 unexpected_parameters Если в params были переданы параметры, которые не предусмотрены JSON структурой метода
Полезные кейсы, статьи и исследования от экспертов UIS
Подписаться
Вы успешно подписаны на новости!
Спасибо за обращение
Понятно