Методы Extensions API

Методы Extensions API доступны по адресу https://extensions.pyrus.com/v1/. Для авторизации запросов необходимо получить токен доступа, выполнив запрос POST /token. Полученный токен необходимо указывать в HTTP-заголовке Authorization при каждом запросе к API:

Authorization: Bearer gAAAAA15vmSeoj*******

Срок действия токена ограничен, поэтому ваше приложение должно уметь повторно проходить процедуру авторизации в случае отзыва токена. Токен авторизации может быть отозван в следующих случаях:

• срок жизни токена истек;
• секретный ключ вашего расширения был отозван администратором или службой безопасности Pyrus. В таком случае все выданные токены будут отозваны.

Параметры POST-запросов передаются в теле запроса в формате JSON. Параметры GET-запросов передаются в URL и при наличии специальных символов должны быть экранированы с помощью urlencode. Все ответы передаются в теле ответа в формате JSON. При передаче чисел в качестве разделителя целой и дробной части используется точка. Даты передаются в формате ISO 8601. Ответ от сервера всегда приходит с нулевой временной зоной. Пустые поля в ответе не возвращаются. В случае возникновения ошибки в теле ответа будут указаны поля:

• error — сообщение об ошибке;
• error_code — строковый код ошибки.

При ошибочном вызове возвращается наиболее подходящий HTTP Status Code.

Общие методы

Общие методы доступны для всех типов расширений, независимо от используемого функционала.

POST /token

Запрос для получения доступа к Extensions API. Возвращает access_token, который надо указывать в заголовке Authorization для каждого последующего запроса.

Параметры:

• client_id — строка, логин для вашего расширения. Посмотреть его можно в общих настройках расширения;

• secret — строка. Секретный ключ для вашего расширения. Можно посмотреть в общих настройках расширения.

Возвращает:

• access_token — строка, токен доступа, для указания в заголовке Authorization для каждого последующего запроса;

• error_code — строка, необязательная. Код ошибки.

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

Допустимые значения кодов ошибок:

• authorization_error — ошибка авторизации. Проверьте правильность передаваемых параметров и повторите запрос.

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

curl -X POST \
  https://extensions.pyrus.com/v1/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "unique12345@login.edu",
    "secret": "czWhgtoLnm****"
  }'

Тело ответа:

{
  "access_token": "089gAAAAiopm92dlfhjij2**kdmd***"
}

POST /task

Создает задачу по форме, к которой привязано расширение.

Параметры:

• account_id — строка. Уникальный идентификатор аккаунта расширения во внешней системе.

• text — строка, необязательная. Текст первого комментария.

• text_html — строка, необязательная. Текст первого комментария, содержащий форматирование html. Допустимые html-теги:

  • <i>text</i> — наклонный;
  • <br> — перенос на новую строку;
  • <code>text</code> код;
  • <b>text</b> — полужирный;
  • <s>text</s> — зачеркнутый;
  • <div data-type=\"heading\">text</div> — заголовок;
  • <q>text</q> — цитата;
  • <mark data-color=\"red\">text</mark> — красный цвет;
  • <mark data-color=\"yellow\">text</mark> — желтый цвет;
  • <mark data-color=\"green\">text</mark> — зеленый цвет;
  • <mark data-color=\"blue\">text</mark> — синий цвет;
  • <ul><li>text1</li><li>text2</li></ul> — маркированный список;
  • <ol><li>text1</li><li>text2</li></ol> — нумерованный список;
  • <a href="url">text</a> — гиперссылка;
  • <button>text</button> — кнопка.

• mappings — данные для автоматического заполнения полей формы. Массив объектов вида:

  • code — строка. Символьный код поля формы Pyrus.

  • value — строка. Значение для поля в Pyrus. Формат зависит от типа поля, к которому привязан код, — см. Значения полей в mappings. Длина текстовых значений ограничивается настройками поля.

Возвращает:

• task_ids — массив чисел. ID созданных задач.

• error_code — строка, необязательная. Код ошибки.

• error — строка, необязательная. Сообщение об ошибке.

Допустимые значения кодов ошибок:

• unrecognized_account_id — ID аккаунта расширения не зарегистрирован в Pyrus. Сообщение не обрабатывается.

• webhook_is_disabled — пользователь отключил уведомления о новых сообщениях. Задача не создается.

• invalid_field_mapping_code — недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом создается задача по форме, но данные, присланные в поле value, игнорируются. Недопустимые коды полей будут указаны в поле error ответа.

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

