[article_list depth:2]
**Термины и сокращения**
- ВАТС – виртуальная АТС, которая используется для приема и обработки телефонных вызовов
- Приложение – программное обеспечение, с которым ВАТС будет взаимодействовать п процессе получения и обработки вызовов
- Интеграция – согласованный протокол взаимодействия между ВАТС и Приложением
- Token – случайный набор данных, используемый для формирования запросов между ВАТС и Приложением
**Принципы взаимодействия**
Интеграция построена на базе протокола HTTP и WebSocket.
Запросы к АТС возможно выполнить только с использованием SSL.
Часть интеграции можно выполнить с использованием WebSocket. Это позволит значительно сократить время обработки событий и повысит комфорт работы сотрудников.
Для WEB приложение возможно подключение телефона непосредственно в браузере.
**Запросы и ответы**
Все запросы и ответы выполнены в едином формате. Запросы через http передаются методом POST, с указанием ключа crm_token и тела запроса.
В теле запроса обязательно должны присутствовать поля: action, type, action_id и прочие данные, если один необходимы для выполнения запроса
В теле ответа обязательно должны присутствовать поля: action, type, action_id, code и прочие данные, полученные при выполнении запроса.
Пример запроса
curl -i -X POST \
-H "Content-Type:application/json" \
-H "X-Token:crm_token" \
-d \
'{"token": "PBX_TOKEN", "url": "https://vpbx.operator.com/integration/usercrm/", "action": "install", "type": "cmd", “action_id”: “123123123”}' \
'https://example.com/some/'
Пример ответа
Успешный ответ:
{“action_id”: “some_id”, "action": " list_ext_users", "type": "response", “code”: “0”, “text”: “”, “users”: {“user_id_1”: “user_name_1”, “user_id_2”: “user_name_2”}}
Ответ с ошибкой
{“action_id”: “some_id”, "action": "find_by_phone", "type": "response", “code”: “2”, “text”: “Ошибка получения. Блокировка базы данных.”}
Ответ содержит обязательное поле code, по которому можно определить успешность выполнения запроса
0 – успешный запрос
1 – Ошибка разбора запроса
2 – Ошибка выполнения запроса
При получении code равному 1 или 2 необходимо указать текст ошибки в понятном пользователю формате.
**Описание Интеграции**
**Процесс взаимодействия состоит из отдельных этапов**
- Подключение интеграции в ВАТС
- Получение списка пользователей Приложения
- Подключение WebSocket
- Получение от Приложения ответственного сотрудника по номеру телефона клиента
- Отправка событий ВАТС в Приложение. Список событий устанавливается на этапе установки интеграции
- Инициализация исходящего вызова
- Получение истории звонков
- Получение файлов с записью разговоров
- Заказ обратного звонка
- Управление конференцией
**Подключение интеграции в ВАТС**
Интеграция включается в личном кабинете ВАТС. Раздел Плагины => Персональное API
Обязательными к заполнению являются поля:
- CRM_TOKEN – Token, который будет использоваться для формирования запросов
- CRM_URL – Адрес, по которому будет отправляться запрос к Приложению
После заполнения полей нажмите кнопку «Установка интеграции». Результатом должно быть уведомление, что подключение к приложению выполнено успешно или же будет показана ошибка.
При выполнении запрос ВАТС отправляет Приложению запрос, где
- url для отправки запросов к ВАТС
- token – ключ ВАТС
Запрос:
curl -i -X POST \
-H "Content-Type:application/json" \
-H "X-Token:crm_token" \
-d \
'{"token": "PBX_TOKEN", "url": "https://vpbx.operator.com/integration/usercrm/", "action": "install", "type": "cmd", “action_id”: “123123123”}' \
'https://example.com/some/'
Успешный ответ:
{“action_id”: “123123123”, "action": "install", "type": "response", “code”: “0”, “text”: “Интеграция успешно завершена”,
“http_events”: [“call_state”, “agent_status”, “user_status”],
“ws_events”: [“call_state”, “agent_status”, “user_status”],
}
В поле http_events и ws_events необходимо указать список событий, которые необходимо отправлять через http и ws соответственно.
Ответ с ошибкой
{“action_id”: “123123123”, "action": "install", "type": "response", “code”: “2”, “text”: “Интеграция запрещена”}
**Подключение WebSocket**
В некоторых ситуациях удобнее использовать ws на стороне клиентского подключение к Приложению. Для подключения к WS небходимо выполнить запрос по адресу WSS:// vpbx.operator.com/integration/usercrm/ws/ и в первом запросе отправить запрос авторизации
{"type":"cmd","action":"auth","action_id":"bcab5f14-e58b-c9e9-47ad-1e5f0519a18f","token":"at6TcBUmOcKN3eUdFlb8BHbrIKwp5D0YmQaey","user_id":645465}
в случае успешной авторизации будет получен ответ
{"type": "response", "action": "auth", "action_id": "bcab5f14-e58b-c9e9-47ad-1e5f0519a18f", "code": 0, "event_before_answer": true, "pbx_user": "1005@testpbx.runtel.ru", "pbx_user_protocol": "WEB", "secret": "g2FeTyrkGdW9", "user_id": "645465"}
В случае использования Web телефона ВАТС может передать дополнительно авторизационные данные и параметр отображать анкету на этапе звонка.
Следом придет ответ, в котором будет информаци о регистрации пользователя
{"type": "event", "action": "user_status", "action_id": "88047031-be96-4b96-9348-0aa56ae22770", "code": 0, "status": "", "text": "", "register": "verto"}
**Получение списка пользователей**
Для установления связи между пользователями Приложения и учетными записями ВАТС используется запрос следующего вида:
curl -i -X POST \
-H "Content-Type:application/json" \
-H "X-Token:crm_token" \
-d \
'{"action": "list_ext_users",
"type": "cmd",
"action_id": "some_id"}' \
'https://example.com/some/'
Успешный ответ:
{“action_id”: “some_id”, "action": " list_ext_users", "type": "response", “code”: “0”, “text”: “”, “users”: {“user_id_1”: “user_name_1”, “user_id_2”: “user_name_2”}}
Ответ с ошибкой
{“action_id”: “some_id”, "action": " list_ext_users", "type": "response", “code”: “2”, “text”: “Ошибка получения списка пользователей. Блокировка базы данных.”}
**Получение информации по номеру звонящего.**
При получении входящего вызова АТС можно запросить у Приложения информацию о звонящем. Эта информация будет использована для фиксации событий в карточке клиента и для перевода звонка на ответственного менеджера. Во входящий маршрут необходимо добавить элемент «Получение данных из CRM»
Запрос:
curl -i -X POST \
-H "Content-Type:application/json" \
-H "X-Token:crm_token" \
-d \
'{"action": "find_by_phone",
"type": "cmd",
"action_id": "some_id",
"phone": "+79204831153",
"gw": "+74732123123"}
' \
'https://example.com/some/'
Успешный ответ:
{“action_id”: “some_id”, "action": " find_by_phone", "type": "response", “code”: “0”, “text”: “”, “data”: [
{"id": “123”, "type": “lead”, "name": “Петров АВ”, "owner_id": “user_id_1”, "company_id": “company_id_1”, "company_name": “company_name”}],
{"id": “1232”, "type": “contact”, "name": “Иванов”, "owner_id": “user_id”, "company_id": “company_id”, "company_name": “company_name”}],
{"id": “1233”, "type": “company”, "name": “ООО Ромашка”, "owner_id": “user_id”, "company_id": “company_id”, "company_name": “company_name”}],}
Ответ с ошибкой
{“action_id”: “some_id”, "action": "find_by_phone", "type": "response", “code”: “2”, “text”: “Ошибка получения. Блокировка базы данных.”}
**Инициализация исходящего вызова**
Инициализация вызова из Приложения зависит от типа пользователя ВАТС и от схемы интеграции.
В случае Web Приложения можно встроить телефон в само приложение и тогда отправка запроса на необходима только для установления данных по контакту, из которого совершается вызов. Сам же вызов будет совершаться средствами web телефона.
Если звонок должен выполнить SIP пользователь, то запрос носит обязательный характер.
Пример запроса:
curl -i -X POST \
-H "Content-Type:application/json" \
-H "X-Token:crm_token" \
-d \
'{"action": "make_call",
"type": "cmd",
"action_id": "some_id",
"user_id": "46484d8e-b262-11e7-9097-001517a211ff",
"phone": "+79525557202",
"call_id": "0",
"element_id": "970c61ec-2a64-11e7-914a-001517a211ff",
"element_type": "company",
"element_name": "Тест 1с"
}' \
'https://example.com/some/'
Успешный ответ:
{"action": "make_call", "type": "response", "action_id": "some_id", text: “None”, “call_id”: “123”}
Ответ с ошибкой
{“action_id”: “some_id”, "action": "make_call", "type": "response", “code”: “2”, “text”: “Ошибка инициализации вызова. Не доступен пользователь”}
**Получение истории звонков**
Для получения истории вызовов необходимо выполнить запрос
curl -i -X POST \
-H "Content-Type:application/json" \
-H "X-Token:crm_token" \
-d \
'{"action": "cdr",
"type": "cmd",
"action_id": "some_id",
"limit": "250",
"page": "1",
"phone_exact": "+79123456789",
"phone": "7202",
"start_epoch": 1501668611,
"end_epoch": 1509444611
}' \
'https://example.com/some/'
Успешный ответ
{"action": "cdr",
"type": "cmd",
"action_id": "some_id",
"limit": "250",
"page": "1",
"phone_exact": "+79123456789",
"phone": "7202",
"start_epoch": 1501668611,
"end_epoch": 1509444611
“response”: [
{'dst': '+79601309563', 'status': 'answered', 'src': 'a_number', 'duration': '23', 'id': '1822', 'calldate': 1509119560.0, 'mp3': '8a911feb-bc2d-4011-a570-9a3ea48a6dab', 'direction': 'outdound', 'rec': 'link_to_mp3'}
]}
**Отправка событий ВАТС в Приложение.**
При установке Интеграции в ответ на запрос к Приложению мы получаем информацию о подписке на события в разрезе канала получения.
Поддерживаются следующие события:
• События по статусам звонка – call_status
• Состояние агента – agent_status
• Состояние пользователя – user_status
Пример события
{"type": "event", "action": "call_state", "action_id": "cc273d35-90c4-4735-89e6-c328183f3188", "code": 0, "status": "ringing", "text": "", "call_id": "ed2da6f4-1a07-4498-a954-cc37350c6476", "direction": "inbound", "element_id": null, "element_name": null, "element_type": null, "founded_contacts": [], "phone": "+74951343060", "session_id": "4abefc1a-cf75-49ab-947d-49162e384a90", "user_id": "645465", "user_number": "1005"}
Пример события по агенту
{"type": "event", "action": "agent_status", "action_id": "778172da-fe7c-4a82-87ed-910e1251ae6b", "code": 0, "status": "NA", "text": "", "user": "1005"}
Пример по события user_state
{"type": "event", "action": "user_status", "action_id": "788616cf-8b7a-4b11-b4c3-0e7ccba938c2", "code": 0, "status": "", "text": "", "register": "verto"}
