API methods for extensions

POST /token

Request to access Extensions API. Returns an access_token, which must be specified in the Authorization header for each subsequent request.

Parameters:

client_id — string, login for your extension. You can view it in the extension's general settings;
secret — string. Secret key for your extension. Can be viewed in the extension's general settings.

Returns:

access_token — string, access token, to be specified in the Authorization header for each subsequent request;
error_code — string, optional. Error code.
error — string, optional. Error message. Max length 300 characters.

Allowed error code values:

authorization_error — authorization error. Check that the transmitted parameters are correct and repeat the request.

Example request via curl:

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

Response body:

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

POST /task

Parameters:

account_id — string. Unique identifier of the extension account in an external system.
text — string, optional. Text of the first comment.
text_html — string, optional. Text of the first comment containing HTML formatting. Allowed HTML tags:
- <i>text</i> — italic;
- <br> — line break;
- <code>text</code> — code;
- <b>text</b> — bold;
- <s>text</s> — strikethrough;
- <div data-type=\"heading\">text</div> — heading;
- <q>text</q> - quote;
- <mark data-color=\"red\">text</mark> — red color;
- <mark data-color=\"yellow\">text</mark> — yellow color;
- <mark data-color=\"green\">text</mark> — green color;
- <mark data-color=\"blue\">text</mark> — blue color;
- <ul><li>text1</li><li>text2</li></ul> — bulleted list;
- <ol><li>text1</li><li>text2</li></ol> — numbered list;
- <a href="url">text</a> — hyperlink;
- <button>text</button> — button.
mappings — data for auto filling of form fields. Array of objects in the format:
- code — string. Field code of the Pyrus form.
- value — string. Value for the field in Pyrus. Max length 300 characters.

Returns:

task_ids — array of numbers. IDs of the created tasks.
error_code — string, optional. Error code.
error — string, optional. Error message.

Allowed error code values:

unrecognized_account_id — extension account ID is not registered in Pyrus. Message not processed.
webhook_is_disabled — user has disabled notifications for new messages. Task is not created.
invalid_field_mapping_code — invalid Pyrus form field code passed in the code field of the mappings array object. Check that the code is correct. At the same time, a task is created from the form, but the data sent in the value field is ignored. Invalid field codes will be indicated in the error field of the response.

Example request via 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"}
    ]
  }'

Response body:

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

POST /comment

Creates a comment for a task. The task must be created from the form to which the extension is connected. Otherwise, Pyrus will return an error and the request will be ignored.

Parameters:

account_id — string. Unique identifier of the extension account in an external system.
task_id — number. The ID of the task to which the comment should be added.
mappings — data for auto filling in form fields. An array of objects in the following format:
- code — string. The symbolic code of the Pyrus form field.
- value — string. Value for the field in Pyrus. Max length 300 characters.
send_to_external_channel — boolean variable. Sending the comment to external channels in the task. By default, it is set to false.
comment_text — string. Comment text.
comment_text_html — string, optional. Comment text containing html formatting. Allowed html tags:
- <i>text</i> — italic;
- <br> — line break;
- <code>text</code> — code;
- <b>text</b> — bold;
- <s>text</s> — strikethrough;
- <div data-type=\"heading\">text</div> — heading;
- <q>text</q> — quote;
- <mark data-color=\"red\">text</mark> — red color;
- <mark data-color=\"yellow\">text</mark> — yellow color;
- <mark data-color=\"green\">text</mark> — green color;
- <mark data-color=\"blue\">text</mark> — blue color;
- <ul><li>text1</li><li>text2</li></ul> — bulleted list;
- <ol><li>text1</li><li>text2</li></ol> — numbered list;
- <a href="url">text</a> — hyperlink;
- <button>text</button> — button.
attachments — an array of strings, each of which is the guid of the uploaded attachment file on the Pyrus server. Max — 100 attachment files. You can upload a file and get its guid using the files/upload method.

Returns:

error_code — string, optional. Error code.
error — string, optional. Error message.

Allowed error code values:

unrecognized_account_id — extension account ID is not registered in Pyrus. Message not processed.
webhook_is_disabled — user has disabled notifications for new messages. Task is not created.
unrecognized_task_id — task ID is not registered or the extension does not have access to this task.
invalid_field_mapping_code — invalid Pyrus form field code passed in the code field of the mappings array object. Check that the code is correct. At the same time, a task is created based on the form, but the data sent in the value field is ignored. Invalid field codes will be indicated in the error_message field of the response.

Example request via 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

Available with the Online Chat feature.

