API для телефонии — различия между версиями
Seva (обсуждение | вклад) |
Seva (обсуждение | вклад) |
||
(не показано 49 промежуточных версий 5 участников) | |||
Строка 1: | Строка 1: | ||
+ | {{#seo: | ||
+ | |title=API для телефонии | ||
+ | |titlemode=append | ||
+ | |keywords=планфикс, телефония, апи, api | ||
+ | |description=API для телефонии | ||
+ | }} | ||
+ | |||
+ | |||
== Общие сведения об API == | == Общие сведения об API == | ||
API позволяет подключить к ПланФикс любую вашу собственную Облачную АТС. | API позволяет подключить к ПланФикс любую вашу собственную Облачную АТС. | ||
− | Интеграция | + | Интеграция ПланФикса и Облачной АТС решает несколько бизнес-задач: |
+ | |||
* получение имени звонящего по номеру телефона, для того, чтобы его можно было отобразить на экране телефона или sip-клиента; | * получение имени звонящего по номеру телефона, для того, чтобы его можно было отобразить на экране телефона или sip-клиента; | ||
* автоматическая маршрутизация входящего звонка от клиента на менеджера, который закреплен за этим клиентом; | * автоматическая маршрутизация входящего звонка от клиента на менеджера, который закреплен за этим клиентом; | ||
− | * отображение информации о входящем звонке непосредственно внутри | + | * отображение информации о входящем звонке непосредственно внутри ПланФикса (всплывающее окно при звонке) |
* сохранение в ПланФиксе истории всех звонков и записей разговоров; | * сохранение в ПланФиксе истории всех звонков и записей разговоров; | ||
* совершение исходящих звонков сразу из интерфейса ПланФикса. | * совершение исходящих звонков сразу из интерфейса ПланФикса. | ||
+ | |||
Интеграция должна быть двухсторонней. Поэтому часть запросов ПланФикс посылает в сторону Облачной АТС на указанные точки входа, а часть запросов, наоборот, Облачная АТС посылает в сторону ПланФикса на единую точку входа. | Интеграция должна быть двухсторонней. Поэтому часть запросов ПланФикс посылает в сторону Облачной АТС на указанные точки входа, а часть запросов, наоборот, Облачная АТС посылает в сторону ПланФикса на единую точку входа. | ||
Взаимодействие производится по протоколу HTTPS. Авторизация осуществляется по адресу ПланФикса или Облачной АТС соответственно и авторизационному ключу, полученному в процессе настройки интеграции. | Взаимодействие производится по протоколу HTTPS. Авторизация осуществляется по адресу ПланФикса или Облачной АТС соответственно и авторизационному ключу, полученному в процессе настройки интеграции. | ||
+ | |||
== Принцип авторизации и взаимодействия == | == Принцип авторизации и взаимодействия == | ||
− | HTTPS: | + | '''HTTPS:''' |
− | * Запросы к | + | * Запросы к ПланФиксу принимаются только по протоколу HTTPS. Это обеспечивает достаточный уровень безопасности для общения систем через Интернет. |
* В целях безопасности ваших данных, пожалуйста, реализуйте прием запросов на стороне АТС также с использованием HTTPS. | * В целях безопасности ваших данных, пожалуйста, реализуйте прием запросов на стороне АТС также с использованием HTTPS. | ||
− | Ключ (token): | + | |
− | * Дополнительно для авторизации каждого запроса к | + | |
+ | '''Ключ (token):''' | ||
+ | * Дополнительно для авторизации каждого запроса к ПланФиксу используется специальный ключ (token). Получить его можно в настройках интеграции. | ||
* Пожалуйста, реализуйте прием запросов на стороне АТС также с использованием ключа (token). Сгенерируйте ключ и вставьте его в соответствующее поле в разделе настройки интеграции. | * Пожалуйста, реализуйте прием запросов на стороне АТС также с использованием ключа (token). Сгенерируйте ключ и вставьте его в соответствующее поле в разделе настройки интеграции. | ||
* Ключи создаются один раз при настройке интеграции. При необходимости, вы можете сменить ключ на своей стороне и обновить его интерфейсе ПланФикса. | * Ключи создаются один раз при настройке интеграции. При необходимости, вы можете сменить ключ на своей стороне и обновить его интерфейсе ПланФикса. | ||
− | Запросы от Облачной АТС к ПланФиксу: | + | |
+ | |||
+ | '''Запросы от Облачной АТС к ПланФиксу:''' | ||
* Запросы необходимо отправлять на указанный в настройках интеграции адрес для приема уведомлений. | * Запросы необходимо отправлять на указанный в настройках интеграции адрес для приема уведомлений. | ||
* В теле запроса в специальном поле «token» необходимо всегда передавать специальный ключ. | * В теле запроса в специальном поле «token» необходимо всегда передавать специальный ключ. | ||
− | Запросы от ПланФикса к Облачной АТС: | + | * Запросы передаются в application/x-www-form-urlencoded формате |
+ | |||
+ | |||
+ | '''Запросы от ПланФикса к Облачной АТС:''' | ||
* ПланФикс будет отправлять все запросы на указанный в настройках интеграции адрес. | * ПланФикс будет отправлять все запросы на указанный в настройках интеграции адрес. | ||
* В теле сообщений ПланФикс будет передавать указанный вами в веб-кабинете ключ (token). | * В теле сообщений ПланФикс будет передавать указанный вами в веб-кабинете ключ (token). | ||
− | Ответы | + | * Запросы передаются в application/x-www-form-urlencoded формате |
+ | |||
+ | |||
+ | '''Ответы''' | ||
* Все ответы на запросы Облачной АТС ПланФикс присылает в формате JSON в теле ответа. | * Все ответы на запросы Облачной АТС ПланФикс присылает в формате JSON в теле ответа. | ||
* Все ответы на запросы ПланФикса Облачная АТС должна присылать в формате JSON в теле ответа. | * Все ответы на запросы ПланФикса Облачная АТС должна присылать в формате JSON в теле ответа. | ||
+ | == Подключение в интерфейсе ПланФикса == | ||
+ | Для подключения и настройки интеграции перейдите в раздел '''Интеграции''' - '''Виртуальные АТС''' | ||
+ | |||
+ | https://p.pfx.so/pf/Og/QuIbQG.png | ||
+ | |||
+ | |||
+ | В открывшемся разделе выберите '''Api ПланФикса для телефоний''' (в конце списка). | ||
+ | |||
+ | https://p.pfx.so/pf/lZ/EWRRqq.png | ||
+ | |||
+ | |||
+ | Откроется окно настроек интеграции. | ||
+ | |||
+ | https://p.pfx.so/pf/ao/TJVltJ.png | ||
+ | |||
+ | |||
+ | Из него необходимо будет взять адрес для отправки запросов в ПланФикс (он свой для каждого аккаунта) и токен (planfix_token в запросах к ПланФиксу), и указать в нём данные АТС - адрес, куда ПланФикс будет слать запросы, и ключ авторизации АТС (параметр token в запросах к АТС) | ||
== Список команд API == | == Список команд API == | ||
− | От ПланФикса к Облачной АТС: | + | |
+ | |||
+ | '''От ПланФикса к Облачной АТС:''' | ||
* makeCall (POST) | * makeCall (POST) | ||
− | От Облачной АТС к | + | * setup (POST) |
+ | |||
+ | |||
+ | '''От Облачной АТС к ПланФиксу:''' | ||
* contact (POST) | * contact (POST) | ||
* event (POST) | * event (POST) | ||
Строка 46: | Строка 89: | ||
=== Команды от ПланФикса к Облачной АТС === | === Команды от ПланФикса к Облачной АТС === | ||
==== makeCall ==== | ==== makeCall ==== | ||
− | Команда необходимая для того, чтобы инициировать звонок от менеджера клиенту. В результате успешного выполнения команды, Облачная АТС сделает сначала звонок на телефон менеджера, а потом соединит его с клиентом. Команда используется для звонка по клику на номер клиента в | + | Команда необходимая для того, чтобы инициировать звонок от менеджера клиенту. В результате успешного выполнения команды, Облачная АТС сделает сначала звонок на телефон менеджера, а потом соединит его с клиентом. Команда используется для звонка по клику на номер клиента в ПланФиксе. |
+ | |||
− | Параметры запроса: | + | '''Параметры запроса:''' |
{| class="wikitable" style="margin-top: 1em; width:100% " | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание | !width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание | ||
Строка 62: | Строка 106: | ||
|} | |} | ||
− | Пример запроса: | + | |
+ | '''Пример запроса:''' | ||
<source lang="bash"> | <source lang="bash"> | ||
POST https://domain/planfix_api.php | POST https://domain/planfix_api.php | ||
+ | |||
cmd=makeCall | cmd=makeCall | ||
from=101 | from=101 | ||
Строка 71: | Строка 117: | ||
</source> | </source> | ||
− | Варианты ответа: | + | |
+ | '''Варианты ответа:''' | ||
{| class="wikitable" style="margin-top: 1em; width:100% " | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
!width="150"|HTTP код !!width="50%"| Тело !! Описание | !width="150"|HTTP код !!width="50%"| Тело !! Описание | ||
Строка 82: | Строка 129: | ||
|- | |- | ||
|} | |} | ||
+ | |||
+ | |||
+ | ==== setup ==== | ||
+ | Команда вызывается при включении интеграции на стороне ПланФикса. Позволяет автоматически включать интеграцию на стороне АТС. В случае статуса ответа не равного 200 - сообщение об ошибке с полученным текстом ответа будет показано на стороне ПланФикса. | ||
+ | |||
+ | |||
+ | '''Параметры запроса:''' | ||
+ | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
+ | !width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание | ||
+ | |- | ||
+ | |cmd || тип операции, в данном случае setup || string || | ||
+ | |- | ||
+ | |token || ключ (token) Облачной АТС, установленный в настройках интеграции || string || | ||
+ | |- | ||
+ | |planfix_token || ключ (token) ПланФикса, указанный в настройках интеграции || string || | ||
+ | |- | ||
+ | |planfix_url || адрес для отправки запросов в ПланФикс || string || | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | |||
+ | '''Пример запроса:''' | ||
+ | <source lang="bash"> | ||
+ | POST https://domain/planfix_api.php | ||
+ | |||
+ | cmd=setup | ||
+ | token=202cb962ac59075b964b07152d234b70 | ||
+ | planfix_token=303cb962ac59075b964b07152d234b70 | ||
+ | planfix_url=https://test.planfix.ru/tel/api | ||
+ | </source> | ||
+ | |||
=== Команды от Облачной АТС к ПланФиксу === | === Команды от Облачной АТС к ПланФиксу === | ||
Строка 87: | Строка 165: | ||
Команда для получения информации о названии клиента и ответственном за него сотруднике по номеру его телефона. | Команда для получения информации о названии клиента и ответственном за него сотруднике по номеру его телефона. | ||
− | Команда может | + | Команда может использоваться для отображения на экране IP-телефона или в коммуникаторе на ПК сотрудника названия клиента. |
Также она может использоваться для перенаправления звонков от клиентов ответственному сотруднику, указанному в ПланФиксе | Также она может использоваться для перенаправления звонков от клиентов ответственному сотруднику, указанному в ПланФиксе | ||
− | Параметры запроса: | + | |
+ | '''Параметры запроса:''' | ||
{| class="wikitable" style="margin-top: 1em; width:100% " | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание | !width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание | ||
Строка 104: | Строка 183: | ||
|} | |} | ||
− | Пример запроса: | + | |
+ | '''Пример запроса:''' | ||
<source lang="bash"> | <source lang="bash"> | ||
POST https://test.planfix.ru/tel/api | POST https://test.planfix.ru/tel/api | ||
+ | |||
cmd=contact | cmd=contact | ||
phone=79101234567 | phone=79101234567 | ||
Строка 113: | Строка 194: | ||
</source> | </source> | ||
− | Варианты ответа: | + | |
+ | '''Варианты ответа:''' | ||
{| class="wikitable" style="margin-top: 1em; width:100% " | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
!width="150"|HTTP код !!width="50%"| Тело !! Описание | !width="150"|HTTP код !!width="50%"| Тело !! Описание | ||
|- | |- | ||
− | |200|| | + | |200|| { contact_name: "Иванов Иван Иванович", responsible: 103 } || responsible - короткий номер ответственного пользователя, может отсутствовать, если такого нет или у него не задан короткий номера |
− | { contact_name: "Иванов Иван Иванович", | ||
− | responsible: 103 | ||
− | |||
|- | |- | ||
|400 || { error: "Invalid parameters" } || Переданы некорректные параметры | |400 || { error: "Invalid parameters" } || Переданы некорректные параметры | ||
Строка 129: | Строка 208: | ||
==== event ==== | ==== event ==== | ||
+ | Облачная АТС отправляет в ПланФикс уведомления о событиях звонков: появлении, принятии или завершении звонка, а также информацию о звонке при его завершении. Команда используется для отображения всплывающей карточки звонка в интерфейсе. | ||
+ | |||
+ | Данные о продолжительности и результате звонка при завершении используются для фиксации данных звонка в аналитике (будет реализовано в скором времени), а также для понимания того существует ли запись звонка и стоит ли ПланФиксу рассчитывать её получить. | ||
+ | |||
+ | |||
+ | '''Параметры запроса:''' | ||
+ | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
+ | !width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание | ||
+ | |- | ||
+ | |cmd || тип операции, в данном случае event || string || | ||
+ | |- | ||
+ | |type|| тип звонка || in/out || входящий / исходящий | ||
+ | |- | ||
+ | |event || тип события, связанного со звонком: | ||
+ | * INCOMING - пришел входящий звонок (в это время у менеджера должен начать звонить телефон). | ||
+ | * OUTGOING - начался исходящий звонок. | ||
+ | * ACCEPTED - звонок успешно принят (менеджер снял трубку). | ||
+ | * COMPLETED - звонок завершен (менеджер или клиент положили трубку после разговора). | ||
+ | || string || | ||
+ | |- | ||
+ | |phone|| номер телефона клиента || string || | ||
+ | |- | ||
+ | |diversion|| внешний номер телефона АТС через который поступил или вышел звонок || string || | ||
+ | |- | ||
+ | |ext|| внутренний номер сотрудника АТС || string || | ||
+ | |- | ||
+ | |callid|| уникальный id звонка || string || | ||
+ | |- | ||
+ | |duration|| продолжительность звонка в секундах || int || при event=COMPLETED | ||
+ | |- | ||
+ | |is_recorded|| записан ли звонок || 0/1 || при event=COMPLETED | ||
+ | |- | ||
+ | |status|| статус входящего звонка: | ||
+ | * Success - успешный входящий звонок | ||
+ | * Missed – пропущенный входящий звонок | ||
+ | * Cancelled - отмененный входящий звонок (трубку снял другой сотрудник и т.п.) | ||
+ | статус исходящего звонка: | ||
+ | * Success - успешный исходящий звонок | ||
+ | * Busy - АТС получила ответ Занято | ||
+ | * NoAnswer - Не дождались ответа | ||
+ | * NotAvailable - АТС получила ответ Абонент недоступен | ||
+ | * NotAllowed - Звонки на это направление запрещены | ||
+ | || string || при event=COMPLETED | ||
+ | |- | ||
+ | |record_link || ссылка на запись звонка, если АТС может предоставить её сразу, если нет - ссылка отправляется командой record || string || необязательный, при event=COMPLETED | ||
+ | |- | ||
+ | |planfix_token || ключ (token) ПланФикса, указанный в настройках интеграции || string || | ||
+ | |- | ||
+ | |data_имя_поля_аналитики|| дополнительные данные, которые надо внести в аналитику звонка. имя поля в аналитике должно точно совпадать с текстом после data_, таких параметров может быть столько, сколько полей заполняется, по одному на каждое поле. К примеру, если вы передаете в запросе параметры data_utm_source и data_utm_medium, то для сохранения этих данных в ПланФиксе, необходимо в аналитике Звонок добавить поля типа Строка с названиями utm_source и utm_medium || string || при event=COMPLETED | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | |||
+ | |||
+ | '''Пример запроса:''' | ||
+ | <source lang="bash"> | ||
+ | POST https://test.planfix.ru/tel/api | ||
+ | |||
+ | cmd=event | ||
+ | type=out | ||
+ | event=COMPLETED | ||
+ | phone=79101234567 | ||
+ | ext=102 | ||
+ | callid=D10D0EB124F4E64AF4EA-1511 | ||
+ | duration=124 | ||
+ | is_recorded=1 | ||
+ | status=Success | ||
+ | record_link=https://link/file.mp3 | ||
+ | planfix_token=303cb962ac59075b964b07152d234b70 | ||
+ | data_utm_source=site.io | ||
+ | data_utm_medium=banner | ||
+ | </source> | ||
+ | |||
+ | |||
+ | |||
+ | '''Варианты ответа:''' | ||
+ | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
+ | !width="150"|HTTP код !!width="50%"| Тело !! Описание | ||
+ | |- | ||
+ | |200|| || ОК | ||
+ | |- | ||
+ | |400 || { error: "Invalid parameters" } || Переданы некорректные параметры | ||
+ | |- | ||
+ | |401|| { error: "Invalid token" } || Передан неверный ключ (token) | ||
+ | |- | ||
+ | |} | ||
+ | |||
==== record ==== | ==== record ==== | ||
+ | Уведомление содержит информацию о записи разговора. ПланФикс ожидает такого уведомления, если в команде event с event=COMPLETED и is_recorded=1 отсутствует параметр record_link. Использовать уведомление имеет смысл, если сохранение записей в Облачной АТС устроено таким образом, что ссылка может быть сформирована только через некоторое время. | ||
+ | |||
+ | Ссылка должна быть постоянной, для того чтобы в зависимости от настроек интеграции: | ||
+ | * файл по ней мог быть сохранен в ПланФиксе | ||
+ | * она могла бы использоваться для прослушивания записи напрямую с серверов АТС. (такая настройка активно запрашивается пользователями и будет реализована в скором времени для поддерживающих это телефоний) | ||
+ | |||
+ | |||
+ | '''Параметры запроса:''' | ||
+ | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
+ | !width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание | ||
+ | |- | ||
+ | |cmd || тип операции, в данном случае record || string || | ||
+ | |- | ||
+ | |callid|| уникальный id звонка || string || | ||
+ | |- | ||
+ | |is_temp|| ссылка временная и может использоваться только для однократного сохранения файла в ПланФиксе, прослушивание из облачной АТС невозможно || 0/1 || необязательный, при отсутствии считается равным 0 | ||
+ | |- | ||
+ | |record_link || ссылка на запись звонка || string || | ||
+ | |- | ||
+ | |planfix_token || ключ (token) ПланФикса, указанный в настройках интеграции || string || | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | |||
+ | |||
+ | '''Пример запроса:''' | ||
+ | <source lang="bash"> | ||
+ | POST https://test.planfix.ru/tel/api | ||
+ | |||
+ | cmd=record | ||
+ | callid=D10D0EB124F4E64AF4EA-1511 | ||
+ | record_link=https://link/file.mp3 | ||
+ | planfix_token=303cb962ac59075b964b07152d234b70 | ||
+ | </source> | ||
+ | |||
+ | |||
+ | |||
+ | '''Варианты ответа:''' | ||
+ | {| class="wikitable" style="margin-top: 1em; width:100% " | ||
+ | !width="150"|HTTP код !!width="50%"| Тело !! Описание | ||
+ | |- | ||
+ | |200|| || ОК | ||
+ | |- | ||
+ | |400 || { error: "Invalid parameters" } || Переданы некорректные параметры | ||
+ | |- | ||
+ | |401|| { error: "Invalid token" } || Передан неверный ключ (token) | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | |||
+ | == Пример использования API при входящем звонке на группу сотрудников == | ||
+ | |||
+ | - начался звонок | ||
+ | * для каждого сотрудника шлется запрос с его ext и INCOMING и одинаковым для всех идентификатором звонка - при этом в планфиксе показывается окно что идет звонок | ||
+ | |||
+ | - один из сотрудников снял трубку | ||
+ | * для него шлется ACCEPTED | ||
+ | * для остальных COMPLETED с Cancelled - при этом окно звонка у них исчезает | ||
+ | (идентификатор звонка общий для всех и тот же, что был в событии начала) | ||
+ | |||
+ | - звонок завершен | ||
+ | * шлется COMPLETED с Success и ext того сотрудника, который разговаривал. - показывается в планфиксе окно что звонок завершен, записывается аналитика | ||
+ | |||
+ | == Перейти == | ||
+ | *[[Разработчикам: API]] |
Текущая версия на 13:33, 5 мая 2021
Содержание
Общие сведения об API
API позволяет подключить к ПланФикс любую вашу собственную Облачную АТС.
Интеграция ПланФикса и Облачной АТС решает несколько бизнес-задач:
- получение имени звонящего по номеру телефона, для того, чтобы его можно было отобразить на экране телефона или sip-клиента;
- автоматическая маршрутизация входящего звонка от клиента на менеджера, который закреплен за этим клиентом;
- отображение информации о входящем звонке непосредственно внутри ПланФикса (всплывающее окно при звонке)
- сохранение в ПланФиксе истории всех звонков и записей разговоров;
- совершение исходящих звонков сразу из интерфейса ПланФикса.
Интеграция должна быть двухсторонней. Поэтому часть запросов ПланФикс посылает в сторону Облачной АТС на указанные точки входа, а часть запросов, наоборот, Облачная АТС посылает в сторону ПланФикса на единую точку входа.
Взаимодействие производится по протоколу HTTPS. Авторизация осуществляется по адресу ПланФикса или Облачной АТС соответственно и авторизационному ключу, полученному в процессе настройки интеграции.
Принцип авторизации и взаимодействия
HTTPS:
- Запросы к ПланФиксу принимаются только по протоколу HTTPS. Это обеспечивает достаточный уровень безопасности для общения систем через Интернет.
- В целях безопасности ваших данных, пожалуйста, реализуйте прием запросов на стороне АТС также с использованием HTTPS.
Ключ (token):
- Дополнительно для авторизации каждого запроса к ПланФиксу используется специальный ключ (token). Получить его можно в настройках интеграции.
- Пожалуйста, реализуйте прием запросов на стороне АТС также с использованием ключа (token). Сгенерируйте ключ и вставьте его в соответствующее поле в разделе настройки интеграции.
- Ключи создаются один раз при настройке интеграции. При необходимости, вы можете сменить ключ на своей стороне и обновить его интерфейсе ПланФикса.
Запросы от Облачной АТС к ПланФиксу:
- Запросы необходимо отправлять на указанный в настройках интеграции адрес для приема уведомлений.
- В теле запроса в специальном поле «token» необходимо всегда передавать специальный ключ.
- Запросы передаются в application/x-www-form-urlencoded формате
Запросы от ПланФикса к Облачной АТС:
- ПланФикс будет отправлять все запросы на указанный в настройках интеграции адрес.
- В теле сообщений ПланФикс будет передавать указанный вами в веб-кабинете ключ (token).
- Запросы передаются в application/x-www-form-urlencoded формате
Ответы
- Все ответы на запросы Облачной АТС ПланФикс присылает в формате JSON в теле ответа.
- Все ответы на запросы ПланФикса Облачная АТС должна присылать в формате JSON в теле ответа.
Подключение в интерфейсе ПланФикса
Для подключения и настройки интеграции перейдите в раздел Интеграции - Виртуальные АТС
В открывшемся разделе выберите Api ПланФикса для телефоний (в конце списка).
Откроется окно настроек интеграции.
Из него необходимо будет взять адрес для отправки запросов в ПланФикс (он свой для каждого аккаунта) и токен (planfix_token в запросах к ПланФиксу), и указать в нём данные АТС - адрес, куда ПланФикс будет слать запросы, и ключ авторизации АТС (параметр token в запросах к АТС)
Список команд API
От ПланФикса к Облачной АТС:
- makeCall (POST)
- setup (POST)
От Облачной АТС к ПланФиксу:
- contact (POST)
- event (POST)
- record (POST)
Команды API и примеры доступных сценариев
Команды от ПланФикса к Облачной АТС
makeCall
Команда необходимая для того, чтобы инициировать звонок от менеджера клиенту. В результате успешного выполнения команды, Облачная АТС сделает сначала звонок на телефон менеджера, а потом соединит его с клиентом. Команда используется для звонка по клику на номер клиента в ПланФиксе.
Параметры запроса:
Имя | Описание | Тип/формат данных | Примечание |
---|---|---|---|
cmd | тип операции, в данном случае makeCall | string | |
from | короткий номер сотрудника осуществляющего исходящий вызов | string | |
to | номер, на который делается исходящий вызов | string | |
token | ключ (token) Облачной АТС, установленный в настройках интеграции | string |
Пример запроса:
POST https://domain/planfix_api.php
cmd=makeCall
from=101
to=79101234567
token=202cb962ac59075b964b07152d234b70
Варианты ответа:
HTTP код | Тело | Описание |
---|---|---|
200 | ОК | |
400 | { error: "Invalid parameters" } | Переданы некорректные параметры |
401 | { error: "Invalid token" } | Передан неверный ключ (token) |
setup
Команда вызывается при включении интеграции на стороне ПланФикса. Позволяет автоматически включать интеграцию на стороне АТС. В случае статуса ответа не равного 200 - сообщение об ошибке с полученным текстом ответа будет показано на стороне ПланФикса.
Параметры запроса:
Имя | Описание | Тип/формат данных | Примечание |
---|---|---|---|
cmd | тип операции, в данном случае setup | string | |
token | ключ (token) Облачной АТС, установленный в настройках интеграции | string | |
planfix_token | ключ (token) ПланФикса, указанный в настройках интеграции | string | |
planfix_url | адрес для отправки запросов в ПланФикс | string |
Пример запроса:
POST https://domain/planfix_api.php
cmd=setup
token=202cb962ac59075b964b07152d234b70
planfix_token=303cb962ac59075b964b07152d234b70
planfix_url=https://test.planfix.ru/tel/api
Команды от Облачной АТС к ПланФиксу
contact
Команда для получения информации о названии клиента и ответственном за него сотруднике по номеру его телефона.
Команда может использоваться для отображения на экране IP-телефона или в коммуникаторе на ПК сотрудника названия клиента. Также она может использоваться для перенаправления звонков от клиентов ответственному сотруднику, указанному в ПланФиксе
Параметры запроса:
Имя | Описание | Тип/формат данных | Примечание |
---|---|---|---|
cmd | тип операции, в данном случае contact | string | |
phone | номер контакта | string | |
callid | уникальный id звонка | string | необязательный |
planfix_token | ключ (token) ПланФикса, указанный в настройках интеграции | string |
Пример запроса:
POST https://test.planfix.ru/tel/api
cmd=contact
phone=79101234567
planfix_token=303cb962ac59075b964b07152d234b70
callid=D12D0EB124F4E64AF4EA-1511
Варианты ответа:
HTTP код | Тело | Описание |
---|---|---|
200 | { contact_name: "Иванов Иван Иванович", responsible: 103 } | responsible - короткий номер ответственного пользователя, может отсутствовать, если такого нет или у него не задан короткий номера |
400 | { error: "Invalid parameters" } | Переданы некорректные параметры |
401 | { error: "Invalid token" } | Передан неверный ключ (token) |
event
Облачная АТС отправляет в ПланФикс уведомления о событиях звонков: появлении, принятии или завершении звонка, а также информацию о звонке при его завершении. Команда используется для отображения всплывающей карточки звонка в интерфейсе.
Данные о продолжительности и результате звонка при завершении используются для фиксации данных звонка в аналитике (будет реализовано в скором времени), а также для понимания того существует ли запись звонка и стоит ли ПланФиксу рассчитывать её получить.
Параметры запроса:
Имя | Описание | Тип/формат данных | Примечание |
---|---|---|---|
cmd | тип операции, в данном случае event | string | |
type | тип звонка | in/out | входящий / исходящий |
event | тип события, связанного со звонком:
|
string | |
phone | номер телефона клиента | string | |
diversion | внешний номер телефона АТС через который поступил или вышел звонок | string | |
ext | внутренний номер сотрудника АТС | string | |
callid | уникальный id звонка | string | |
duration | продолжительность звонка в секундах | int | при event=COMPLETED |
is_recorded | записан ли звонок | 0/1 | при event=COMPLETED |
status | статус входящего звонка:
статус исходящего звонка:
|
string | при event=COMPLETED |
record_link | ссылка на запись звонка, если АТС может предоставить её сразу, если нет - ссылка отправляется командой record | string | необязательный, при event=COMPLETED |
planfix_token | ключ (token) ПланФикса, указанный в настройках интеграции | string | |
data_имя_поля_аналитики | дополнительные данные, которые надо внести в аналитику звонка. имя поля в аналитике должно точно совпадать с текстом после data_, таких параметров может быть столько, сколько полей заполняется, по одному на каждое поле. К примеру, если вы передаете в запросе параметры data_utm_source и data_utm_medium, то для сохранения этих данных в ПланФиксе, необходимо в аналитике Звонок добавить поля типа Строка с названиями utm_source и utm_medium | string | при event=COMPLETED |
Пример запроса:
POST https://test.planfix.ru/tel/api
cmd=event
type=out
event=COMPLETED
phone=79101234567
ext=102
callid=D10D0EB124F4E64AF4EA-1511
duration=124
is_recorded=1
status=Success
record_link=https://link/file.mp3
planfix_token=303cb962ac59075b964b07152d234b70
data_utm_source=site.io
data_utm_medium=banner
Варианты ответа:
HTTP код | Тело | Описание |
---|---|---|
200 | ОК | |
400 | { error: "Invalid parameters" } | Переданы некорректные параметры |
401 | { error: "Invalid token" } | Передан неверный ключ (token) |
record
Уведомление содержит информацию о записи разговора. ПланФикс ожидает такого уведомления, если в команде event с event=COMPLETED и is_recorded=1 отсутствует параметр record_link. Использовать уведомление имеет смысл, если сохранение записей в Облачной АТС устроено таким образом, что ссылка может быть сформирована только через некоторое время.
Ссылка должна быть постоянной, для того чтобы в зависимости от настроек интеграции:
- файл по ней мог быть сохранен в ПланФиксе
- она могла бы использоваться для прослушивания записи напрямую с серверов АТС. (такая настройка активно запрашивается пользователями и будет реализована в скором времени для поддерживающих это телефоний)
Параметры запроса:
Имя | Описание | Тип/формат данных | Примечание |
---|---|---|---|
cmd | тип операции, в данном случае record | string | |
callid | уникальный id звонка | string | |
is_temp | ссылка временная и может использоваться только для однократного сохранения файла в ПланФиксе, прослушивание из облачной АТС невозможно | 0/1 | необязательный, при отсутствии считается равным 0 |
record_link | ссылка на запись звонка | string | |
planfix_token | ключ (token) ПланФикса, указанный в настройках интеграции | string |
Пример запроса:
POST https://test.planfix.ru/tel/api
cmd=record
callid=D10D0EB124F4E64AF4EA-1511
record_link=https://link/file.mp3
planfix_token=303cb962ac59075b964b07152d234b70
Варианты ответа:
HTTP код | Тело | Описание |
---|---|---|
200 | ОК | |
400 | { error: "Invalid parameters" } | Переданы некорректные параметры |
401 | { error: "Invalid token" } | Передан неверный ключ (token) |
Пример использования API при входящем звонке на группу сотрудников
- начался звонок
- для каждого сотрудника шлется запрос с его ext и INCOMING и одинаковым для всех идентификатором звонка - при этом в планфиксе показывается окно что идет звонок
- один из сотрудников снял трубку
- для него шлется ACCEPTED
- для остальных COMPLETED с Cancelled - при этом окно звонка у них исчезает
(идентификатор звонка общий для всех и тот же, что был в событии начала)
- звонок завершен
- шлется COMPLETED с Success и ext того сотрудника, который разговаривал. - показывается в планфиксе окно что звонок завершен, записывается аналитика