api:telephony

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 /calls

Register a call
This method returns the GUID of the incoming call, and the id of the generated request.

POST https://api.pyrus.com/v4/calls

{
  "to": "+18769876543",
  "from": "+18769542312",
  "extension": "0000000",
  "integration_guid": "5d8dc3d6-27e7-4cd4-a057-2b4f4d74e0a5"
}
Show response

{
  "call_guid": "718c41fb-6b8b-48af-8863-b048d70d9589",
  "task_id": "43534533145"
}

Parameters

Name Description
to The phone number of the operator the call was made to.
from * The phone number of the caller.
extension Operator’s internal number. This number identifies the co-worker to whom the event is registered. For this to work, the “Work number” field on the Pyrus user form has to be filled in. In this case, when the parameter is set, a user search is performed. If a match is found, the “Assignee” field will auto-fill. If the call is being recorded in an already existing task, the task is reassigned to the new assignee, and information about this appears in the comments.
integration_guid * The GUID generated when the integration was connected to the form.
call_guid The GUID of the call that was registered as a new incoming call, so that additional information can be added to the call.
task_id The id of the task that was generated when the function was dialed in, or a task to which information about a new call has been added as a comment.
* Required field

Errors

Name Description
invalid_value_format Cannot reconcile the definition entered with the indicated type (the error message will show which one).
required_field_missing 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.

PUT calls/{call_guid}

Adding information about the call
When running this function, you can have the parameters configured in any combination. Each parameter is either recorded in the appropriate field in the task, which contains the call with the according call_guid; or, if it’s not a first call, it gets added as a comment. The function can be run more than once, adding new information to a task about a first call, or re-recording already existing information as a comment when additional calls come in from the same number.

POST https://api.pyrus.com/v4/calls/718c41fb-6b8b-48af-8863-b048d70d9589

{
  "start_time": "2009-02-15T00:00:00Z",
  "end_time": "2009-02-15T00:00:00Z",
  "rating": 5,
  "disconnect_party": "agent",
  "call_status": "answered",
  "file_guid": "2d7fee85-1671-43de-8b72-3bf07032c443"
} 

Parameters

Name Description
start_time The time when the incoming call began (time format UTC, YYYY-MM-DDThh:mm:ssZ).
end_time The time when the incoming call ended (time format UTC, YYYY-MM-DDThh:mm:ssZ).
rating Call rating (whole digit between 1 and 5).
disconnect_party Who terminated the call. Options: “agent”, “client”, “error”, “other” (limited choice text definition).
call_status Status of the call. Options: “answered”, “no answer”, “busy”, “error”, “other” (limited choice text definition).
file_guid A unique identifier for files uploaded through the /files/upload function. The uploaded file is attached as a comment, indicating that this is the phone call channel. When attaching the file, the system will check that its extension corresponds to one of the audio formats (ac3, mp3, off, wav, wma). If the file does not correspond, it is not attached, and an error message is displayed.

Errors

Name Description
invalid_value_format Cannot reconcile the definition entered with the indicated type (the error message will show which one).
unrecognized_attachment_id The identifier of the attached file is incorrect. The user does not have a file with the indicated identifier.
access_denied_task You do not have access rights to this task. Make sure the user on whose behalf the request is being filled out has all the necessary rights.
unrecognized_call_guid That call identifier does not exist in the system.
unsupported_attachment_format The attached file has an extension that does not correspond to the list of audio file formats.

POST calls/{call_guid}/event

Register a call-related event
Currently the only supported event is “call answered”. When it’s registered the ticket task page automatically opens in the operator’s Pyrus web app.

POST https://api.pyrus.com/v4/calls/718c41fb-6b8b-48af-8863-b048d70d9589/event

{
  "event_type": "show",
  "extension": "0000000"
}

Parameters

Name Description
event_type An event that gets registered in the system. Options: “show”.
extension Operator’s internal number. This number identifies the co-worker to whom the event is registered. For this to work, the “Work number” field on the Pyrus user field has to be filled in. If the field is blank, the same definition as when the call was generated will be used.

Errors

Name Description
unrecognized_call_guid That call identifier does not exist in the system.

Was this article helpful?

Yes, thanks! No, I have a question