A request-notification to Pyrus about a new message from an external system. The message is created as a comment in the task. Pyrus automatically determines in which task to write the comment, depending on the user's settings. At the same time, Pyrus creates an external communication channel in the task to communicate with the sender from the Pyrus interface. When the user writes a comment in the external channel, Pyrus calls the sendmessage method. Thus, the integrations/getmessage request and the sendmessage webhook support online chat and enable creating and processing requests based on inquiries in the account connected to the extension.

Parameters:

account_id — string. Unique identifier of the integration account in the external system (group ID in VKontakte, bot name in Telegram, etc.);
channel_id — string. Unique identifier of the channel for messages in the integration (chat ID in Telegram, user ID in VKontakte, etc.). Max length 300 characters;
sender_name — string. Sender's name of the message. Max length 100 characters;
message_type — field "Message type code", which appears when the online chat feature is enabled. Online chats can be connected in the personal account in the additional functions settings block.
message_text — string. Message text. Max length 10,000 characters.
message_text_html — string, optional. Message text containing html formatting. Allowed html tags:
- <i>text</i> — italic;
- <br> — line break;
- <code>text</code> — code;
- <b>text</b> — bold;
- <s>text</s> — strikethrough;
- <div data-type=\"heading\">text</div> — heading;
- <q>text</q> — quote;
- <mark data-color=\"red\">text</mark> — red color;
- <mark data-color=\"yellow\">text</mark> — yellow color;
- <mark data-color=\"green\">text</mark> — green color;
- <mark data-color=\"blue\">text</mark> — blue color;
- <ul><li>text1</li><li>text2</li></ul> — bulleted list;
- <ol><li>text1</li><li>text2</li></ol> — numbered list;
- <a href="url">text</a> — hyperlink;
- <button>text</button> — button.
mappings — data for auto filling of form fields. An array of objects in the following format:
- code — string. Field code for Pyrus form;
- value — string. Value for the field in Pyrus. Max length 300 characters.

Returns an array of objects with the following parameters:

task_id — number, task ID;
is_new_task — boolean field. Has a value of true if a new task was created, and false if a record was added to an existing task;
responsible_person — user specified as responsible in the task. Object in the following format:
- user_id — number, user ID;
- first_name — string, user's first name;
- last_name — string, user's last name;
- work_phone — string, user's work phone.
error_code — string, optional. Error code.
error — string, optional. Error message. Max length 300 characters.

Allowable error code values:

unrecognized_account_id — extension account ID is not registered in Pyrus. Message not processed;
webhook_is_disabled — user has disabled for new messages. Message not processed;
too_large_message_text — message text in the message_text field is too large. Message not processed;
unrecognized_message_type — unknown message type. The message is processed, using the first object from the "Message Type Code" field when the online chat function is enabled. Unknown message type code will be indicated in the error_message field of the response.
invalid_field_mapping_code — invalid Pyrus form field code passed in the code field of the mappings array object. Check that the code is correct. The message is processed (a task is created from the form or a comment is added), but the data sent in the value field is ignored. Invalid field codes will be indicated in the error_message field of the response;
too_many_attachments — the attachments field contains more than 100 elements. The message is processed (a task is created from the form or a comment is added), but only the first 100 files from the attachments field are attached to the comment. The list of ignored file guids will be indicated in the error_message field of the response;
unrecognized_attachment_id — the ID of the attached file is incorrect. The file with the specified identifier is missing. The list of incorrect file guids will be indicated in the error_message field of the response. If the message is not empty, it is processed (a task is created from the form or a comment is added).

Example request via 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": "Paul Jones",
    "message_type": "Telegram",
    "message_text": "Hello! Could you please move the delivery to Thursday?",
    "mappings": [
      {"code":"SenderName", "value":"Paul Jones"},
      {"code":"Subject", "value":"Hello! Could you please move the delivery to Thursday?"}
    ],
    "attachments":[
      "50b15ea9-41aa-4820-8350-8c6a3a16ed84",
      "00464c7d-9bd1-42ac-901b-3beb8e9ecee5"
    ]
  }'

Response body:

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

POST /call

Available with Telephony feature.

Request to register a call in Pyrus from the API telephony system. The call is registered as a task in a form connected to an extension. Pyrus automatically determines whether to create a new task or add a comment to an existing one. When the internal_number parameter is specified, Pyrus will search for users with the Work Phone field filled out in their Pyrus profile. If a match is found, the user will be assigned responsibility for the task, and this will be reflected in the comments. After registering the call for the user responsible for the task, a new tab with the task will open in the browser.

