Справка

Методы Extensions API для расширений

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. Максимальная длина — 300 символов.

Возвращает:

  • 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 — данные для автоматического заполнения полей формы. Массив объектов вида:

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

    • value — строка. Значение для поля в Pyrus. Максимальная длина — 300 символов.

  • send_to_external_channel — булевская переменная. Отправка комментария во внешние каналы в задаче. По умолчанию имеет значение 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.

Возвращает:

  • 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 /getmessage

Доступно с функцией Онлайн чат

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

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

Параметры:

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

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

  • 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. Максимальная длина — 300 символов.

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

  • 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 ответа. При этом если сообщение не пустое, оно обрабатывается (создается задача по форме или комментарий к ней).

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

Параметры:

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

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

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

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

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

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

    • value — строка. Значение для поля в Pyrus. Максимальная длина 300 символов.

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

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

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

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

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

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

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

  • 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"}
    ]
  }'

Тело ответа:

{
  "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. Максимальная длина — 300 символов.

Возвращает:

  • 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}
    ]
  }'

POST /files/upload

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

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

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

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

Возвращает:

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

  • 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 'filename.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

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