Существует несколько способов «подружить» IP-телефонию с CRM-системой или другим внешним сервисом. Между ними:
- Готовые интеграции, созданные разработчиками сервиса телефонии. Все делается по принципу Nocode или Lowcode. быстрый и удобный вариант. Но у провайдеров IP-телефонии нет готовых интеграций для каждой внешней системы.
- Использование посредников. Существуют специальные сервисы-коннекторы, поддерживающие подключение множества внешних продуктов (программ, решений) на вход и выход. Он также не требует программирования. Но такие интеграции часто недостаточно гибки.
- Интеграция через API. Основным преимуществом этого метода является гибкость. Однако требуется программирование. Но практика показывает, что оно того стоит — можно настроить все под себя, без всяких «но».
API телефония: что это такое
Аббревиатура API расшифровывается как Application Programming Interface. На русский язык это переводится как «интерфейс прикладного программирования». API можно охарактеризовать как описание способов взаимодействия между программами (сервисами). В случае IP-телефонии интерфейс прикладного программирования предоставляет возможность считывать и изменять данные, хранящиеся на сервере телефонии. Те. это своеобразный «мост», который позволяет соединить стороннее приложение с сервером IP-телефонии и обеспечить оперативный обмен информацией между этими двумя сторонами.
«Сервер» и «клиент»: 2 стороны API интеграции
При интеграции через API взаимодействующие стороны обычно делятся на «сервер» и «клиент». В случае IP-телефонии (в принципе, это относится и к другим услугам) сервер — это та сторона, которая фактически предоставляет этот самый программный интерфейс для взаимодействия, получает запросы, формирует ответы и работает с данными, хранящимися на физическом или виртуальном сервере. .
Клиент — это стороннее приложение, которое обращается к API службы телефонии. В качестве клиента могут выступать различные программы и сервисы, такие как CRM-системы, BPM, программы для складского и других видов учета и так далее.
Взаимодействие между клиентом и сервером при интеграции
Чтобы установить связь между этими двумя сторонами через интерфейс прикладного программирования, вам необходимо убедиться, что клиент «знает»:
- К каким данным можно получить доступ через API службы телефонии?
- Как именно организован этот доступ?
- Как клиент может манипулировать данными, хранящимися на сервере.
- В какой форме/формате организован обмен данными между взаимодействующими сторонами?
- Как клиент авторизуется при доступе к API.
Популярность этого архитектурного стиля обусловлена его преимуществами, к которым относятся:
- Легкость поддержки.
- Высокая отказоустойчивость систем, построенных по этому принципу.
- Гибкость и возможность реализации различных изменений.
- Хорошая производительность API.
- Масштабируемость системы.
Что нужно знать, чтобы клиент мог успешно «достучаться» до сервера
Каждый сервис, предлагающий свой API, должен предоставлять клиентам его описание, в котором формулируются правила взаимодействия. В описании обычно рассматриваются такие вопросы, как:
- Протокол, по которому происходит взаимодействие.
- Методы аутентификации клиента.
- Форматы передачи данных.
- Методы, с помощью которых клиент может получить доступ к API службы телефонии.
Протокол описывает набор правил для «общения» между клиентом и сервером. В Интернете наиболее часто используемым протоколом является HTTP. И он широко используется различными сервисами в качестве основы для своего API.
Центральным элементом взаимодействия при использовании этого протокола является концепция, называемая циклом запрос-ответ. Те. клиент отправляет запрос через API на выполнение определенных действий, а сервер отправляет ему ответ с результатами запроса или с информацией о том, что его невозможно выполнить.
Структура запроса
При использовании рассмотренного подхода к проектированию интерфейса прикладного программирования используется структура требований, включающая:
- URL. Задает адрес к ресурсу (к API).
- Метод. Таким образом, клиент сообщает именно то, что он хочет сделать.
- Заголовок. Здесь передается служебная информация (например, данные для авторизации, информация об используемом формате и т.д.).
- Тело. Здесь передается «основное содержание» запроса.
Методы API при взаимодействии с сервисами IP-телефонии
Метод является важной частью HTTP-запроса к API. Клиент использует это, чтобы сообщить, какое действие он ожидает в качестве ответа от сервера. С помощью методов вы можете сделать следующее:
- Получить всю информацию от сервиса (часто специалисты используют также термин «ресурс» — «получать ресурс»). Однако никаких изменений в эту информацию (ресурс) не вносится. Такие методы относятся к категории GET. Примером метода GET в Telfin API является `GET /api/ver1.0/client/client_info/{client_id}` (подробнее здесь) для получения данных о клиенте по его идентификатору.
- Создавать новые ресурсы («единицы» информации) в базе данных (и не только) сервера. Для этого используются методы POST. Тело запроса содержит информацию, которая будет добавлена к ресурсу при его создании.
- Редактировать существующие ресурсы. Это делается с помощью методов PUT. При вызове в теле запроса указываются поля для редактирования.
- Удалить информацию (ресурсы) из базы данных сервера. Для этого используются методы DELETE, в которых передаются идентификатор ресурса или другие поля, на основании которых производится выборка (в зависимости от структуры и параметров базы данных).
Для API-интеграции в основном используются 2 формата: JSON и XML. API-интерфейсы часто разрабатываются для одновременной поддержки. Например, в теле запроса и успешном ответе может использоваться json, а в случае ошибки вместе с передачей ее кода передается xml-структура с полями, описывающими причину ее возникновения.
Пример тела запроса API Telphin для изменения информации о клиенте `PUT /api/ver/1.0/client/client_info/{client_id}/` в формате json выглядит следующим образом:
```json { "ambassadors": "string", "contact_phones": "string", "create_date": "string", "dial_rule_id": 0, "did_as_transfer_caller_id": "string", "disk_space_notify_email": "string", "disk_space_notify_threshold": 0, "domain": "string", "domain_prefix": "string", "email": "string", "extension_len": 0, "extra_params": "string", "fact_address": "string", "geo_list": "string", "hold_music": 0, "id": 0, "jur_address": "string", "language": "string", "name": "string", "prefix": "string", "presence": "string", "record_format": "mp3", "record_stereo": true, "reg_status_log": true, "short_local_caller_id": "string", "sip_network_permission_id": 0, "timezone": "Europe/Moscow", "type": "string" } ```
Типовой пример ответа в формате xml в случае ошибки:
```xml Сообщение об ошибке```
Эти форматы были выбраны благодаря их «универсальности» (их поддерживают практически все языки программирования), гибкости и простоте обработки. Со стороны клиента остается только разобрать полученный ответ и использовать его по назначению.
Аутентификация при подключении по API
В API телефонии (как и в любом другом программном интерфейсе) нельзя просто «прийти и постучать со стороны». Разработчики должны обеспечить аутентификацию.
Схемы аутентификации могут быть разными. Все зависит от предпочтений разработчиков API. Аутентификацию можно использовать:
- Логин и пароль. Эта опция называется «Базовая аутентификация». Использовался редко, т.к. есть проблемы с безопасностью.
- API-ключ. Клиенту выдается уникальный ключ.
- OAuth 1 и 2. Подход автоматизирует обмен ключами доступа между клиентом и сервером, предоставляющим API. Здесь используются токены доступа.
Интеграция через API позволяет настроить гибкое и эффективное взаимодействие с сервисом. Возьмем в качестве примера IP-телефонию от Telfin, тогда предлагаемый пользователям API позволяет выполнять самые разные действия. Среди них:
- Организация отправки уведомлений о входящем звонке в CRM или другую внешнюю систему.
- Возможность совершать исходящие вызовы из систем, подключенных к телефонии через системы API.
- Загружайте журналы вызовов, записи вызовов и другую статистическую информацию.
- Возможность перехватывать звонки.
- Функционал для переадресации входящих вызовов на нужные номера прямо из интерфейса внешних систем.
- Обрабатывать звонки в диалоговом режиме в зависимости от их параметров (номер абонента и т.д.).