Проекты

REST API ВАТС

Прокрутите вниз
На главную

REST API Облачной АТС

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

ТЕЛКОМ разработчик
РАЗРАБОТЧИКАМ И ПРОГРАММИСТАМ

Интеграция с CRM
REST API Облачной АТС

Интеграция CRM и Облачной АТС TELCOM решает бизнес-задачи:
получение имени звонящего по номеру телефона, для того, чтобы его можно было отобразить на экране телефона или sip-клиента;
автоматическая маршрутизация входящего звонка от клиента на менеджера, который закреплен за этим клиентом;
отображение информации о входящем звонке непосредственно внутри CRM (всплывающая карточка клиента);
сохранение в CRM истории всех звонков и записей разговоров;
совершение исходящих звонков сразу из интерфейса CRM.
Скачать PDF
01.

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

Интеграция CRM и Облачной АТС TELCOM

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

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

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

HTTPS:

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

Ключ (token):

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

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

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

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

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

Ответы:

— Все ответы на запросы CRM Облачная АТС TELCOM присылает в формате JSON в теле ответа (body). Исключение составляет только команда history, которая возвращает ответ в CSV.
— Все ответы на запросы Облачной АТС TELCOM, CRM должна присылать в формате JSON в теле
ответа (body).

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

— history (POST)
— event (POST)
— contact (POST)

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

— accounts (GET / POST)
— groups (GET / POST)
— makeCall (POST)
— history (GET / POST)
— subscribeOnCalls (POST)
— subscriptionStatus (GET / POST)
— set_dnd (POST)
— get_dnd (GET / POST)

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

Команда history (POST)

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

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

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

 

Имя Описание Тип/формат данных Обязательный параметр
cmd тип операции, в данном случае history string да
type тип звонка in/out (входящий/исходящий) string да
user идентификатор пользователя облачной АТС TELCOM (необходим для сопоставления на стороне CRM) string да
ext внутренний номер пользователя облачной АТС TELCOM, если есть string нет
groupRealName название отдела, если входящий звонок прошел через отдел string нет
telnum прямой телефонный номер пользователя облачной АТС TELCOM, если есть string нет
phone номер телефона клиента, с которого или на который произошел звонок string / E164 да
diversion ваш номер телефона, через который пришел входящий вызов string / E164
start время начала звонка в формате YYYYmmddTHHMMSSZ timestamp да
duration общая длительность звонка в секундах number да
callid уникальный id звонка string да
link ссылка на запись звонка, если она включена в Облачной АТС TELCOM string
crm_token ключ (token) от CRM, установленный в веб-кабинете string да
status статус входящего звонка:
— Success — успешный входящий звонок
— missed – пропущенный входящий звонок
статус исходящего звонка:
— Success — успешный исходящий звонок
— Busy — мы получили ответ Занято
— NotAvailable — мы получили ответ Абонент недоступен
— NotAllowed — мы получили ответ Звонки на это направление запрещены
— call A error – вызов менеджера при выполнении команды makecall завершился ошибкой
string да

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

POST https://crm.ru/crm_integration.php
cmd=history
type=out
status=Success
phone=79101234567
user=user
start=20170703T121110Z
duration=124
link=https://link/file.mp3
crm_token=76fsd7tfs-fhjdgfdjsfsk-hfgsdguuuwoeiwey1111
callid=B10D0EB124F4E64AF4EA-1511

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

 

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

Команда event (POST)

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

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

Имя Описание Тип/формат данных Обязательный параметр
cmd тип операции, в данном случае event string да
type type — это тип события, связанного со звонком
 — INCOMING — пришел входящий звонок (в это время у
менеджера должен начать звонить телефон).
 — ACCEPTED — звонок успешно принят (менеджер снял трубку). В этот момент можно убрать всплывающую карточку контакта в CRM.
 — COMPLETED — звонок успешно завершен (менеджер или клиент положили трубку после разговора).
 — CANCELLED — звонок сброшен (клиент не дождался
пока менеджер снимет трубку. Либо, если это был
звонок сразу на группу менеджеров, на звонок мог
ответить кто-то еще).
 — OUTGOING — менеджер совершает исходящий звонок (в это время облачная АТС TELCOM пытается дозвониться до клиента).