curl -X POST \
  https://extensions.pyrus.com/v1/task \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "uniqueID12345",
    "mappings": [
      {"code":"PostLink", "value":"https://specialsite.com/post123"}
    ]
  }'

Тело ответа:

{
  "task_ids": [
    458732
  ]
}

POST /comment

Создает комментарий к задаче. Задача должна быть создана по форме, к которой подключено расширение, в противном случае Pyrus вернет ошибку и запрос будет проигнорирован.

Параметры:

• account_id — обязательная строка. Уникальный идентификатор аккаунта расширения во внешней системе.

• task_id — обязательное число. Id задачи в которую нужно дописать комментарий.

Также обязательным является наличие одного из следующих параметров: mappings, comment_text, comment_text_html, attachments.

• mappings — необязательный параметр. Данные для автоматического заполнения полей формы. Массив объектов вида:

  • code — строка. Символьный код поля формы Pyrus.

  • value — строка. Значение для поля в Pyrus. Формат зависит от типа поля, к которому привязан код, — см. Значения полей в mappings. Длина текстовых значений ограничивается настройками поля.

• send_to_external_channel — булево поле, необязательное. Если true, комментарий отправляется во внешние каналы задачи. По умолчанию false.

• comment_text — строка, необязательная. Текст комментария.

• comment_text_html — строка, необязательная. Текст комментария, содержащий форматирование html. Допустимые html-теги:

  • <i>text</i> — наклонный;
  • <br> — перенос на новую строку;
  • <code>text</code> код;
  • <b>text</b> — полужирный;
  • <s>text</s> — зачеркнутый;
  • <div data-type=\"heading\">text</div> — заголовок;
  • <q>text</q> — цитата;
  • <mark data-color=\"red\">text</mark> — красный цвет;
  • <mark data-color=\"yellow\">text</mark> — желтый цвет;
  • <mark data-color=\"green\">text</mark> — зеленый цвет;
  • <mark data-color=\"blue\">text</mark> — синий цвет;
  • <ul><li>text1</li><li>text2</li></ul> — маркированный список;
  • <ol><li>text1</li><li>text2</li></ol> — нумерованный список;
  • <a href="url">text</a> — гиперссылка;
  • <button>text</button> — кнопка.

• attachments — необязательный параметр. Массив строк, каждая из которых является guid загруженного на сервер Pyrus файла вложения. Максимум — 100 файлов вложений. Загрузить файл и получить его guid можно с помощью метода files/upload.

• skip_auto_reopen — булево поле, необязательное. Если true, закрытая задача не переоткрывается при добавлении комментария. По умолчанию false.

Возвращает:

• error_code — строка, необязательная. Код ошибки.

• error — строка, необязательная. Сообщение об ошибке.

Допустимые значения кодов ошибок:

• unrecognized_account_id — ID аккаунта расширения не зарегистрирован в Pyrus. Сообщение не обрабатывается.

• webhook_is_disabled — пользователь отключил уведомления о новых сообщениях. Задача не создается.

• unrecognized_task_id — ID задачи не зарегистрирован или у расширения нет доступа к этой задаче.

• invalid_field_mapping_code — недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом создается задача по форме, но данные, присланные в поле value, игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа.

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

curl -X POST \
  https://extensions.pyrus.com/v1/comment \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "uniqueID12345",
    "task_id": 15862,
    "comment_text": "New event in external system!",
    "mappings": [
      {"code":"PostLink", "value":"https://specialsite.com/post123"}
    ]
  }'

POST /files/upload

Используется для загрузки файла в Pyrus.

В большинстве языков программирования или программных средств для отправки REST API запросов, например curl или Postman, корректный запрос сформируется автоматически, если при передаче данных указать тип кодирования multipart/form-data. Таким образом для успешной загрузки файла в теле запроса достаточно указать путь к файлу.

В ответе возвращается guid файла, который можно передавать в нужных полях в некоторых запросах, например, в поле attachments запроса getmessage или поля record_file запроса attachcallrecord. Файлы, не приложенные ни к одному сообщению, через некоторое время удаляются. Загружайте ровно один файл, используя указанный запрос.

Если необходимо загрузить несколько файлов, запустите запрос несколько раз соответственно. Максимальный размер прикладываемого файла — 2 ГБ.

Возвращает:

• guid — строка. Временный одноразовый идентификатор загруженного файла. Используется один раз для прикладывания файла к сообщению в методах getmessage и attachcallrecord;

