Интеграция со своей CRM (открытый REST API)

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

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

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

получение имени звонящего по номеру телефона, для того, чтобы его можно было отобразить на экране телефона или sip-клиента;

автоматическая маршрутизация входящего звонка от клиента на менеджера, который закреплен за этим клиентом;

отображение информации о входящем звонке непосредственно внутри CRM (всплывающая карточка клиента)

сохранение в CRM истории всех звонков и записей разговоров;

совершение исходящих звонков сразу из интерфейса CRM.

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

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

Для работы с API необходимо реализовать ответную часть на стороне вашей CRM или базы данных.

Если вы хотите подключить какую-либо популярную Облачную или Коробочную CRM и она не присутствует в списке интеграций, то обратитесь в службу поддержки.

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

HTTPS:

Запросы к Облачной АТС принимаются только по протоколу HTTPS. Это обеспечивает достаточный уровень безопасности для общения систем через Интернет.

В целях безопасности ваших данных, пожалуйста, реализуйте прием запросов на стороне CRM также с использованием HTTPS.

Ключ (token):

Дополнительно для авторизации каждого запроса к Облачной АТС используется специальный ключ (token). Получить его можно в веб-кабинете Облачной АТС.

Пожалуйста, реализуйте прием запросов на стороне CRM также с использованием ключа (token). Сгенерируйте ключ и вставьте его в соответствующей поле в разделе настройки интеграции через API веб-кабинета Облачной АТС.

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

Запросы от CRM или базы данных к Облачной АТС:

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

В теле запроса в специальном поле "token" необходимо всегда передавать специальный ключ.

Запросы от Облачной АТС к CRM или базе данных:

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

В теле сообщений Облачная АТС будет передавать указанный вами в веб-кабинете ключ (token).

3. Список команд API

От Облачной АТС к CRM или базе данных:

history (POST)

event (POST)

contact (POST)

От CRM или базы данных к Облачной АТС:

makeCall (POST)

accounts (POST)

4. Команды API и примеры доступных сценариев

4.1 Команды от Облачной АТС к CRM или базе данных

Пожалуйста, реализуйте принимающую и ответную часть для этих команд.

4.1.1 Команда history (POST)

Входящий звонок клиента и ссылка на запись разговора записывается в CRM Всегда подключено

Исходящий звонок клиента и ссылка на запись разговора записывается в CRM Всегда подключено

После успешного звонка в CRM отправляется запрос с данными о звонке и ссылкой на запись разговора.
Команда может быть использована для сохранения в данных ваших клиентов истории и записей входящих и исходящих звонков.

Команда доступна сразу после включения API.

Входные параметры:

Имя	Описание	Тип/формат данных	Обязательный параметр
cmd	тип операции, в данном случае history	string	да
type	тип звонка in/out (входящий/исходящий)	string	да
user	идентификатор пользователя облачной АТС (необходим для сопоставления на стороне CRM)	string	да
phone	номер телефона клиента, с которого или на который произошел звонок	string / E164	да
diversion	ваш номер телефона, через который пришел входящий вызов	string / E164	да
duration	общая длительность звонка в секундах	number	да
callid	уникальный id звонка	string	да
link	ссылка на запись звонка, если она включена в Облачной АТС	string
crm_token	ключ (token) от CRM, установленный в веб-кабинете	string	да
status	статус входящего звонка: Success - успешный входящий или исходящий звонок Внимание! API не предусмотрена информация о не отвеченных входящих звонках. статус исходящего звонка: Success - успешный исходящий звонок Busy - мы получили ответ Занято NotAvailable - мы получили ответ Абонент недоступен NotAllowed - мы получили ответ Звонки на это направление запрещены	string	да

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

POST https://crm.ru/crm_integration.php

cmd=history
type=in / out
status=Success
phone=79101234567
user=user
duration=124

link=https://link/file.mp3

crm_token=76fsd7tfs-fhjdgfdjsfsk-hfgsdguuuwoeiwey1111
callid=B10D0EB124F4E64AF4EA-1511

Выходные данные:

Код	Содержание	Описание
200		ОК
400	{ error: "Invalid parameters" }	Переданы некорректные параметры
401	{ error: "Invalid token" }	Передан неверный ключ (token)

4.1.2 Команда event (POST)

При входящем звонке всплывает карточка клиента с его именем Всегда подключено

Облачная АТС отправляет в вашу CRM уведомления о событиях входящих звонков пользователям: появлении, принятии или завершении звонка. Команда может быть использована для отображения всплывающей карточки клиента в интерфейсе CRM.

Команда доступна сразу после включения API.

Входные параметры:

Имя	Описание	Тип/формат данных	Обязательный параметр
cmd	тип операции, в данном случае event	string	да
type	type - это тип события, связанного со звонком INCOMING - пришел входящий звонок (в это время у менеджера должен начать звонить телефон). ACCEPTED - звонок успешно принят (менеджер снял трубку). В этот момент можно убрать всплывающую карточку контакта в CRM. COMPLETED - звонок успешно завершен (менеджер или клиент положили трубку после разговора). CANCELLED - звонок сброшен (клиент не дождался пока менеджер снимет трубку. Либо, если это был звонок сразу на группу менеджеров, на звонок мог ответить кто-то еще).	string	да
phone	номер телефона клиента	string / E.164	да
diversion	ваш номер телефона, через который пришел входящий вызов	string / E.164
user	идентификатор пользователя облачной АТС (необходим для сопоставления на стороне CRM)	string	да
callid	уникальный id звонка, совпадает для всех связанных звонков	string	да
crm_token	ключ (token) от CRM, установленный в веб-кабинете	string	да

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

