Методы Extensions API для расширений
Общие коды ошибок
Ошибки, которые могут вернуться при выполнении любого запроса к Pyrus 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 — некорректный запрос.
GET token
Запрос для получения доступа к Pyrus 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 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 символов.
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"
]
}'
Тело ответа:
[
{
"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, если добавлена запись в существующую задачу.
error_code — строка, необязательная. Код ошибки.
error — строка, необязательная. Сообщение об ошибке. Максимальная длина — 300 символов.
responsible_person — пользователь, указанный ответственным в задаче. Может быть пустым. Объект вида:
user_id — число, идентификатор пользователя;
first_name — строка, имя пользователя;
last_name — строка, фамилия пользователя;
Допустимые значения кодов ошибок:
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"
}
]
}'
Тело ответа:
[
{
"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:
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 task
Создает задачу по форме, к которой привязано расширение.
Параметры:
account_id — строка. Уникальный идентификатор аккаунта расширения во внешней системе.
text — строка, необязательная. Текст первого комментария.
mappings — данные для автоматического заполнения полей формы. Массив объектов вида:
code — строка. Символьный код поля формы Pyrus.
value — строка. Значение для поля в Pyrus. Максимальная длина — 300 символов.
Возвращает массив task_ids — ID созданных задач:
task_id — число, 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"
}
]
}'
Тело ответа:
"Tasks": [
{
"task_id": 458732,
"is_new_task": false,
"responsible_person": {
"user_id": 34231,
"first_name": "Ilya",
"last_name": "Laserson",
"work_phone": "+79338762030"
}
}
]
POST comment
Создает комментарий к задаче. Задача должна быть создана по форме, к которой подключено расширение, в противном случае Pyrus вернет ошибку и запрос будет проигнорирован.
Параметры:
account_id — строка. Уникальный идентификатор аккаунта расширения во внешней системе.
task_id — число. Id задачи в которую нужно дописать комментарий.
mappings — данные для автоматического заполнения полей формы. Массив объектов вида:
code — строка. Символьный код поля формы Pyrus.
value — строка. Значение для поля в Pyrus. Максимальная длина — 300 символов.
send_to_external_channel — булевская переменная. Отправка комментария во внешние каналы в задаче. По умолчанию имеет значение false.
comment_text — строка. Текст комментария.
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://api.pyrus.com/v4/integrations/addcomment \
-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. В ответе возвращается guid файла, который можно передавать в нужных полях в некоторых запросах, например, в поле attachments запроса getmessage или поля record_file запроса attachcallrecord. Файлы, не приложенные ни к одному сообщению, через некоторое время удаляются. В большинстве языков программирования или программных средств для отправки REST API запросов, например curl или Postman, корректный запрос сформируется автоматически, если при передаче данных указать тип кодирования multipart/form-data. Таким образом для успешной загрузки файла в теле запроса достаточно указать путь к файлу. Загружайте ровно один файл, используя указанный запрос. Если необходимо загрузить несколько файлов, запустите запрос несколько раз соответственно. Максимальный размер прикладываемого файла — 250 Mb.
Возвращает:
guid — строка. guid загруженного файла. Используется для прикладывания файла к сообщению в getmessage;
error_code — строка, необязательная. Код ошибки.
error — строка, необязательная. Сообщение об ошибке.
Допустимые значения кодов ошибок:
empty_file — нельзя загрузить пустой файл;
no_file_in_request — запрос не содержит файлов;
too_large_file — превышен максимальный размер файла.
Пример запроса через curl:
curl -X POST \ https://extensions.pyrus.com/v1/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/download/1 \ -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