Parameters:

account_id — string. Unique identifier of the extension account in the external system.
from_number — string. Phone number of the caller.
to_number — string. Phone number that was called.
internal_number — string, optional. Operator's internal number.
mappings — data for auto filling of form fields. Array of objects in the following format:
- code — string. Symbolic code of the Pyrus form field.
- value — string. Value for the field in Pyrus. Max length 300 characters.

Returns an array of objects from the specified parameters:

task_id — number. ID of the created task.
is_new_task — boolean field. It is true if a new task was created, and false if a record was added to an existing task.
responsible_person — the user specified as responsible in the task. Can be empty. Object structure:
- user_id — number, user identifier;
- first_name — string, user's first name;
- last_name — string, user's last name;
error_code — string, optional. Error code.
error — string, optional. Error message. Max length 300 characters.

Allowed error code values:

unrecognized_account_id — extension account ID is not registered in Pyrus. Message not processed.
webhook_is_disabled — user has disabled notifications for new messages. Message not processed.
invalid_field_mapping_code — invalid Pyrus form field code passed in the code field of the mappings array object. Check that the code is correct. At the same time, the message is processed (a task is created based on the form or a comment is added to it), but the data sent in the value field is ignored. Invalid field codes will be indicated in the error_message field of the response.

Example request via 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"}
    ]
  }'

Response body:

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

POST /attachcallrecord

Available with Telephony feature/

Request to add call information to a Pyrus task. For the request to be processed, one of the following parameters must be specified: external_id, task_id, or both from_number and to_number parameters. Otherwise, Pyrus will not be able to identify the call and will return an error code required_parameters_not_specified.

Processing result of the attachcallrecord request:

Parameters:

account_id — string. Unique identifier of the extension account in an external system.
record_file — string. Unique identifier of the file that was uploaded using the /files/upload request. The uploaded file is attached indicating that it is a phone call channel. The file must have an extension of one of the audio formats (ac3, mp3, ogg, wav, wma), otherwise the file will not be attached and an error will be returned.
from_number — string, optional. Phone number of the caller.
to_number — string, optional. Phone number that was called.
external_id — string, optional. Call identifier in an external system.
task_id number, optional. ID of the created task. Returned in call.
mappings — data for auto filling of form fields. Array of objects in the following format:
- code — string. Symbolic code of the Pyrus form field.
- value — string. Value for the field in Pyrus. Max length 300 characters.

Returns:

error_code — string, optional. Error code.
error — string, optional. Error message. Max length 300 characters.

Allowed error code values:

unrecognized_call_id — the call ID is not registered in Pyrus. Message not processed.
webhook_is_disabled — the user has disabled notifications for new messages. Message not processed.
invalid_field_mapping_code — invalid Pyrus form field code passed in the code field of the mappings array object. Check that the code is correct. At the same time, the message is processed (a task is created from the form or a comment is added to it), but the data sent in the value field is ignored. Invalid field codes will be specified in the error_message field of the response.
unrecognized_attachment_id — invalid attachment ID.
unsupported_record_file_format — incorrect call recording file format.

Example request via 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

Used to upload a file to Pyrus.

In most programming languages or tools for sending REST API requests, such as curl or Postman, a correct request will be automatically generated if you specify the encoding type as multipart/form-data when sending data. So, to upload a file, all you have to do is specify the path to the file in the request body.

The response will return the file's GUID, which can be used in certain fields in some requests, such as the attachments field in the getmessage request or the record_file field in the attachcallrecord request. Files not attached to any message will be deleted after some time. Upload exactly one file using the specified request.

If you need to upload multiple files, run the request multiple times accordingly. The maximum size of an attached file is 2 GB.

Returns:

guid — string. Temporary identifier of the uploaded file. Used to attach the file to a message in getmessage;
error_code — string, optional. Error code.
error — string, optional. Error message.

Allowed error code values:

empty_file — cannot upload an empty file;
no_file_in_request — request does not contain any files;
too_large_file — file size exceeds the maximum limit.

Example request using 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'

Response body:

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

GET /files/download/{file-id}

Request to download a file from Pyrus.

Parameters:

file-id — number. ID of the attachment file, passed in the attachment_ids parameter of the sendmessage request. Returns:
error_code — string, optional. Error code.
error — string, optional. Error message.

Example request using curl:

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

Response headers:

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

API methods for extensions

POST /token

POST /task

POST /comment

POST /getmessage

POST /call

POST /attachcallrecord

POST /files/upload

GET /files/download/{file-id}

Was this article helpful?