string да
phone номер телефона клиента string / E.164 да
diversion ваш номер телефона, через который пришел входящий вызов string / E.164
user идентификатор пользователя облачной АТС TELCOM (необходим для сопоставления на стороне CRM) string да
groupRealName название отдела, если входящий звонок прошел через отдел string нет
ext внутренний номер пользователя облачной АТС TELCOM, если есть string нет
telnum прямой телефонный номер пользователя облачной АТС TELCOM, если есть string нет
calid уникальный id звонка, совпадает для всех связанных звонков timestamp да
duration общая длительность звонка в секундах number да
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 Ok
400 { error: «Invalid parameters» } Переданы некорректные параметры
401 { error: «Invalid token» } Передан неверный ключ (token)

Команда contact (POST)

Команда для получения информации о названии клиента и ответственном за него сотруднике по номеру его телефона. Команда вызывается при поступлении нового входящего звонка.
При входящем звонке имя клиента отображается на экране IP-телефона или коммуникатора — Всегда подключено!
Команда используется для отображения на экране IP-телефона или в коммуникаторе на ПК сотрудника названия клиента.
Этот функционал доступен сразу после включения API.
Звонки от клиентов будут перенаправляться ответственному менеджеру, указанному в CRM — Настроить!
Также в Облачной АТС TELCOM можно включить функцию автоматического перевода каждого звонка от клиента сразу на ответственного за него менеджера, указанного в CRM. Данная функция активируется вручную в веб-кабинете Облачной АТС TELCOM. При включении вам будет необходимо выбрать номер(а) телефона, на котором будет работать данная функция, а также определить на кого будет переведен звонок, если ответственный сотрудник не отвечает или занят.

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

Имя Описание Тип/формат данных Обязательный параметр
cmd тип операции, в данном случае contact string да
phone номер телефона клиента string / E.164 да
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 ответственного пользователя.
Нужно для автоматической маршрутизации звонка
}
Ok
400 { error: «Invalid parameters» } Переданы некорректные параметры
401 { error: «Invalid token» } Передан неверный ключ (token)

В поле responsible может быть передан логин, внутренний номер или прямой телефонный номер пользователя Облачной АТС TELCOM.

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

Команда accounts (GET / POST)

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

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

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

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

POST https://domain/sys/crm_api.wcgp
cmd=accounts
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

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

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

Команда groups (GET / POST)
CRM получает список всех отделов из Облачной АТС или список отделов, в которые входит указанный сотрудник — Всегда подключено!
Запрос от CRM к Облачной АТС для получения отделов. Команда доступна сразу после включения API.

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

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

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

POST https://domain/sys/crm_api.wcgp
cmd=groups
user=u1
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

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

Код Содержание Описание
200 [
{«id»:»sales»,»realName»:»Отдел продаж», ext: 701},
{«id»:»gr001″,»realName»:»Бухгалтерия», ext: 705},
]
Список отделов
400 { error: «Invalid parameters» } Переданы некорректные параметры
401 { error: «Invalid token» } Передан неверный ключ (token)

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

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

Команда makeCall (POST)

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

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

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

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

POST https://domain/sys/crm_api.wcgp
cmd=makeCall
phone=79101234567
user=andy
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

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

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

Команда history (GET / POST)

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

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

Имя Описание Тип/формат данных Обязательный параметр
cmd тип операции, в данном случае history string да
token ключ (token) Облачной АТС TELCOM, полученный в веб-кабинете string да
start начало периода для выгрузки данных
end jокончание периода для выгрузки данных string нет
period период, за который надо выгрузить данные.
Возможные значения:
today – звонки за сегодня
yesterday – звонки за вчера
this_week – звонки за текущую неделю
last_week – звонки за прошедшую неделю
this_month – звонки за текущий месяц
last_month – звонки за прошедший месяц
Если в запросе установлено значение period, выгружаются данные за указанный период,
string нет
type тип звонка:
all – все звонки
in – только входящие
out – только исходящие
missed – только пропущенные
Если не задан, используется all
string нет
limit Результат должен содержать не более, чем limit записей string нет

Значения start и end указываются в UTC, в формате YYYYmmddTHHMMSSZ, где
YYYY – год
mm – месяц
dd – день
HH – часы
MM – минуты
SS – секунды
T — разделитель

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

POST https://domain/sys/crm_api.wcgp
cmd=history
period=today
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

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

Код Содержание Описание
200 Значения истории, разделенные запятыми
UID,type,client,account,via,start,wait,duration,record
OK
400 { error: «Invalid parameters» } Переданы некорректные параметры
401 { error: «Invalid token» } Передан неверный ключ (token)

Поля в таблице:

