Методы Pyrus 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 — некорректный запрос.

POST auth

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

Параметры:

login — строка, логин для вашего расширения. Посмотреть его можно в параметрах расширения; security_key — строка. Секретный ключ для вашего расширения. Можно посмотреть в параметрах расширения.

Возвращает:

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

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

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

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

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

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

curl -X POST \
https://api.pyrus.com/v4/auth \
-H 'Content-Type: application/json' \
-d '{
"login": "unique12345@login.edu",
"security_key": "czWhgtoLnm****"
}'

Тело ответа:

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

POST integrations/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://api.pyrus.com/v4/integrations/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 integrations/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://api.pyrus.com/v4/integrations/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 integrations/attachcallrecord

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

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

Параметры: 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_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://api.pyrus.com/v4/integrations/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 integrations/createtask

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

Параметры:

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

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

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

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

Возвращает:

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://api.pyrus.com/v4/integrations/createtask \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"account_id": "uniqueID12345",
"mappings": [
{
"code":"PostLink", "value": "https://specialsite.com/post123"
}
]
}'

Тело ответа:

{
  "task_id": 587625
}

POST integrations/addcomment

Создает комментарий к задаче. Задача должна быть создана по форме, к которой подключено расширение, в противном случае 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 запроса integrations/getmessage или поля record_file запроса integrations/attachcallrecord. Файлы, не приложенные ни к одному сообщению, через некоторое время удаляются. В большинстве языков программирования или программных средств для отправки REST API запросов, например curl или Postman, корректный запрос сформируется автоматически, если при передаче данных указать тип кодирования multipart/form-data. Таким образом для успешной загрузки файла в теле запроса достаточно указать путь к файлу. Загружайте ровно один файл, используя указанный запрос. Если необходимо загрузить несколько файлов, запустите запрос несколько раз соответственно. Максимальный размер прикладываемого файла — 250 Mb.

Возвращает:

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

md5_hash — строка. Хеш файла, вычисленный по алгоритму MD5;

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

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

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

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

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

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

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

curl -X POST \
https://api.pyrus.com/v4/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://api.pyrus.com/v4/files/download/1334 \
-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

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

Общие коды ошибок

POST auth

POST integrations/getmessage

POST integrations/call

POST integrations/attachcallrecord

POST integrations/createtask

POST integrations/addcomment

POST files/upload

GET files/download/{file-id}

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