API для телефонии

Материал из Planfix
Версия от 07:48, 21 ноября 2024; Artem (обсуждение | вклад)
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)
Перейти к: навигация, поиск

Общие сведения об API

API позволяет подключить к ПланФикс любую вашу собственную Облачную АТС.

Интеграция ПланФикса и Облачной АТС решает несколько бизнес-задач:


  • получение имени звонящего по номеру телефона, для того, чтобы его можно было отобразить на экране телефона или sip-клиента;
  • автоматическая маршрутизация входящего звонка от клиента на менеджера, который закреплен за этим клиентом;
  • отображение информации о входящем звонке непосредственно внутри ПланФикса (всплывающее окно при звонке)
  • сохранение в ПланФиксе истории всех звонков и записей разговоров;
  • совершение исходящих звонков сразу из интерфейса ПланФикса.


Интеграция должна быть двухсторонней. Поэтому часть запросов ПланФикс посылает в сторону Облачной АТС на указанные точки входа, а часть запросов, наоборот, Облачная АТС посылает в сторону ПланФикса на единую точку входа.

Взаимодействие производится по протоколу HTTPS. Авторизация осуществляется по адресу ПланФикса или Облачной АТС соответственно и авторизационному ключу, полученному в процессе настройки интеграции.


Принцип авторизации и взаимодействия

HTTPS:

  • Запросы к ПланФиксу принимаются только по протоколу HTTPS. Это обеспечивает достаточный уровень безопасности для общения систем через Интернет.
  • В целях безопасности ваших данных, пожалуйста, реализуйте прием запросов на стороне АТС также с использованием HTTPS.


Ключ (token):

  • Дополнительно для авторизации каждого запроса к ПланФиксу используется специальный ключ (token). Получить его можно в настройках интеграции.
  • Пожалуйста, реализуйте прием запросов на стороне АТС также с использованием ключа (token). Сгенерируйте ключ и вставьте его в соответствующее поле в разделе настройки интеграции.
  • Ключи создаются один раз при настройке интеграции. При необходимости, вы можете сменить ключ на своей стороне и обновить его интерфейсе ПланФикса.


Запросы от Облачной АТС к ПланФиксу:

  • Запросы необходимо отправлять на указанный в настройках интеграции адрес для приема уведомлений.
  • В теле запроса в специальном поле «token» необходимо всегда передавать специальный ключ.
  • Запросы передаются в application/x-www-form-urlencoded формате


Запросы от ПланФикса к Облачной АТС:

  • ПланФикс будет отправлять все запросы на указанный в настройках интеграции адрес.
  • В теле сообщений ПланФикс будет передавать указанный вами в веб-кабинете ключ (token).
  • Запросы передаются в application/x-www-form-urlencoded формате


Ответы

  • Все ответы на запросы Облачной АТС ПланФикс присылает в формате JSON в теле ответа.
  • Все ответы на запросы ПланФикса Облачная АТС должна присылать в формате JSON в теле ответа.

Подключение в интерфейсе ПланФикса

Для подключения и настройки интеграции перейдите в раздел Интеграции - Виртуальные АТС

QuIbQG.png


В открывшемся разделе выберите Api ПланФикса для телефоний (в конце списка).

EWRRqq.png


Откроется окно настроек интеграции.

TJVltJ.png


Из него необходимо будет взять адрес для отправки запросов в ПланФикс (он свой для каждого аккаунта) и токен (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 тип события, связанного со звонком:
  • 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


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

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 того сотрудника, который разговаривал. - показывается в планфиксе окно что звонок завершен, записывается аналитика

Перейти

Источник — http://planfix.com/ru/help/index.php?title=API_для_телефонии&oldid=47086