• error_code — строка, необязательная. Код ошибки.

• error — строка, необязательная. Сообщение об ошибке.

Допустимые значения кодов ошибок:

• empty_file — нельзя загрузить пустой файл;

• no_file_in_request — запрос не содержит файлов;

• too_large_file — превышен максимальный размер файла.

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

curl -X POST \
  https://extensions.pyrus.com/v1/files/upload \
  -H 'Authorization: Bearer <your_access_token>' \
  -F 'file.jpg=@C:\Path\To\File\filename.jpg'

Тело ответа:

{
  "guid": "08923d83-255b-4f18-b0eb-5c4d3b9bf1d2",
  "md5_hash": "cd4df826e3b9ce6e7895d8a31536d99d"
}

GET /files/download/{file-id}

Запрос для скачивания файла из Pyrus.

Параметры:

• file-id — число. ID файла вложения, переданный в параметре attachment_ids запроса sendmessage.

Возвращает:

• error_code — строка, необязательная. Код ошибки.

• error — строка, необязательная. Сообщение об ошибке.

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

curl -X GET \
  https://extensions.pyrus.com/v1/files/download/123 \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json'

Заголовки ответа:

Content-Disposition: attachment; filename=test.txt
Content-Length: 12
Content-Type: application/octet-stream

Значения полей при сопоставлении

Поле value всегда передаётся строкой, но её содержимое зависит от типа поля Pyrus, к которому привязан код (code).

Общие правила:

• Если значение не подходит под формат поля, поле остаётся незаполненным. Запрос при этом выполняется успешно, ошибка не возвращается.
• Ограничение длины берётся из настроек конкретного поля формы; если оно не задано, длина не ограничивается. Для типов Число, Дата и Время ограничение длины неприменимо.
• Если внутри значения есть кавычки, они экранируются по обычным правилам JSON.
• Время передаётся в UTC и при отображении пересчитывается в часовой пояс пользователя.

Справочник. В value передаётся JSON-документ с условиями поиска: в какой колонке какое значение должно совпасть. Совпадение ищется по точному значению с учётом регистра. Несколько условий внутри одной строки объединяются по «И». Если поле допускает только один элемент, используется первая строка. В поле попадает найденный элемент справочника, а не переданный текст; если ничего не найдено, поле остаётся пустым.

{"code": "Client", "value": "{\"rows\":[{\"items\":[{\"column\":\"ИНН\",\"value\":\"7701234567\"}]}]}"}

Читается как «найти элемент, у которого в колонке ИНН значение 7701234567».

Таблица. Табличное поле заполняется через rows, а не через value. rows — массив строк таблицы; каждая строка — массив маппингов её колонок:

{
  "code": "Товары",
  "rows": [
    [ {"code": "Товар", "value": "Ручка"},  {"code": "Количество", "value": "10"} ],
    [ {"code": "Товар", "value": "Бумага"}, {"code": "Количество", "value": "20"} ]
  ]
}

• строки сопоставляются по порядку с уже существующими строками таблицы;
• если строк передано больше, чем есть в таблице, недостающие добавляются; если меньше — лишние удаляются;
• пустой массив на месте строки оставляет её без изменений;
• "rows": [] очищает таблицу целиком;
• вложенные таблицы не поддерживаются.

Пример запроса со всеми типами полей:

{
  "account_id": "uniqueID12345",
  "mappings": [
    {"code": "Comment",   "value": "Иван Синицин"},
    {"code": "Amount",    "value": "1500.50"},
    {"code": "Count",     "value": "42"},
    {"code": "EventDate", "value": "2026-07-22"},
    {"code": "StartTime", "value": "14:30:00Z"},
    {"code": "Email",     "value": "user@example.com"},
    {"code": "Phone",     "value": "+79991234567"},
    {"code": "Status",    "value": "В работе"},
    {"code": "Manager",   "value": "34231"},
    {"code": "Files",     "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6"},
    {"code": "Client",    "value": "{\"rows\":[{\"items\":[{\"column\":\"ИНН\",\"value\":\"7701234567\"}]}]}"},
    {"code": "Товары",    "rows": [
      [ {"code": "Товар", "value": "Ручка"}, {"code": "Количество", "value": "10"} ]
    ]}
  ]
}

Функционал чатов

Методы доступны с включенной функцией Онлайн-чат.

POST /getmessage

