Порядок интеграции виртуальной АТС с системой

Скопировать ссылку на статью

Скопировано

• Возможности интеграции системы и виртуальной АТС
• Регистрация и настройка телефонии
• Получение информации о телефонии
• Загрузка истории звонков
• Получение ответственного менеджера
• События звонков
• Инициация звонка
• Уведомление о смене статуса пользователя в системе

Возможности интеграции retailСRM и виртуальной АТС

API системы для телефонии позволяет:

1. Инициировать звонок из системы
2. Загружать в систему историю звонков
3. Получать ответственного менеджера по номеру телефона для маршрутизации входящего звонка
4. Уведомлять систему о событиях звонка

Работа с API производится в соответствии с правилами работы с API. Для интеграции используются API-методы секциий Телефония и Пользователи.

Алгоритм интеграции виртуальной АТС и системы:

• USER Запросить у пользователя API-ключ доступа к системе
• API Зарегистрировать новую телефонию
• API | USER Заполнить добавочные номера пользователям системы или задать соответствие при регистрации телефонии
• API | USER Заполнить внешние номера телефонов или задать соответствие при регистрации телефонии
• API Выгружать историю звонков из виртуальной АТС в систему
• API При распределении звонков использовать данные об ответственном менеджере
• API Отправлять в систему уведомления о событиях звонков

Этапы с пометкой USER — это этапы, где данные предоставляются или заполняются пользователем. Остальные этапы с пометкой API выполняются посредством API-запросов.

Регистрация и настройка телефонии

Регистрация новой телефонии, а также изменение настроек существующей производится с помощью метода POST /api/v5/integration-modules/{code}/edit. Если телефония с кодом code уже существует, метод меняет ее настройки, в противном случае создается новая телефония. При регистрации телефонии передается уникальный код clientId, который будет позволять идентифицировать телефонии аккаунт системы.

Если в поле allowEdit передать false, редактирование настроек интеграции будет возможно только через API. Пользователям системы будет доступно только удаление интеграции.

В поле makeCallUrl передается адрес, на который система будет отсылать запросы для инициации звонка.

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

С помощью параметра personalAccountUrl можно передавать URL для перехода в личный кабинет телефонии.

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

Добавочные коды

Настроить соответствие добавочных кодов и пользователей можно двумя способами:

• Через API, заполнив поле additionalCodes в методе создания/редактирования телефонии.
• Через интерфейс настроек. Необходимо зайти в Маркетплейс и перейти на страницу редактирования нужной телефонии. В разделе Добавочные коды необходимо прописать добавочные номера для тех сотрудников компании, которые будут принимать/инициировать звонки.

Если в настройках телефонии заполнено поле makeCallUrl и у авторизованного пользователя системы указан добавочный код, на страницах появится иконка трубки для звонка.

Внешние номера

Настроить соответствие внешних номеров и магазинов можно двумя способами:

• Через API, заполнив поле externalPhones в методе создания/редактирования телефонии.
• Через интерфейс настроек. Необходимо зайти в раздел Маркетплейс и перейти на страницу редактирования нужной телефонии. В разделе Внешние номера необходимо настроить соответствие магазина внешнему номеру.

Если в настройках телефонии заданы внешние номера, и звонок инициируется из сущности связанной с магазином, при инициации звонка на адрес makeCallUrl будет передан параметр externalPhone.

Если в событии звонка указан параметр externalPhone, и в настройках телефонии присутствует этот внешний номер, в всплывающем окне будет отображена информация о направлении звонка. Например в Магазин 1.

Пример создания/редактирования телефонии

Например, есть система https://example.retailcrm.ru. В системе заведены два пользователя с ID 1, 2 и два магазина с символьными кодами shop1, shop2.

На стороне телефонии заведены добавочные номера 100, 200 и внешние номера +7-499-999-99-99, +7-499-888-88-88.

Для создания/редактирования телефонии с кодом my-telephony нужно отправить POST-запрос на адрес https://example.retailcrm.ru/api/v5/integration-modules/my-telephony/edit

c параметром integrationModule, в качестве значения JSON:

{
    "code": "my-telephony",
    "active": true,
    "name": "Название телефонии",
    "logo": "http://api.telephony-test.ru/logo.svg",
    "clientId": "2dbh26tahjj26sg",
    "accountUrl": "http://api.telephony-test.ru/settings",
    "integrations": {
        "telephony": {
            "makeCallUrl": "http://api.telephony-test.ru/make-call",
            "allowEdit": false,
            "inputEventSupported": true,
            "additionalCodes":[
                {"userId":"1", "code":100},
                {"userId":"2", "code":200}
            ],
            "externalPhones":[
                {"siteCode":"shop1", "externalPhone":"+7-499-999-99-99"},
                {"siteCode":"shop2", "externalPhone":"+7-499-888-88-88"}
            ],
            "changeUserStatusUrl": "http://api.telephony-test.ru/change-status"
        }
    }
}

