Set Agent State

This action sets the state of the Agent who owns the session specified by the SessionId property.

An Agent can only be set to either an Available or Unavailable state. The other Agent States are controlled by the platform as it route contacts or as the Agent logs in and out of the platform. There is only one Available state, but there are multiple reasons an Agent can be in the Unavailable state as described below:

  1. The Agent can be in the default Unavailable state with no reason code. This is the state when an agent session is started.
  2. The Agent can be assigned a reason code for being Unavailable from a collection of reasons known as unavailable codes. These unavailable codes are created by the customer. For example, they may have an On Break unavailable code, a Lunch unavailable code, or a Training unavailable code, etc. These unavailable codes can be retrieved from the GET /admin/teams/{teamId}/unavailable-codes method.
  3. The Agent can be in an After Contact Work (ACW) state. These are special unavailable states that are created by the customer on the CXone platform, and are unavailable codes with the ACW flag. These unavailable codes can only be used as "reason" if the Agent is handling an active contact, otherwise the API will return a 409 error.

Unavailable codes that are ACW states will have the isAcw flag set to true. Note that ACW unavailable codes can also have an auto-timeout, which is used by the platform to automatically end the ACW unavailable code and move the Agent to their next state. You can use this to display a countdown timer to the Agent when the ACW unavailable code begins, enabling the Agent to see how much time they have before the ACW unavailable code ends.

Setting the Agent’s session to an ACW unavailable code causes the Agent to go into an Unavailable state during which the time is counted against the active interaction time, even though the interaction with the contact has ended. While in this state, the Agent will not be delivered other interactions (because they are Unavailable), but the time is recorded as work time for the interaction that just ended.

Dependencies

  • This action will inevitably require the use of additional API actions in order to obtain the SessionID of the agent. Refer to developer.niceincontact.com A square with an arrow pointing from the center to the upper right corner. for more information on how to obtain the session ID.

  • For organizations that use Supervisor and a Agent application: You can use the Set Agent STATE action to set agent states to Available. However, for supervising agents, you must configure your script to prevent issues when the supervising agent receives a call in Agent while they're monitoring another agent in Supervisor. There are two possible solutions: 

    • Use the AgentState action to check the supervising agent's state. If the agent's state is Unavailable or a similar state, such as Unavailable Monitoring, your script must bypass the Set Agent State action. This prevents the agent's state from being changed to Available. Additionally, the script must handle the incoming interaction in some other way. For example, it could go to voicemail, or route to another ACD skill or agent.
    • Connect the Set Agent STate action's On Error branch. When a supervisor is monitoring an agent, the system doesn't allow the supervisor's state to be set to Available. It takes the On Error branch if it's connected. If it's not connected, it takes the Default branch. You must ensure that your script handles the incoming interaction in some other way.

Supported Script Types

The icon for a Generic script type - a rectangle with < and > symbols inside it.

The icon for the Email script type - a large @ symbol in a diamond.

The icon for the Chat script type - a chat bubble with an ellipsis inside (...), in a diamond shape.

The icon for the Phone script type - an old-style phone handset with curved lines indicating sound coming out of it.

The icon for the Voicemail script type - a symbol that looks like a cassette tape - two circles sitting on a horizontal line.

The icon for the Work Item script type-a piece of paper with one corner folded down and a bullet list on it.

The icon for the SMS script type - a smart phone with a chat bubble coming out of it.

The icon for the Digital script type - a computer monitor with a smartphone next to it.

Generic

 Email Chat Phone Voicemail Work Item SMS Digital

Input Properties

These properties define data that the action uses when executing.

Property

Description

Caption

Enter a short phrase that uniquely identifies this action in the script. The caption appears on the script canvas under the action icon. The default is the action name.

SecurityUser

The output value of the SetSecurityUser action which authenticates a selected agent based on their permissions in the security profile. This field accepts variable formatted with curly braces ( { } ). The default value is SecurityUser (same default output value of SetSecurityUser).

SessionId

The unique ID assigned to the agent's login session within the CXone system.
State The desired state to which the agent will be set after executing this action successfully. Options include Unavailable or Available and can be consumed as variables.
Reason This property is used to enter text for the Unavailable Code that also displays on the agent interface Unavailable status bar next to SystemOutstate – {inserted text}. This property is unused when the Agent state is available.

Result Branch Conditions

Result branch conditions allow you to create branches in your script to handle different outcomes when an action executes.

Condition

Description
Default Path taken unless the script meets a condition that requires it to take one of the other branches. It is also taken if the action's other branches are not defined.
Success Path taken if the action completes without errors and any API calls or data returns were successful (2xx response codes).
InvalidSecurityUser Path taken when an invalid security user is used.
InvalidAgentSession Path taken if the SessionID entered is invalid.
InvalidStateRequest Path taken if an invalid state is requested other than the available options.
InvalidUnavailableCode Path taken if the Unavailable Code specified is invalid.
InvalidState Path taken if a value other than Unavailable or Available is entered.

Other Options

If your desire is to leverage an existing, custom Unavailable Code in which to place the agent, use the Framework API action Set Agent State V7. The V7 action enables you to use the AgentID variable instead of the session ID, simplifying the outcome of changing an agent’s state without leveraging multiple API actions.