User—Sign In to Finesse

The User—Sign in to Finesse API allows a user to sign in to the CTI server. If the response is successful, the user is signed in to Finesse and is automatically placed in NOT_READY state.

If five consecutive sign-ins fail due to an incorrect password, Finesse blocks access to the user account for a period of 5 minutes.

This API forces a sign-in. That is, if the user is already signed in, that user is authenticated via the sign-in process. If the user's credentials are correct, the user is signed in again but the user keeps the current state. For example, if a user signs in, changes state to Ready, and then signs in again, the user remains in Ready state.

Note	To sign in as a mobile agent, see User—Sign In as a Mobile Agent. To sign in to nonvoice Media Routing Domains, see Media—Sign In.

URI:

https://<FQDN>/finesse/api/User/<id>

Example URI:

https://finesse1.xyz.com/finesse/api/User/1234

Security Constraints:

Users can only act on their own User objects.

HTTP Method:

PUT

Content Type:

Application/XML

Input/Output Format:

XML

HTTP Request:

<User>
    <state>LOGIN</state>
    <extension>1001001</extension>
    <activeDeviceId>CSFJP5550016</activeDeviceId>
</User>

Request Parameters:

id (required): The ID of the user

state (required): The new state that the user wants to be in (LOGIN)

extension (required): The extension with which the user wants to sign in

activeDeviceId: A unique ID of the active device.

Note

This parameter is required when the extension is a shared line between multiple devices and agent is enabled for shared ACD line usage.
This parameter is optional if there is only a single device associated with the extension, while shared ACD line usage is enabled for the agent.
This parameter should not be passed if shared ACD line usage is not enabled for the agent.

HTTP Response:

202: Success

400: Bad Request (for example, malformed or incomplete request, invalid extension)

400: Parameter Missing

401: Unauthorized (for example, the user is not authenticated in the Web Session)

404: Not Found (for example, the user ID is not known)

503: Service Unavailable (for example, the Notification Service is not running)

Example Failure Response:

<ApiErrors>
     <ApiError>
          <ErrorType>User Not Found</ErrorType>
          <ErrorMessage>UNKNOWN_USER</ErrorMessage>
          <ErrorData>4023</ErrorData>
   </ApiError>
</ApiErrors>

Notifications Triggered:

User notification

Platform-Based API Differences

Stand-alone Finesse with Unified CCE:

Finesse does not support agent sign-in with an E.164 extension when Finesse is deployed with Unified CCE. However, agents can make calls to and receive calls from E.164 phone numbers.

Coresident Finesse with Unified CCX:

Finesse supports agent sign-in with an E.164 extension when Finesse is deployed with Unified CCX. The maximum number of characters supported for an E.164 extension is 15 (a single plus sign followed by 14 digits).

Asynchronous Errors

Note	When accessing the Finesse REST API through the Finesse JavaScript library, asynchronous errors have a status code of 400. When receiving the asynchronous error directly through XMPP, the error message has the format described in "Dialog CTI Error Notification."

ErrorType

Reason

Deployment Type

Invalid Device

Attempt to sign in an agent with a multiline device without the correct Unified CM configuration for maximum calls and busy trigger for these devices.

All

Invalid Device

Attempt to sign in an agent with a device that does not exist.

All

Invalid Device

Attempt to sign in an agent with a device that is offline.

All

Invalid Device

Attempt to sign in an agent with an extension that is not associated with the Unified CCX Resource Manager provider.

All

Device Busy

Attempt to sign in an agent with a device that is already in use.

All

Parameter Missing

Attempt to sign in an agent without an active device, when multiple devices are associated with the extension supplied, while agent is enabled for shared ACD line usage.

All

Invalid Input

Attempt to sign in an agent with an unrecognized or invalid state.

All

Invalid Input

Attempt to sign in an agent with an active device ID,when the protocol version used for CTI connection is lesser than 24.

Note	The protocol version constraint is applicable only for Unified CCE deployments.

All

Authorization Failure

Attempt to sign in an unauthorized agent.

All

Invalid Authorization User Specified

Attempt to make a request by an agent to an unauthorized user.

All

User Not Found

Attempt to sign in an agent with invalid agent ID, or when an agent record is not part of the CTI.

All

Internal Server Error

Attempt to sign in an agent during runtime error (CTI server or any other component).

All