Ответ

HTTP/1.1 201 OK

{
  "success": true
}

Получение информации о телефонии

Получение информации о интеграции с телефонией производится с помощью метода GET /api/v5/integration-modules/{code}

Загрузка истории звонков

Для загрузки истории необходимо использовать метод POST /api/v5/telephony/calls/upload. За один запрос можно сохранить до 50 звонков. АТС может загружать историю, используя одну из двух стратегий:

Загрузка истории сразу же после звонка

После факта совершения исходящего или входящего звонка АТС отправляет в системы историю по данному звонку. Таким образом в запросе, как правило, будет передаваться одна запись истории.

Периодическая загрузка истории звонков

АТС периодически (например, раз в 10 минут) отправляет в систему историю звонков, которые накопились с момента предыдущей загрузки.

Записи звонков

В поле calls[][recordUrl] передается ссылка на запись звонка.

При попытке прослушать звонок система посылает GET-запрос на адрес calls[][recordUrl] с параметрами:

• clientId — уникальный код системы, переданный при регистрации телефонии, подробнее в статье.

Для корректного воспроизведения аудиозаписи необходимо указывать верный заголовок Content-Type.

Получение ответственного менеджера

Метод GET /api/v5/telephony/manager позволяет передать номер телефона, по которому система попытается найти клиента и вернуть свободного ответственного менеджера данного клиента при его наличии. Данный метод полезен при маршрутизации входящего звонка на добавочный номер ответственного менеджера.

Менеджер считается свободным если он авторизован в системе и у него выставлен статус свободен. Кроме того в настройках интеграции у менеджера должен быть задан добавочный код. Если одно из этих условий не выполнено, ответственный менеджер не будет возвращен методом.

События звонков

Методом POST /api/v5/telephony/call/event можно сообщить системе о событиях звонка. Необходимо передавать события трех типов: входящий звонок, исходящий звонок и событие завершение звонка. В момент передачи события входящего звонка у менеджера, на чей добавочный номер направлен звонок, будет выводиться карточка звонка.

Пример запроса

Например, у системы https://example.retailcrm.ru активирована интеграция с телефонией. В настройках заведены добавочные номера 100, 200 и внешние номера +7-499-999-99-99, +7-499-888-88-88.

Нужно отправить POST-запрос на адресс https://example.retailcrm.ru/api/v5/telephony/call/event

c параметром event, в качестве значения JSON:

{
    "phone": "+7-555-555-55-55",
    "type": "in",
    "codes":["100"],
    "externalPhone": "+7-444-444-44-44"
}

Ответ

HTTP/1.1 200 OK

{
  "success": true
}

Инициация звонка

При настройке интеграции в поле configuration["makeCallUrl"] передается адрес, на который система будет отсылать запросы для инициации звонка.

Система посылает запрос GET {configuration["makeCallUrl"]} с параметрами:

• clientId — уникальный код системы, переданный при регистрации телефонией
• code — добавочный код пользователя, который инициирует звонок
• phone — телефон, на который инициируется звонок
• userId — Id пользователя в системе
• externalPhone — внешний номер телефона, если присутствует в настройках телефонии.

В случае успешной инициации звонка, АТС должна вернуть HTTP-статус 200. В противном случае любой другой статус, который будет интерпретирован как ошибка инициации звонка, о чем будет сообщено пользователю. Тело HTTP-ответа игнорируется.

Пример запроса на makeCallUrl

Например, зарегистрирован makeCallUrl-адрес http://api.telephony-test.ru/make-call. Менеджер c добавочным кодом 100 и id в системе 1 звонит клиенту с номером +7 (912) 123-45-67.

Запрос http://api.telephony-test.ru/make-call?clientId=2dbh26tahjj26sg&code=100&phone=+79121234567&userId=1

Ответ

HTTP/1.1 200 OK

Уведомление о смене статуса пользователя в системе

Если в настройках телефонии заполнено поле changeUserStatusUrl и у авторизованного пользователя системы указан добавочный код, система будет отсылать запросы для уведомления о смене статуса пользователя в системе.

Система посылает запрос GET {configuration["changeUserStatusUrl"]} с параметрами:

• clientId — уникальный код системы, переданный при регистрации телефонией
• userId — ID пользователя в системе
• code — добавочный код пользователя, у которого поменялся статус
• status — новый статус пользователя в системе.

Поле status - может принимать значения: [free|busy|dinner|break]

Пример запроса на changeUserStatusUrl

Например, зарегистрирован changeUserStatusUrl-адрес http://api.telephony-test.ru/change-status. Менеджер c добавочным кодом 100 и ID 1 поменял статус на занят.

Запрос http://api.telephony-test.ru/change-status?clientId=2dbh26tahjj26sg&code=100&userId=1&status=busy

Тело и статус HTTP-ответа игнорируется.