Методы 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. Максимальная длина — 300 символов.
Возвращает:
task_ids — массив чисел. ID созданных задач.
error_code — строка, необязательная. Код ошибки.
error — строка, необязательная. Сообщение об ошибке.
Допустимые значения кодов ошибок:
unrecognized_account_id— ID аккаунта расширения не зарегистрирован в Pyrus. Сообщение не обрабатывается.webhook_is_disabled— пользователь отключил уведомления о новых сообщениях. Задача не создается.invalid_field_mapping_— недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом создается задача по форме, но данные, присланные в поле value, игнорируются. Недопустимые коды полей будут указаны в поле error ответа.code
Пример запроса через 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. Максимальная длина — 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_— недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом создается задача по форме, но данные, присланные в поле value, игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа.code
Пример запроса через 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
Функционал чатов
Методы доступны с включенной функцией Онлайн-чат.
POST /getmessage
Запрос-уведомление Pyrus о новом сообщении из внешней системы. Сообщение создается в виде комментария в задаче. Pyrus автоматически определяет, в какую задачу записывать комментарий, в зависимости от настроек пользователя. При этом Pyrus создает в задаче внешний канал для общения с отправителем из интерфейса Pyrus. Когда пользователь пишет комментарий во внешний канал, Pyrus вызывает метод sendmessage. Таким образом, запрос /getmessage и вебхук /sendmessage поддерживают возможность онлайн чата и позволяют создавать и обрабатывать заявки, на основе обращений в аккаунт, подключенный к расширению.
Например, внешний канал создается при обработке запроса /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 символов;
attachments — необязательный параметр. Массив строк, каждая из которых является guid загруженного на сервер Pyrus файла вложения. Максимум — 100 файлов вложений. Загрузить файл и получить его guid можно с помощью метода files/upload.
Возвращает массив объектов из следующих параметров:
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_— недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value, игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа;code too_many_attachments— в поле attachments содержится более 100 элементов. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но в комментарий прикладывается только 100 первых файлов из поля attachments. Список guid проигнорированных файлов будет указан в поле error_message ответа;unrecognized_attachment_— идентификатор прикладываемого файла неверен. Отсутствует файл с указанным идентификатором. Список неверных guid файлов будет указан в поле error_message ответа. При этом если сообщение не пустое, оно обрабатывается (создается задача по форме или комментарий к ней).id
Пример запроса через 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 будет искать уже созданную задачу.
Важно: поля PhoneNumberFrom (номер телефона клиента) и PhoneNumberTo (номер телефона оператора) необходимо заполнять одинаково, независимо от направления звонка.
При указании параметра 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_— недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа.code
Пример запроса через 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_.
Результат обработки запроса 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_— недопустимый код поля формы Pyrus, переданный в поле code объекта из массива mappings. Проверьте код на корректность. При этом сообщение обрабатывается (создается задача по форме или комментарий к ней), но данные, присланные в поле value игнорируются. Недопустимые коды полей будут указаны в поле error_message ответа.code 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— некорректный запрос.