Telephony
The methods are intended for integration with telephony in call centers. They allow you to register a new ticket when there's a new incoming call, to show the service agent a ticket when they pick 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/ callRegister a call - POST /
integrations/ attachcallrecordAdd information about a call
POST integrations/call
Register a call
Request to register a phone call from the API telephony system in Pyrus. 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, the user will be assigned as responsible in the task, and this information 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": "CallStartTime",
"value": "2021-12-23T00:11:32Z"
}]
}
Response body
{
"task_id": 458732,
"is_new_task": false,
"responsible_person": {
"user_id": "34231",
"first_name": "Ilya",
"last_name": "Laserson",
"work_phone": "+79338762030"
}
}
Parameters
| Name | Description |
| account_id | Line. Unique ID of the extension's account in the external system. |
| from_number | Line. Sender phone number. |
| to_number | Line. Recipient phone number. |
| internal_number | Line, optional. Internal operator number. |
| external_id | Line, optional. Call ID in external system. |
mappings | Data for autofilling form fields. Array of objects type:
The following fields are available for filling (can be used with field codes):
|
Returns
| Name | Description |
| task_id | Numeral. Task ID. |
| is_new_task | Boolean. Set to true if a new task was created, false if a record was added to an existing task. |
| error_code | Line, optional. Error code. |
| error | Line, optional. Error notification. 300 symbols max. |
| responsible_person | The user assigned as responsible for the task. Can be empty. Object type:
|
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": "CallStartTime",
"value": "2021-12-23T00:11:32Z"
},
{
"code": "CallEndTime",
"value": "2021-12-23T00:24:02Z"
},
{
"code": "Rating",
"value": 5
}
]
}
Parameters
| Name | Description |
| account_id | Line. Unique ID of the extension's account in the external system. |
| record_file | Line. 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_number | Line, optional. Sender phone number. |
| to_number | Line, optional. Recipient phone number. |
| external_id | Line, optional. Call ID in external system. |
| task_id | Numeral, optional. ID of the created task. Returns in integrations/call. |
mappings | Data for autofilling form fields. Array of objects type:
The following fields are available for filling (can be used with field codes):
|
Returns
| Name | Description |
| error_code | Line, optional. Error code. |
| error | Line, optional. Error notification. 300 symbols max. |
Errors
| Name | Description |
| unrecognized_call_id | Request ID not registered in Pyrus. Request not being processed. |
| invalid_field_mapping_code | Unacceptable 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_id | Attachment file ID incorrect. |
| unsupported_record_file_format | Phone call record file format incorrect. |
| unrecognized_account_id | Account ID not registered with Pyrus. Request not being processed. |
| webhook_is_disabled | User has turned off new message notifications. Request not being processed. |