Запрос-уведомление Pyrus о новом сообщении из внешней системы. Сообщение создается в виде комментария в задаче. Pyrus автоматически определяет, в какую задачу записывать комментарий, в зависимости от настроек пользователя. При этом Pyrus создает в задаче внешний канал для общения с отправителем из интерфейса Pyrus. Когда пользователь пишет комментарий во внешний канал, Pyrus вызывает метод sendmessage. Таким образом, запрос /getmessage и вебхук /sendmessage поддерживают возможность онлайн чата и позволяют создавать и обрабатывать заявки, на основе обращений в аккаунт, подключенный к расширению.

Например, внешний канал создается при обработке запроса /getmessage из расширения Telegram:

Параметры:

• account_id — строка. Уникальный идентификатор аккаунта интеграции во внешней системе (ID группы в ВКонтакте, имя бота в Telegram и т. д.);

• channel_id — строка. Уникальный идентификатор канала для сообщений в интеграции (ID чата в Telegram, ID пользователя ВКонтакте и т. д.). Максимальная длина — 200 символов;

• sender_name — строка. Имя отправителя сообщения. Максимальная длина — 100 символов;

• message_type — поле "Код типа сообщения", который появляется при включенной функции онлайн-чатов. Онлайн-чаты можно подключить в ЛК в блоке настроек дополнительных функций.

• message_text — строка. Текст сообщения. Максимальная длина — 10 000 символов.

• message_text_html — строка, необязательная. Текст сообщения, содержащий форматирование html. Допустимые html-теги:

  • <i>text</i> — наклонный;
  • <br> — перенос на новую строку;
  • <code>text</code> код;
  • <b>text</b> — полужирный;
  • <s>text</s> — зачеркнутый;
  • <div data-type=\"heading\">text</div> — заголовок;
  • <q>text</q> — цитата;
  • <mark data-color=\"red\">text</mark> — красный цвет;
  • <mark data-color=\"yellow\">text</mark> — желтый цвет;
  • <mark data-color=\"green\">text</mark> — зеленый цвет;
  • <mark data-color=\"blue\">text</mark> — синий цвет;
  • <ul><li>text1</li><li>text2</li></ul> — маркированный список;
  • <ol><li>text1</li><li>text2</li></ol> — нумерованный список;
  • <a href="url">text</a> — гиперссылка;
  • <button>text</button> — кнопка.

• mappings — данные для автоматического заполнения полей формы. Массив объектов вида:

  • code — строка. Символьный код поля формы Pyrus;

  • value — строка. Значение для поля в Pyrus. Формат зависит от типа поля, к которому привязан код, — см. Значения полей в mappings. Длина текстовых значений ограничивается настройками поля;

• attachments — необязательный параметр. Массив строк, каждая из которых является guid загруженного на сервер Pyrus файла вложения. Максимум — 100 файлов вложений. Загрузить файл и получить его guid можно с помощью метода files/upload.

• on_closed — строка, необязательная. Что делать с сообщением, если задача канала закрыта и по настройкам интеграции в аккаунте считается неактивной. Допустимые значения (регистр значим):

  • create — создать новую задачу. Значение по умолчанию;

  • reopen — добавить сообщение комментарием в найденную закрытую задачу, переоткрыв её. Настройка периода неактивности при этом не учитывается: задача переоткрывается независимо от того, как давно она была закрыта;

  • error — не обрабатывать сообщение и вернуть ошибку no_open_task. Расширение может само решить, создавать ли новую задачу, например, через метод /task.

  Параметр срабатывает только тогда, когда задача по каналу найдена, но отброшена как неактивная. Если задачи по каналу ещё нет, новая задача создаётся при любом значении параметра. Если задача открыта либо закрыта, но укладывается в период неактивности, сообщение добавляется в неё комментарием. Неизвестное значение параметра возвращает ошибку validation_error с перечнем допустимых значений.

Возвращает массив объектов из следующих параметров:

• task_id — число, ID задачи;

• is_new_task — булево поле. Имеет значение true, если была создана новая задача, и значение false, если добавлена запись в существующую задачу;

• responsible_person — пользователь, указанный ответственным в задаче. Объект вида:

  • user_id — число, идентификатор пользователя;

  • first_name — строка, имя пользователя;

  • last_name — строка, фамилия пользователя;

  • work_phone — строка, рабочий телефон пользователя.

• error_code — строка, необязательная. Код ошибки.

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

Допустимые значения кодов ошибок:

• unrecognized_account_id — ID аккаунта расширения не зарегистрирован в Pyrus. Сообщение не обрабатывается;

