Интеграция телефонии по API

«Подружить» IP-телефонию c CRM-системой или каким-то другим внешним сервисом можно несколькими способами. Среди них:

Готовые интеграции, созданные разработчиками сервиса телефонии. Все делается по принципу Nocode или Lowcode. быстрый и удобный вариант. Но готовые интеграции у провайдеров IP телефонии есть далеко не для каждой внешней системы.
Использование «посредников». Существуют специальные сервисы-коннекторы, которые поддерживают подключение множества внешних продуктов (программ, решений) на вход и на выход. Здесь также не требуется программирование. Но такие интеграции часто получаются недостаточно гибкими.
Интеграция через API. Главный плюс этого способа — гибкость. Однако, требуется программирование. Но практика показывает, оно того стоит: вы сможете настроить все под себя, без всяких «но».

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

API телефония: что это такое

Аббревиатура API расшифровывается как Application Programming Interface. Это переводится на русский как «программный интерфейс приложения». Охарактеризовать API можно как описание способов взаимодействия между программами (сервисами). В случае с IP-телефонией с помощью Application Programming Interface обеспечивается возможность чтения и изменения данных, хранящихся на сервере телефонии. Т.е. это — своего рода «мост», позволяющий соединить стороннее приложение с сервером IP-телефонии и обеспечить эффективный обмен информацией между этими двумя сторонами.

«Сервер» и «клиент»: 2 стороны API интеграции

При интеграции через API взаимодействующие стороны принято делить на «сервер» и «клиент». В случае с IP-телефонией (в принципе, это касается и других сервисов) сервер — это сторона, которая фактически предоставляет этот самый программный интерфейс для взаимодействия, принимает запросы, формирует ответы, работает с данными, хранящимися на физическом или виртуальном сервере.

Клиент — это стороннее приложение, которое обращается к API сервиса телефонии. В качестве клиента могут выступать различные программы и сервисы, такие как CRM-системы, BPM, программы для складского и иных видов учета и так далее.

Взаимодействие между клиентом и сервером при интеграции

Чтобы наладить взаимодействие между этими двумя сторонами с помощью Application Programming Interface, нужно сделать так, чтобы клиент «знал»:

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

То есть, видно, что взаимодействие при API интеграции происходит по какому-то определённому набору правил. Таких «наборов» сегодня существует несколько. Но чаще всего именно при взаимодействии через web используется REST API. REST расшифровывается как Representational State Transfer. Он представляет собой архитектурный стиль или набор согласованных принципов и ограничений проектирования API, которые позволяют добиться определённых свойств системы и организовать взаимодействие с внешними сервисами по понятным правилам. Архитектурный стиль REST API используют практически все сервисы IP-телефонии, в том числе и «Телфин».

Популярность этого архитектурного стиля обусловлена его преимуществами, среди которых:

Простота поддержки.
Высокие показатели отказоустойчивости систем, построенных с использованием этого принципа.
Гибкость и возможность реализации различных изменений.
Хорошая производительность API.
Масштабируемость систем.

Что нужно знать, чтобы клиент мог успешно «достучаться» до сервера

Каждый сервис, предлагающий собственный API-интерфейс, должен предоставить клиентам и его описание, в котором сформулированы правила взаимодействия. В описании, как правило, рассматриваются такие вопросы, как:

Протокол, по которому происходит взаимодействие.
Способы аутентификации клиента.
Форматы передачи данных.
Методы, с помощью которых клиент может обращаться к API сервиса телефонии.

Протокол для API интеграции с сервисом API-телефонии

Протокол API-интеграции

Протокол описывает набор правил для «общения» между клиентом и сервером. В интернете наибольшее распространение на данный момент имеет протокол HTTP. И именно его повсеместно используют различные сервисы в качестве основы для своего API-интерфейса.

В основе взаимодействия при использовании этого протокола лежит концепция, которая получила название Цикл «Запрос-ответ». Т.е. клиент отправляет через API запрос на выполнение определенных действий, а сервер отправляет ему ответ с результатами выполнения запроса или с информацией о том, что он не может быть выполнен.

Структура запроса

При использовании рассматриваемого подхода к проектированию Application Programming Interface применяется структура запроса, которая включает:

URL. Указывает адрес к ресурсу (к API).
Метод. С его помощью клиент сообщает, что именно он хочет сделать.
Заголовок. Здесь передается служебная информация (например, данные для авторизации, сведения об используемом формате и пр.).
Тело. Здесь передается «основное» содержимое запроса.

Методы API при взаимодействии с сервисами IP-телефонии

Метод — важная составляющая HTTP-запроса к API. С его помощью клиент сообщает, какое действие он ожидает от сервера в ответ. С помощью методов можно выполнять следующие действия:

Получать от сервиса какую-либо информацию (часто специалисты оперируют еще термином «ресурс» — «получить ресурс»). При этом никаких изменений в эту информацию (ресурс) не вносится. Такие методы относятся к категории GET. Пример GET-метода в API «Телфин» — `GET /api/ver1.0/client/client_info/{client_id}` (подробнее — здесь) для получения данных о клиенте по его id.
Создавать в БД (и не только) сервера новые ресурсы («единицу» информации). Для этого используются методы POST. В теле запроса передаётся информация, которую нужно добавить в ресурс при его создании.
Редактировать уже имеющиеся ресурсы. Делается это с помощью методов PUT. При их вызове в теле запроса указываются поля, которые необходимо отредактировать.
Удалять информацию (ресурсы) из БД сервера. Для этого используются методы DELETE, в которых передается id ресурса или какие-то иные поля, по которым делается выборка (в зависимости от структуры и настроек БД).

Форматы передачи данных при интеграции через API с IP-телефонией

Для API-интеграции чаще всего используется 2 формата: JSON и XML. Часто при разработке API предусматривается их одновременная поддержка. Например, в теле запроса и успешного ответа может применяться json, а в случае ошибки вместе с передачей ее кода передается xml-структура с полями, которые описывают причину ее возникновения.

Пример тела запроса API «Телфин» для изменения сведений о клиенте `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-телефонии

Возможности API-телефонии

При интеграции через API вы сможете настроить гибкое и эффективное взаимодействие с сервисом. Если взять в качестве примера IP-телефонию от «Телфин», то предлагаемый пользователям API позволяет выполнять широкий перечень действий. Среди них:

Организация отправки уведомлений о входящем звонке в CRM или иную внешнюю систему.
Возможность совершать исходящие вызовы из подключенных к телефонии через API систем.
Выгрузка истории вызовов, записей звонков и другой статистической информации.
Возможность совершения перехватов звонков.
Функционал для перевода входящих вызовов на нужные номера прямо из интерфейса внешних систем.
Обработка вызовов в интерактивном режиме, в зависимости от их параметров (номер абонента и т.п.).