Help Center

Telephony

The methods are intended for integration with telephony in call centers. They allow to register a new ticket when there's new incoming call, to show service agent a ticket when she picks up a call, to attach an audio recording after the call is terminated.

Read more about how to set up the integration in the Extension section.

Methods

POST / integrations/call

Register a call

Request to register a phone call from the API telephony system in Pyrus, or to refresh information about the call.

The phone call is registered as a task made in the form the extension is connected to. Whether to create a new task or add a comment to an old Pyrus task is determined automatically.

When the internal_number parameter is indicated, Pyrus will search for users whose Work phone fields are populated in their Pyrus users’ profiles. If a correspondence is found, that will be noted in the comment.

Once a call is registered, a new tab, containing the task, opens in the browser of the person responsible for the task.

POST https://api.pyrus.com/v4/integrations/call

Request body

{
  "account_id": "uniqueID12345",
  "from_number": "+79774221338",
  "to_number": "+74953009080",
  "internal_number": "200",
  "mappings": [{
    "code": "Subject",
    "value": "Consultation"
  }]
}

Response body

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

Parameters

NameDescription
account_idLine. Unique ID of the extension's account in the external system.
from_numberLine. Sender phone number.
to_numberLine. Recipient phone number.
internal_numberLine, optional. Internal operator number.
external_idLine, optional. Call ID in external system.
mappingsData for autofilling form fields. Array of objects type:
  • code — line. Pyrus form field symbol code.
  • value — line. Pyrus field value. 300 symbols max.

Returns

NameDescription
task_idNumeral. Task ID.

POST / integrations/attachcallrecord

Adding information about the call

Request to add information about a call to the Pyrus task. To successfully process the request, one of the following parameters must be indicated: external_id, task_id or from_number and to_number. If these parameters are not entered, Pyrus will not be able to identify the request and will return Error code required_parameters_not_specified.

POST https://api.pyrus.com/v4/integrations/attachcallrecord

Request body

{
  "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
    }
  ]
}

Parameters

NameDescription
account_idLine. Unique ID of the extension's account in the external system..
record_fileLine. Unique ID of the file uploaded with a /files/upload request. The uploaded file is attached with an indication that this is the telephone call channel. The file must have one of these audio format extensions: ac3, mp3, ogg, wav, or wma. If it does not have this extension, the file will not be attached and an error will be returned.
from_numberLine, optional. Sender phone number.
to_numberLine, optional. Recipient phone number.
external_idLine, optional. Call ID in external system.
task_idNumeral, optional. ID of the created task. Returns to integrations/call.
mappingsData for autofilling form fields. Array of objects type:
  • code — line. Pyrus form field symbol code.
  • value — line. Pyrus field value. 300 symbols max.

Returns

NameDescription
error_codeLine, optional. Error code.
errorLine, optional. Error notification. 300 symbols max.

Errors

NameDescription
unrecognized_account_idAccount ID not registered with Pyrus. Request not being processed.
webhook_is_disabledA required field has not been filled out (the error message will indicate which one).
unrecognized_integration_guidThe integration id entered in the integration_guid parameter does not exist.
unrecognized_сall_idRequest ID not registered in Pyrus. Request not being processed.
webhook_is_disabledUser has turned off new message notifications. Request not being processed.
invalid_field_mapping_codeUnacceptable Pyrus form field code, entered in code field of the object from the mappings array. Check the code. Request being processed (a form task or a comment in one is being created), but the data entered in the value field are being ignored. Unacceptable field codes will be indicated in the error field of the reply.
unrecognized_attachment_idAttachment file ID incorrect.
unsupported_record_file_formatPhone call record file format incorrect.

Pyrus Tip: POST /calls, PUT calls/{call_guid} и POST calls/{call_guid}/event methods are outdated. But they are still work.

Was this article helpful?