• webhook_is_disabled — пользователь отключил уведомления о новых сообщениях. Сообщение не обрабатывается;

• too_large_message_text — слишком большой текст сообщения в поле message_text. Сообщение не обрабатывается;

• unrecognized_message_type — неизвестный тип сообщения. Сообщение обрабатывается, в качестве типа сообщения используется первый объект из поля "Код типа сообщения" при включенной функции онлайн-чатов. Неизвестный код типа сообщения будет указан в поле error_message ответа.

• invalid_field_mapping_code — недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value, игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа;

• too_many_attachments — в поле attachments содержится более 100 элементов. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но в комментарий прикладывается только 100 первых файлов из поля attachments. Список guid проигнорированных файлов будет указан в поле error_message ответа;

• unrecognized_attachment_id — идентификатор прикладываемого файла неверен. Отсутствует файл с указанным идентификатором. Список неверных guid файлов будет указан в поле error_message ответа. При этом если сообщение не пустое, оно обрабатывается (создается задача по форме или комментарий к ней);

• no_open_task — в канале нет активной задачи, а в запросе передано on_closed со значением error. Сообщение не обрабатывается.

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

curl -X POST \
  https://extensions.pyrus.com/v1/getmessage \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "uniqueID12345",
    "channel_id": 87654321,
    "sender_name": "Иван Синицин",
    "message_type": "Telegram",
    "message_text": "Здравствуйте! Подскажите, можно ли будет перенести доставку заказа на четверг?",
    "mappings": [
      {"code":"SenderName", "value":"Иван Синицин"},
      {"code":"Subject", "value":"Здравствуйте! Подскажите, можно ли будет перенести доставку заказа на четверг?"}
    ],
    "attachments":[
      "50b15ea9-41aa-4820-8350-8c6a3a16ed84",
      "00464c7d-9bd1-42ac-901b-3beb8e9ecee5"
    ]
  }'

Тело ответа:

{
  "tasks": [
    {
      "task_id": 458732,
      "is_new_task": false,
      "responsible_person": {
        "user_id": 34231,
        "first_name": "Ilya",
        "last_name": "Laserson",
        "work_phone": "+79338762030"
      }
    }
  ]
}

Функционал телефонии

Методы доступны с включенной функцией Телефония.

POST /call

Запрос для регистрации в Pyrus звонка из системы API-телефонии. Звонок регистрируется в виде задачи по форме, к которой подключено расширение. Создавать новую задачу или добавить комментарий в старую Pyrus определяет автоматически. Для корректного поиска существующей задачи необходимо добавить в настройках и передавать в запросе поля формы с кодами PhoneNumberFrom (номер телефона клиента) и PhoneNumberTo (номер телефона оператора). По значению поля PhoneNumberFrom Pyrus будет искать уже созданную задачу.

При указании параметра internal_number Pyrus запустит поиск по пользователям, у которых заполнено поле Рабочий телефон в профиле Pyrus. Если соответствие обнаружено, пользователь будет назначен ответственным в задаче, информация об этом будет записана в комментарии. После регистрации звонка у пользователя, ответственного за задачу, в браузере открывается новая вкладка с задачей.

Параметры:

• account_id — строка. Уникальный идентификатор аккаунта расширения во внешней системе.

• from_number — строка. Номер телефона позвонившего.

• to_number — строка. Номер телефона, на который был совершен звонок.

• internal_number — строка, необязательная. Внутренний номер оператора.

• external_id — строка, необязательная. Идентификатор канала общения во внешней системе. Максимальная длина — 200 символов;

• mappings — данные для автоматического заполнения полей формы. Массив объектов вида:

  • code — строка. Символьный код поля формы Pyrus.

  • value — строка. Значение для поля в Pyrus. Формат зависит от типа поля, к которому привязан код, — см. Значения полей в mappings. Длина текстовых значений ограничивается настройками поля.

Возвращает массив объектов из указанных параметров:

• task_id — число. ID созданной задачи.

• is_new_task — булево поле. Имеет значение true, если была создана новая задача, и значение false, если добавлена запись в существующую задачу.

• responsible_person — пользователь, указанный ответственным в задаче. Может быть пустым. Объект вида:

  • user_id — число, идентификатор пользователя;

  • first_name — строка, имя пользователя;

  • last_name — строка, фамилия пользователя;

  • work_phone — строка, рабочий телефон пользователя.

