Телефония
Методы предназначены для интеграции с телефонией в контакт-центрах: регистрации новой клиентской заявки при поступлении звонка, поднятия трубки оператором (Pyrus автоматически откроет у оператора окно с заявкой), завершения звонка с прикладыванием аудиозаписи.
О том, как подключить интеграцию, читайте в разделе Расширения.
Методы
- POST /integrations/callРегистрация звонка
- POST /integrations/attachcallrecordДобавление информации по звонку
POST integrations/call
Регистрация звонка
Запрос для регистрации в Pyrus звонка из системы API-телефонии. Звонок регистрируется в виде задачи по форме, к которой подключено расширение. Создавать новую задачу или добавить комментарий в старую Pyrus определяет автоматически.
При указании параметра internal_number Pyrus запустит поиск по пользователям, у которых заполнено поле Рабочий телефон в профиле Pyrus.
Если соответствие обнаружено, пользователь будет назначен ответственным в задаче, а информация об этом – записана в комментарии. После регистрации звонка у пользователя, ответственного за задачу, в браузере открывается новая вкладка с задачей.
POST https://api.pyrus.com/v4 /integrations /call
Тело запроса
{
"account_id": "uniqueID12345",
"from_number": "+79774221338",
"to_number": "+74953009080",
"internal_number": "200",
"mappings": [{
"code": "CallStartTime",
"value": "2021-12-23T00:11:32Z"
}]
}
Тело ответа
{
"task_id": 458732,
"is_new_task": false,
"responsible_person": {
"user_id": "34231",
"first_name": "Ilya",
"last_name": "Laserson",
"work_phone": "+79338762030"
}
}
Параметры
| Наименование | Описание |
| account_id | Строка. Уникальный идентификатор аккаунта расширения во внешней системе. |
| from_number | Строка. Номер телефона позвонившего. |
| to_number | Номер телефона, на который был совершен звонок. |
| internal_number | Строка, необязательная. Внутренний номер оператора. |
| external_id | Строка, необязательная. Идентификатор звонка во внешней системе. |
mappings | Данные для автоматического заполнения полей формы. Массив объектов вида:
Для заполнения доступны следующие поля: (можно использовать с кодами):
|
Возвращает
| Наименование | Описание |
| task_id | Число. ID созданной задачи. |
| is_new_task | Булево поле. Имеет значение true, если была создана новая задача, и значение false, если добавлена запись в существующую задачу. |
| error_code | Строка, необязательная. Код ошибки. |
| error | Строка, необязательная. Сообщение об ошибке. Максимальная длина — 300 символов. |
| responsible_person | Пользователь, указанный ответственным в задаче. Может быть пустым. Объект вида:
|
POST integrations/attachcallrecord
Добавление информации по звонку
Запрос для добавления в задачу Pyrus информации о звонке. Для успешной обработки запроса должен быть указан один из следующих параметров external_id, task_id или оба параметра from_number и to_number. В противном случае Pyrus не сможет идентифицировать обращение и вернет код ошибки required_parameters_not_specified.
POST https://api.pyrus.com/v4 /integrations /attachcallrecord
Тело запроса
{
"account_id": "uniqueID12345",
"task_id": 45873,
"record_file": "08923d83-255b-4f18-b0eb-5c4d3b9bf1d2",
"mappings": [
{
"code": "CallStartTime",
"value": "2021-12-23T00:11:32Z"
},
{
"code": "CallEndTime",
"value": "2021-12-23T00:24:02Z"
},
{
"code": "Rating",
"value": 5
}
]
}
Параметры
| Наименование | Описание |
| account_id | Строка. Уникальный идентификатор аккаунта расширения во внешней системе. |
| record_file | Строка. Уникальный идентификатор файла, который был загружен с помощью запроса /files/upload. Загруженный файл прикрепляется с указанием, что это канал телефонного звонка. Файл должен иметь расширение одного из аудиоформатов ac3, mp3, ogg, wav, wma), в противном случае файл не будет прикреплён и будет возвращена ошибка. |
| from_number | Строка, необязательная. Номер телефона позвонившего. |
| to_number | Строка, необязательная. Номер телефона, на который был совершен звонок. |
| external_id | Строка, необязательная. Идентификатор звонка во внешней системе. |
| task_id | Число, необязательное. ID созданной задачи. Возвращается в integrations/call. |
| mappings | Данные для автоматического заполнения полей формы. Массив объектов вида:
|
Возвращает
| Наименование | Описание |
| error_code | Строка, необязательная. Код ошибки. |
| error | Строка, необязательная. Сообщение об ошибке. Максимальная длина — 300 символов. |
Ошибки
| Наименование | Описание |
| unrecognized_call_id | ID обращения не зарегистрирован в Pyrus. Сообщение не обрабатывается. |
| invalid_field_mapping_code | Недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа. |
| unrecognized_attachment_id | Неверный идентификатор прикладываемого файла. |
| unsupported_record_file_format | Неправильный формат файла записи звонка. |
| unrecognized_account_id | ID аккаунта расширения не зарегистрирован в Pyrus. Сообщение не обрабатывается. |
| webhook_is_disabled | Пользователь отключил уведомления о новых сообщениях. Сообщение не обрабатывается. |