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

Уведомление CRM о событиях

Вызов ф-ций данной версии API осуществляется по следующему URL: https://<Ваш субдомен>.t8s.ru/Api/V1/<Имя функции>. Т.е., к примеру, если ваш субдомен - «someschool», а имя функции - «OnRinging», то получится следующий URL: https://someschool.t8s.ru/Api/V1/OnRinging

Данные функции в случае успеха возвращают пустой результат.

OnRinging: Начало звонка

При вызове данной ф-ции в CRM у необходимого сотрудника(-ов) появляется окно о звонке.

Хотя бы один из номеров должен являться внутренним номером сотрудника, в том же виде, в котором он указан в CRM. В противном случае, ф-ция вернёт ошибку.

Список параметров (обязательные поля отмечены звёздочкой):

callId *	Идентификатор звонка.
from *	Номер звонящего.
to *	Номер адресата.
trunkNumber	Номер, через который осуществляется коммуникация (отображается в истории звонков).
continuableCallIds	Идентификаторы звонков, продолжением которых в рамках той же сессии является данный звонок, разделённые запятой.
utm	UTM-метки в JSON-формате (используются при создании лида из звонка).

Звонки из continuableCallIds должны существовать к моменту вызова данного метода.
Вместо continuableCallIds в данном методе можно использовать continuingCallIds из метода OnHangup (смотря какое событие наступает раньше), но только что-то одно.
Если в continuableCallIds в ID одного из звонков содержится запятая, её необходимо экранировать второй запятой.

OnChangedCallerId: Смена одного из значений CallerID в длящемся звонке

С помощью данной ф-ции можно заменить номер одной из сторон во время звонка.

Заменить можно только внешний номер, внутренний номер сотрудника не меняется.

Список параметров (все поля являются обязательными):

callId	Идентификатор звонка.
old	Старое значение CallerID.
new	Новое значение CallerID.

OnAnswer: Подтверждение звонка (снятие трубки)

Список параметров (все поля являются обязательными):

callId

Идентификатор звонка.

OnHangup: Завершение звонка

При вызове данной ф-ции в CRM закрываются окна о звонке и звонок добавляется в историю.

Список параметров (обязательные поля отмечены звёздочкой):

callId *	Идентификатор звонка.
cause	Причина завершения звонка (отображается в истории у непринятых звонков).
audioUrl	Ссылка на запись звонка (если указана, то для данного звонка не будет вызываться вебхук для запроса аудиофайла звонка).
continuingCallIds	Идентификаторы звонков, которые в рамках той же сессии являются продолжением данного звонка, разделённые запятой.
addToHistory	Добавить звонок в историю (по умолчанию true).

Webhooks (функции обратного вызова)

Общая информация

Ссылки на данные ф-ции задаются в настройках CRM.

Авторизация

Для проверки подлинности вызова можно использовать произвольный ключ (задаётся в настройках CRM, не обязателен).

Данный ключ придёт в качестве параметры «key» в каждый из нижеуказанных методов (для краткости не указан в списке параметров).

Однако более надёжный способ - использовать https и выполнять проверку клиентского сертификата на валидность и поле Common Name (CN), которое должно быть равным «*.t8s.ru».

Возвращаемые данные

Возвращаемые данные (если они предусмотрены) должны быть представлены в виде JSON.

В случае ошибки вебхук-методы должны возвращать текст ошибки в поле «Error».

Если возвращаемый код состояния HTTP свидетельствует об ошибке, так же будет отображён соответствующий ему текст ошибки, но текст в поле «Error» имеет больший приоритет.

События CRM

Исходящий вызов

Вызывается при клике пользователем CRM на кнопку с изображением трубки возле номера телефона.
Если обработчик не указан, эти кнопки будут скрыты.

Клик по кнопке не является для CRM событием начала звонка. Звонок можно начать только вызовом метода OnRinging.

Список параметров:

from	Номер звонящего.
to	Номер адресата.

Возвращаемых данных не предусмотрено.

Завершение звонка

Вызывается при клике пользователем CRM на кнопку «Завершить» в окне звонка.
Если обработчик не указан, эта кнопка будет скрыта.

Список параметров:

callId

Идентификатор звонка.

Возвращаемых данных не предусмотрено.

Запрос аудиофайла

Вызывается при клике пользователем CRM на кнопку для воспроизведения состоявшегося звонка из истории звонков.
Если обработчик не указан, эти кнопки будут скрыты (кроме тех звонков, для которых был указан параметр audioUrl в ф-ции OnHangup).

Список параметров:

created	Unix timestamp начала звонка.
finished	Unix timestamp завершения звонка.
employeePhones	Внутренние номера телефонии, установленные в данный момент у сотрудника, являющегося одной из сторон звонка.
remotePhone	Внешний номер (может быть также внутренним номером сотрудника при внутреннем звонке).
incoming	Признак того, что звонок является входящим относительно первого сотрудника (employeePhones).

Метод должен возвращать поле «Urls» с массивом URL’ов аудиофайлов (массив – на случай, если совпадений несколько), даже если запись одна.
Если запись не найдена, можно возвратить как пустой массив, так и пустой результат (более корректным является первый вариант).

Пример результата

{
	"Urls": [
		"https://demo.t8s.ru/Files/demo.t8s.ru/Audio/btns4dtz.mfl.mp3",
		"https://demo.t8s.ru/Files/demo.t8s.ru/Audio/vsape2r3.54l.mp3"
	]
}