api:telephony

Телефония

Методы предназначены для интеграции с телефонией в контакт-центрах: регистрации новой клиентской заявки при поступлении звонка, поднятия трубки оператором (Pyrus автоматически откроет у оператора окно с заявкой), завершения звонка с прикладыванием аудиозаписи.

О том, как подключить интеграцию, читайте в разделе Расширения.

Методы

POST /calls

Регистрация звонка
Метод возвращает GUID зарегистрированного звонка и id созданной задачи.

POST https://api.pyrus.com/v4/calls

{
  "to": "+790000000",
  "from": "+790000000",
  "extension": "0000000",
  "integration_guid": "5d8dc3d6-27e7-4cd4-a057-2b4f4d74e0a5"
}
Показать ответ

{
  "call_guid": "718c41fb-6b8b-48af-8863-b048d70d9589",
  "task_id": "43534533145"
}

Параметры

Наименование Описание
to Номер телефона оператора, на который был совершён звонок.
from * Номер телефона позвонившего.
extension Внутренний номер оператора. Определяет сотрудника, на которого будет зарегистрировано событие. Для этого нужно, чтобы поле «Рабочий телефон» в профиле пользователя Pyrus было заполнено. В этом случае при указании параметра происходит поиск по пользователям, и, если соответствие обнаружено, заполняется поле «Ответственный». Если звонок записывается в уже существующую задачу, то ответственный меняется на нового и информация об этом появляется в комментариях.
integration_guid * GUID, сгенерированный при подключении интеграции к форме.
call_guid GUID звонка, который регистрируется за новым входящим звонком для того, чтобы к звонку можно было добавлять дополнительную информацию.
task_id id задачи, которая была создана при вызове функции или к которой информация об осуществлённом звонке добавилась в виде комментария.
* поле обязательно для заполнения

Ошибки

Наименование Описание
invalid_value_format Не удается преобразовать переданное значение к заданному типу (в сообщении об ошибке будет указано, к какому именно).
required_field_missing Не заполнено обязательное поле формы (в сообщении об ошибке будет указано, какое именно).
unrecognized_integration_guid В параметре integration_guid передан несуществующий id интеграции.

PUT calls/{call_guid}

Добавление информации по звонку
При вызове данной функции параметры могут быть скомбинированы в любом сочетании. Каждый параметр либо записывается в соответствующее поле задачи, в которой находится звонок по соответствующему call_guid, либо добавляется в виде комментария, если этот звонок не первый. Функция может вызываться неоднократно, добавляя в задачу новую информацию о первичном звонке или перезаписывая уже существующую в виде комментария с повторным звонком с одного номера.

POST https://api.pyrus.com/v4/calls/718c41fb-6b8b-48af-8863-b048d70d9589

{
  "start_time": "2009-02-15T00:00:00Z",
  "end_time": "2009-02-15T00:00:00Z",
  "rating": 5,
  "disconnect_party": "agent",
  "call_status": "answered",
  "file_guid": "2d7fee85-1671-43de-8b72-3bf07032c443"
} 

Параметры

Наименование Описание
start_time Время, когда начался входящий звонок (временной формат в UTC, YYYY-MM-DDThh:mm:ssZ).
end_time Время, когда звонок был закончен (временной формат в UTC, YYYY-MM-DDThh:mm:ssZ).
rating Оценка звонка (целое число от 1 до 5).
disconnect_party Кем был завершён разговор. Варианты: «agent», «client», «error», «other» (текстовое значение с ограниченным выбором вариантов).
call_status Статус звонка. Варианты: «answered», «no answer», «busy», «error», «other» (текстовое значение с ограниченным выбором вариантов).
file_guid Уникальный идентификатор файла, который был загружен с помощью функции /files/upload. Загруженный файл прикрепляется в виде комментария с указанием, что это канал телефонного звонка. При попытке прикрепить файл будет проверено, что его расширение соответствует одному из аудиоформатов (ac3, mp3, ogg, wav, wma). В случае несоответствия файл не будет прикреплён и будет возвращена ошибка.

Ошибки

Наименование Описание
invalid_value_format Не удается преобразовать переданное значение к заданному типу (в сообщении об ошибке будет указано, к какому именно).
unrecognized_attachment_id Идентификатор прикладываемого файла неверен. У пользователя отсутствует файл с указанным идентификатором.
access_denied_task Нет прав доступа к запрашиваемой задаче. Убедитесь, что у пользователя, от имени которого выполняется запрос, есть все необходимые права.
unrecognized_call_guid Идентификатор звонка не существует в системе.
unsupported_attachment_format Прикладываемый файл имеет расширение, не соответствующее доступному списку форматов аудиофайлов.

POST calls/{call_guid}/event

Регистрация события по звонку
Сейчас поддерживается только событие «ответ на звонок». При его регистрации у оператора автоматически открывается страница с обращением клиента.

POST https://api.pyrus.com/v4/calls/718c41fb-6b8b-48af-8863-b048d70d9589/event

{
  "event_type": "show",
  "extension": "0000000"
}

Параметры

Наименование Описание
event_type Событие, которое регистрируется в системе. Варианты: «show».
extension Внутренний номер оператора. Определяет сотрудника, на которого будет зарегистрировано событие. Для этого нужно, чтобы поле «Рабочий телефон» в профиле пользователя Pyrus было заполнено. Если поле пустое, то применяется значение, которое было использовано при создании звонка.

Ошибки

Наименование Описание
unrecognized_call_guid Идентификатор звонка не существует в системе.

Была ли эта статья полезной?

Да, спасибо! Нет, остался вопрос