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
| 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:
|
Returns
| Name | Description |
| task_id | Numeral. 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
| 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 to integrations/call. |
| mappings | Data for autofilling form fields. Array of objects type:
|
Returns
| Name | Description |
| error_code | Line, optional. Error code. |
| error | Line, optional. Error notification. 300 symbols max. |
Errors
| Name | Description |
| unrecognized_account_id | Account ID not registered with Pyrus. Request not being processed. |
| webhook_is_disabled | A required field has not been filled out (the error message will indicate which one). |
| unrecognized_integration_guid | The integration id entered in the integration_guid parameter does not exist. |
| unrecognized_call_id | Request ID not registered in Pyrus. Request not being processed. |
| webhook_is_disabled | User has turned off new message notifications. 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. |
Pyrus Tip: POST /calls, PUT calls/{call_guid} и POST calls/{call_guid}/event methods are outdated. But they are still work.