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.


URI:

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

Example URI:

http://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>
</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

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

Related References
Dialog CTI Error Notification