• error_code — строка, необязательная. Код ошибки.

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

Допустимые значения кодов ошибок:

• unrecognized_account_id — ID аккаунта расширения не зарегистрирован в Pyrus. Сообщение не обрабатывается.

• webhook_is_disabled — пользователь отключил уведомления о новых сообщениях. Сообщение не обрабатывается.

• invalid_field_mapping_code — недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа.

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

curl -X POST \
  https://extensions.pyrus.com/v1/call \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "uniqueID12345",
    "from_number": "+79774221338",
    "to_number": "+74953009080",
    "internal_number": "200",
    "mappings": [
      {"code":"Subject", "value":"Consultation"},
      {"code":"PhoneNumberFrom", "value":"+79774221338"},
      {"code":"PhoneNumberTo", "value":"+74953009080"}
    ]
  }'

Тело ответа:

{
  "tasks": [
    {
      "task_id": 458732,
      "is_new_task": false,
      "responsible_person": {
        "user_id": 34231,
        "first_name": "Ilya",
        "last_name": "Laserson",
        "work_phone": "+79338762030"
      }
    }
  ]
}

POST /attachcallrecord

Запрос для добавления в задачу Pyrus информации о звонке. Для успешной обработки запроса должен быть указан один из следующих параметров external_id, task_id или оба параметра from_number и to_number. В противном случае Pyrus не сможет идентифицировать обращение и вернет код ошибки required_parameters_not_specified.

Результат обработки запроса attachcallrecord:

Параметры:

• account_id — строка. Уникальный идентификатор аккаунта расширения во внешней системе.

• record_file — строка. Уникальный идентификатор файла, который был загружен с помощью запроса /files/upload. Загруженный файл прикрепляется с указанием, что это канал телефонного звонка. Файл должен иметь расширение одного из аудиоформатов ac3, mp3, ogg, wav, wma), в противном случае файл не будет прикреплён и будет возвращена ошибка.

• from_number — строка, необязательная. Номер телефона позвонившего.

• to_number — строка, необязательная. Номер телефона, на который был совершен звонок.

• external_id — строка, необязательная. Идентификатор звонка во внешней системе.

• task_id — число, необязательное. ID созданной задачи. Возвращается в call.

• mappings — данные для автоматического заполнения полей формы. Массив объектов вида:

  • code — строка. Символьный код поля формы Pyrus.
  • value — строка. Значение для поля в Pyrus. Формат зависит от типа поля, к которому привязан код, — см. Значения полей в mappings. Длина текстовых значений ограничивается настройками поля.

Возвращает:

• error_code — строка, необязательная. Код ошибки.

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

Допустимые значения кодов ошибок:

• unrecognized_call_id — ID обращения не зарегистрирован в Pyrus. Сообщение не обрабатывается.

• webhook_is_disabled — пользователь отключил уведомления о новых сообщениях. Сообщение не обрабатывается.

• invalid_field_mapping_code — недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа.

• unrecognized_attachment_id — неверный идентификатор прикладываемого файла.

• unsupported_record_file_format — неправильный формат файла записи звонка.

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

curl -X POST \
  https://extensions.pyrus.com/v1/attachcallrecord \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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}
    ]
  }'

Ограничения количества запросов

К методам Extensions API можно обращаться не чаще 5000 раз в 10 минут. В HTTP-заголовках ответа содержится дополнительная информация по ограничениям:

• X-RateLimit-Limit — максимальное количество запросов, разрешенное в данном временном интервале;
• X-RateLimit-Remaining — количество запросов до превышения ограничения в данном временном интервале;
• X-RateLimit-Reset — количество секунд до начала следующего временного интервала.

Коды ошибок

Ошибки, которые могут вернуться при выполнении любого запроса к Extensions API в поле error_code:

• server_error — внутренняя ошибка сервера, при возникновении которой следует обратиться в службу поддержки Pyrus;

• token_not_specified — не указан токен авторизации. Необходимо указать токен в HTTP-заголовке Authorization;

• revoked_token — токен авторизации был отозван. Необходимо получить новый токен;

• invalid_token — неверный токен авторизации. Необходимо проверить корректность токена или получить новый;

• invalid_request — переданные в запросе данные не являются корректным запросом;

• empty_body — тело запроса не может быть пустым;

• too_many_requests — превышено максимальное количество запросов за период. Подождите несколько минут и повторите запрос;

• required_parameters_not_specified — не указаны обязательные параметры запроса;

• validation_error — некорректный запрос.