API для телефонии: различия между версиями
Artem (обсуждение | вклад) Нет описания правки |
Artem (обсуждение | вклад) Нет описания правки |
||
(не показаны 4 промежуточные версии 2 участников) | |||
Строка 82: | Строка 82: | ||
* event (POST) | * event (POST) | ||
* record (POST) | * record (POST) | ||
* ping (POST) | |||
Строка 204: | Строка 205: | ||
|- | |- | ||
|} | |} | ||
==== event ==== | ==== event ==== | ||
Строка 292: | Строка 294: | ||
|- | |- | ||
|} | |} | ||
==== record ==== | ==== record ==== | ||
Строка 344: | Строка 347: | ||
== Пример использования API при входящем звонке на группу сотрудников == | ==== ping ==== | ||
Позволяет проверить корректность подключения и параметров заданных на стороне ПланФикса. | |||
'''Параметры запроса:''' | |||
{| class="wikitable" style="margin-top: 1em; width:100% " | |||
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание | |||
|- | |||
|cmd || тип операции, в данном случае ping || string || | |||
|- | |||
|planfix_token || ключ (token) ПланФикса, указанный в настройках интеграции || string || | |||
|- | |||
|} | |||
'''Пример запроса:''' | |||
<source lang="bash"> | |||
POST https://test.planfix.ru/tel/api | |||
cmd=ping | |||
planfix_token=303cb962ac59075b964b07152d234b70 | |||
</source> | |||
'''Варианты ответа:''' | |||
{| class="wikitable" style="margin-top: 1em; width:100% " | |||
!width="150"|HTTP код !!width="50%"| Тело !! Описание | |||
|- | |||
|200|| { pbxToken: "value", pbxUrl: "https://domain.com/path" } || pbxToken - ключ авторизации АТС, указанный в настройках интеграции, pbxUrl - адрес АТС, указанный в настройках интеграции | |||
|- | |||
|401|| { error: "Invalid token" } || Передан неверный ключ (token) | |||
|- | |||
|} | |||
== Пример использования API при входящем звонке одновременно на группу сотрудников == | |||
- начался звонок | - начался звонок | ||
Строка 352: | Строка 389: | ||
* для него шлется ACCEPTED | * для него шлется ACCEPTED | ||
* для остальных COMPLETED с Cancelled - при этом окно звонка у них исчезает | * для остальных COMPLETED с Cancelled - при этом окно звонка у них исчезает | ||
(идентификатор звонка общий для всех и тот же, что был в событии начала) | |||
- звонок завершен | |||
* шлется COMPLETED с Success и ext того сотрудника, который разговаривал. - показывается в планфиксе окно что звонок завершен, записывается аналитика | |||
== Пример использования API при звонке на группу, с переводом по очереди между сотрудниками == | |||
- начался звонок | |||
* для первого сотрудника шлется запрос с его ext и INCOMING и идентификатором звонка - при этом в планфиксе показывается окно что идет звонок | |||
- сотрудник не берет трубку и звонок идет на следующиего сотрудника | |||
* для первого сотрудника шлется COMPLETED с Cancelled - при этом окно звонка у него исчезает | |||
* для второго - INCOMING | |||
(идентификатор звонка общий для всех и тот же, что был в событии начала) | |||
- второй сотрудник не берет трубку и звонок идет на следующиего сотрудника | |||
* для второго сотрудника шлется COMPLETED с Cancelled - при этом окно звонка у него исчезает | |||
* для третьего - INCOMING | |||
(идентификатор звонка общий для всех и тот же, что был в событии начала) | |||
- сотрудник снял трубку | |||
* для него шлется ACCEPTED | |||
(идентификатор звонка общий для всех и тот же, что был в событии начала) | (идентификатор звонка общий для всех и тот же, что был в событии начала) | ||
Текущая версия от 07:48, 21 ноября 2024
Общие сведения об 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)
- ping (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) |
ping
Позволяет проверить корректность подключения и параметров заданных на стороне ПланФикса.
Параметры запроса:
Имя | Описание | Тип/формат данных | Примечание |
---|---|---|---|
cmd | тип операции, в данном случае ping | string | |
planfix_token | ключ (token) ПланФикса, указанный в настройках интеграции | string |
Пример запроса:
POST https://test.planfix.ru/tel/api
cmd=ping
planfix_token=303cb962ac59075b964b07152d234b70
Варианты ответа:
HTTP код | Тело | Описание |
---|---|---|
200 | { pbxToken: "value", pbxUrl: "https://domain.com/path" } | pbxToken - ключ авторизации АТС, указанный в настройках интеграции, pbxUrl - адрес АТС, указанный в настройках интеграции |
401 | { error: "Invalid token" } | Передан неверный ключ (token) |
Пример использования API при входящем звонке одновременно на группу сотрудников
- начался звонок
- для каждого сотрудника шлется запрос с его ext и INCOMING и одинаковым для всех идентификатором звонка - при этом в планфиксе показывается окно что идет звонок
- один из сотрудников снял трубку
- для него шлется ACCEPTED
- для остальных COMPLETED с Cancelled - при этом окно звонка у них исчезает
(идентификатор звонка общий для всех и тот же, что был в событии начала)
- звонок завершен
- шлется COMPLETED с Success и ext того сотрудника, который разговаривал. - показывается в планфиксе окно что звонок завершен, записывается аналитика
Пример использования API при звонке на группу, с переводом по очереди между сотрудниками
- начался звонок
- для первого сотрудника шлется запрос с его ext и INCOMING и идентификатором звонка - при этом в планфиксе показывается окно что идет звонок
- сотрудник не берет трубку и звонок идет на следующиего сотрудника
- для первого сотрудника шлется COMPLETED с Cancelled - при этом окно звонка у него исчезает
- для второго - INCOMING
(идентификатор звонка общий для всех и тот же, что был в событии начала)
- второй сотрудник не берет трубку и звонок идет на следующиего сотрудника
- для второго сотрудника шлется COMPLETED с Cancelled - при этом окно звонка у него исчезает
- для третьего - INCOMING
(идентификатор звонка общий для всех и тот же, что был в событии начала)
- сотрудник снял трубку
- для него шлется ACCEPTED
(идентификатор звонка общий для всех и тот же, что был в событии начала)
- звонок завершен
- шлется COMPLETED с Success и ext того сотрудника, который разговаривал. - показывается в планфиксе окно что звонок завершен, записывается аналитика