Телефония

Облачный Pyrus
Безоблачный Pyrus

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

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

Методы

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": "Subject",
    "value": "Consultation"
  }]
}

Тело ответа

{
  "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Строка, необязательная. Внутренний номер оператора.
mappingsДанные для автоматического заполнения полей формы. Массив объектов вида:
  • code — строка. Символьный код поля формы Pyrus.
  • value — строка. Значение для поля в Pyrus. Максимальная длина 300 символов.
is_new_taskБулево поле. Имеет значение true, если была создана новая задача, и значение false, если добавлена запись в существующую задачу.
  • error_code — строка, необязательная. Код ошибки.
  • error — строка, необязательная. Сообщение об ошибке. Максимальная длина — 300 символов.
  • responsible_person — пользователь, указанный ответственным в задаче. Может быть пустым. Объект вида:
    • user_id — число, идентификатор пользователя;
    • first_name — строка, имя пользователя;
    • last_name — строка, фамилия пользователя;

Возвращает

НаименованиеОписание
task_idЧисло. ID созданной задачи.

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": "StartTime",
      "value": "2021-12-23T00:11:32Z"
    },
    {
      "code": "EndTime",
      "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Данные для автоматического заполнения полей формы. Массив объектов вида:
  • code — строка. Символьный код поля формы Pyrus.
  • value — строка. Значение для поля в Pyrus. Максимальная длина — 300 символов.

Возвращает

НаименованиеОписание
error_codeCтрока, необязательная. Код ошибки.
errorСтрока, необязательная. Сообщение об ошибке. Максимальная длина — 300 символов.

Ошибки

НаименованиеОписание
unrecognized_сall_idID обращения не зарегистрирован в Pyrus. Сообщение не обрабатывается.
webhook_is_disabledПользователь отключил уведомления о новых сообщениях. Сообщение не обрабатывается.
invalid_field_mapping_codeНедопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа.
unrecognized_attachment_idНеверный идентификатор прикладываемого файла.
unsupported_record_file_formatНеправильный формат файла записи звонка.
unrecognized_account_idID аккаунта расширения не зарегистрирован в Pyrus. Сообщение не обрабатывается.
webhook_is_disabledПользователь отключил уведомления о новых сообщениях. Сообщение не обрабатывается. invalid_field_mapping_code — недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа.

Подсказка: методы POST /calls, PUT calls/{call_guid} и POST calls/{call_guid}/event по-прежнему работают, но являются устаревшими.

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