Интеграция со своей 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тип операции, в данном случае historystringда
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тип операции, в данном случае eventstringда
typetype - это тип события, связанного со звонком
  • 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тип операции, в данном случае contactstringда
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тип операции, в данном случае accountsstringда
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тип операции, в данном случае makeCallstringда
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.