Поле Содержание
UID уникальный идентификатор звонка
type тип вызова: in / out / missed
client номер клиента
account логин сотрудника, который разговаривал с клиентом или имя группы или код: ivr / fax, если звонок не дошел до сотрудника
via номер телефона, через который пришел входящий звонок или АОН для исходящего вызова
start время начала звонка в UTC
wait время ожидания на линии (секунд)
duration длительность разговора (секунд)
record ссылка на запись разговора

Команда subscribeOnCalls (POST)

CRM может включить или выключить прием звонков сотрудником во всех его отделах или конкретном отделе — Всегда подключено!
Запрос от CRM к Облачной АТС TELCOM для включение / выключения приема звонков сотрудником во всех его отделах или конкретном отделе. Может использоваться для того, чтобы временно выключить прием звонков сотрудником во всех его отделах или конкретном отделе. Команда доступна сразу после включения API.

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

Имя Описание Тип/формат данных Обязательный параметр
cmd тип операции, в данном случае subscribeoncalls string да
token ключ (token) Облачной АТС TELCOM, полученный в веб-кабинете string да
user идентификатор пользователя CRM или аккаунт ВАТС, если при авторизации был установлен self_map = true, для которого надо
выключить/включить прием звонков
string да
group_id идентификатор отдела ВАТС, в котором надо выключить/вклю-
чить прием звонков
string нет
status on — чтобы включить прием звонков, off — чтобы выключить прием звонков string да

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

POST https://domain/sys/crm_api.wcgp
cmd=subscribeoncalls
user=ivanov
group_id=sales
status=off
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

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

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

Команда subscriptionStatus (GET / POST)

CRM может запросить информацию о том, принимает или не принимает звонки сотрудник в отделе — Всегда подключено!
Запрос от CRM к Облачной АТС TELCOM для проверки факта приема звонков сотрудником в конкретном отделе. Команда доступна сразу после включения API.

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

Имя Описание Тип/формат данных Обязательный параметр
cmd тип операции, в данном случае subscribtionstatus string да
token ключ (token) Облачной АТС TELCOM, полученный в веб-кабинете string да
user идентификатор пользователя CRM или аккаунт ВАТС, если при авторизации был установлен self_map = true, для которого надо
выполнить проверку
string да
group_id идентификатор отдела ВАТС, для которого надо выполнить проверку string да

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

POST https://domain/sys/crm_api.wcgp
cmd=subscribtionstatus
user=ivanov
group_id=sales
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

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

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

Команда set_dnd (POST)

CRM может включить или выключить прием звонков сотрудником (режим do not disturb) — Всегда подключено!
Запрос от CRM к Облачной АТС TELCOM позволяет включить или выключить прием звонков сотрудником Облачной АТС. Команда доступна сразу после включения API.

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

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

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

POST https://domain/sys/crm_api.wcgp
cmd=set_dnd
user=ivanov
state=true
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

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

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

Команда get_dnd (POST)
CRM может проверить факт прием звонков сотрудником (включен или выключен режим do not disturb) — Всегда подключено!
Запрос от CRM к Облачной АТС TELCOM позволяет узнать включен или выключен прием звонков сотрудником Облачной АТС. Команда доступна сразу после включения API.

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

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

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

POST https://domain/sys/crm_api.wcgp
cmd=get_dnd
user=ivanov
token=5f317b9f-e86c-41f7-a6fc-c76eb0da0000

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

Код Содержание Описание
200 { state: true | false} Состояние DND
400 { error: «Invalid parameters» } Переданы некорректные параметры
401 { error: «Invalid token» } Передан неверный ключ (token)

На основе имеющихся команд вы можете реализовать в вашей CRM другие полезные функции, например:
— Автоматическое создание нового контакта или лида для каждого пропущенного звонка с неизвестного номера с назначением на старшего менеджера. Это полезно для контроля результатов по работе с пропущенными звонками. Если контакту не перезвонили, он так и останется на старшем менеджере. Старший менеджер всегда увидит такие контакты.
— Автоматическое создание нового контакта или лида для каждого исходящего звонка на неизвестный номер. Позволяет быстро и удобно актуализировать базу контактов в CRM.
— Сохранять историю и записи звонков сотрудников, которые есть в Облачной АТС TELCOM, но их нет в CRM, от лица пользователя CRM по умолчанию, например, от пользователя «все остальные» или «админ». Так вся история звонков и записи разговоров всегда будут в вашей CRM.