POST https://crm.ru/crm_integration.php

cmd=event type=INCOMING / COMPLETED / ACCEPTED / CANCELLED
phone=79101234567
user=andy
crm_token=76fsd7tfs-fhjdgfdjsfsk-hfgsdguuuwoeiwey1111
callid=B10D0EB124F4E64AF4EA-1511

Выходные данные:

Код	Содержание	Описание
200		ОК
400	{ error: "Invalid parameters" }	Переданы некорректные параметры
401	{ error: "Invalid token" }	Передан неверный ключ (token)

4.1.3 Команда contact (POST)

Команда для получения информации о названии клиента и ответственном за него сотруднике по номеру его телефона. Команда вызывается при поступлении нового входящего звонка.

При входящем звонке имя клиента отображается на экране IP-телефона или коммуникатора Всегда подключено

Команда используется для отображения на экране IP-телефона или в коммуникаторе на ПК сотрудника названия клиента.

Этот функционал доступен сразу после включения API.

Звонки от клиентов будут перенаправляться ответственному менеджеру, указанному в CRM

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

Входные параметры:

Имя	Описание	Тип/формат данных	Обязательный параметр
cmd	тип операции, в данном случае contact	string	да
phone	номер телефона клиента	string / E164	да
crm_token	ключ (token) от CRM, установленный в веб-кабинете	string	да
callid	уникальный id звонка, совпадает для всех связанных звонков	string	да

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

POST https://crm.ru/crm_integration.php

cmd=contact
phone=79101234567
crm_token=76fsd7tfs-fhjdgfdjsfsk-hfgsdguuuwoeiwey1111
callid=B10D0EB124F4E64AF4EA-1511

Выходные данные:

Код	Содержание	Описание
200	{ contact_name: "Менеджер ЗАО Рога и копыта", // имя контакта responsible:andy // id ответственного пользователя. Нужно для автоматической маршрутизации звонка } Ответ обязан быть в JSON.	ОК
400	{ error: "Invalid parameters" }	Переданы некорректные параметры
401	{ error: "Invalid token" }	Передан неверный ключ (token)

4.2 Команды от CRM или базы данных к Облачной АТС

Пожалуйста, реализуйте отправку и приемку ответов для этих команд.

4.2.1 Команда accounts (POST)

CRM получает список сотрудников из Облачной АТС для сопоставления Всегда подключено

Запрос от CRM к Облачной АТС для получения сотрудников.

Может использоваться для сопоставления пользователей в CRM и Облачной АТС. Для этого вам придётся реализовать функционал сопоставления. Вы можете так же настраивать сопоставление пользователей на вашей стороне вручную, без использования этой команды.

Команда доступна сразу после включения API.

Входные параметры:

Имя	Описание	Тип/формат данных	Обязательный параметр
cmd	тип операции, в данном случае accounts	string	да
token	ключ (token) Облачной АТС, полученный в веб-кабинете	string	да

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

POST https://domain/sys/crm_api.wcgp

cmd=accounts
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

Выходные параметры:

Код	Содержание	Описание
200	[ {"name":"test","realName":"Тестовый пользователь"}, {"name":"daria","realName":"Иванова Дария"}, {"name":"andy","realName":"Петров Андрей"}, {"name":"mike","realName":"Семенов Михаил"}, {"name":"serg","realName":"Чижиков Сергей"} ]	ОК
400	{ error: "Invalid parameters" }	Переданы некорректные параметры
401	{ error: "Invalid token" }	Передан неверный ключ (token)

4.2.2 Команда makeCall (POST)

Кликом по номеру клиента в CRM совершается исходящий звонок клиенту Всегда подключено

Команда необходимая для того, чтобы инициировать звонок от менеджера клиенту. В результате успешного выполнения команды, Облачная АТС сделает сначала звонок на телефон менеджера, а потом соединит его с клиентом. Команда может использоваться, например, для звонка по клику на номер клиента в вашей CRM или базе данных.

Команда доступна сразу после включения API.

Входные параметры:

Имя	Описание	Тип/формат данных	Обязательный параметр
cmd	тип операции, в данном случае makeCall	string	да
phone	номер, на который последует звонок	string / E164	да
user	пользователь Облачной АТС, от которого последует звонок	string	да
token	ключ (token) Облачной АТС, полученный в веб-кабинете	string	да

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

POST https://domain/sys/crm_api.wcgp

cmd=makeCall
phone=79101234567
user=andy
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

Выходные данные:

Код	Содержание	Описание
200		ОК
400	{ error: "Invalid parameters" }	Переданы некорректные параметры
401	{ error: "Invalid token" }	Передан неверный ключ (token)

4.3 Прочие возможные сценарии использования

На основе имеющихся команд вы можете реализовать в вашей CRM другие полезные функции, например:

Автоматическое создание нового контакта или лида для каждого пропущенного звонка с неизвестного номера с назначением на старшего менеджера. Это полезно для контроля результатов по работе с пропущенными звонками. Если контакту не перезвонили, он так и останется на старшем менеджере. Старший менеджер всегда увидит такие контакты.

Автоматическое создание нового контакта или лида для каждого исходящего звонка на неизвестный номер. Позволяет быстро и удобно актуализировать базу контактов в CRM.

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