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

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

Перейти

• Разработчикам: API