Cisco Finesse APIs

APIs that control actions on the Finesse desktop and call control make use of two objects:

• User object: The User object represents agent and supervisor data and actions. This object is used to get information about a single user or list of users, to sign in or out of the Finesse Desktop, and change agent state.

• Dialog object: The Dialog object represents a dialog with participants. For media type "voice", this object represents a call. A participant can represent an internal user (such as an agent) or an external user (for example, a customer). A participant can belong to only one dialog but a user can be a participant in several dialogs. The Dialog object is used for call control and call data.

GET requests are synchronous. That is, the response body of a successful GET request contains all requested contents, which you can view in Postman or RESTClient. No event is published by XMPP and no event is received in Pidgin.

PUT and POST requests are asynchronous. A successful response is an HTTP return code of 200 or 202. The response body does not contain the updated object information.

If a PUT, POST, or DELETE request is on a User or Dialog object, the update is published by XMPP as a real-time event to Pidgin. If a PUT, POST, or DELETE request is on a configuration object (for example, a ReasonCode object), XMPP does not publish a real-time update. You must perform a GET request to get an updated copy of the object.

GET, PUT, POST, and DELETE requests that fail Finesse server internal checks are synchronous. If a request fails, Postman or RESTClient display the error. No event is published by XMPP to Pidgin. However, if the request fails on CTI side, Finesse will send an api Error XMPP event back to client after receiving a failure confirmation response from the CTI Server.

For each object, Finesse maintains an internal request queue where each subsequent request for this object is processed only after a success or a failure confirmation response is received from the CTI Server for the previous request.

RequestId is a user provided unique string that is added to the request API header and used to correlate originating requests with the resulting XMPP notifications or errors.

XMPP event notifications that match the requested action are tagged with the requestId (if available) from the original request. If the originating request results in a system error, the corresponding XMPP error notifications also contain the requestId. Note that the request id is not sent in the case of synchronous responses to GET requests. Although not mandatory, using a unique requestId helps in tracking error messages and allows a user to debug issues faster, as messages with requestId are easily tracked in Finesse logs.

The following sections provide instructions and examples for using the APIs with Postman and Pidgin.