Contact Center methods

createAgents(User[] agents, AgentGroup agentGroup, AgentState initialState)

Creates agents in the supplied Agent Group.

Input

• agents: Valid existing users (see createUser)
• agentGroup: An externalId that determines the AgentGroup in which the Agents are created
• initialState: An AgentState used to initialize these agents

Response

AgentState[] (D)

Availability

Engage 7.3.3

Errors returned

• ARG_INVALID_CHAR – Invalid Data, argument '%s' contains invalid characters
• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• INVALID_OBJECT_TYPE – The supplied object '%s' is not of the correct type
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of agents exceeded

Notes

• This method may successfully create some of the supplied agents and fail to create others. In this case the failures will be returned as warnings (one per failure).
• The maximum number of items that may be supplied using this method is 1,000.
• The maximum number of agents active is 1,000.

createAgentsUsingString(String agents, AgentGroup agentGroup, AgentState initialState)

Creates agents in the supplied Agent Group.

Input

• agents : Valid existing users (see createUser)
• agentGroup : An externalId that determines the AgentGroup in which the Agents are created
• initialState : An AgentState used to initialize these agents

Response

AgentState[] (D)

Availability

Engage 8.5.0

Errors returned

• ARG_INVALID_CHAR – Invalid Data, argument '%s' contains invalid characters
• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of agents exceeded

Notes

• This method may successfully create some of the supplied agents and fail to create others. In this case the failures will be returned as warnings (one per failure).
• The agent string must be formatted as per the specification in the Appendix.
• The maximum length (in bytes) supported for the agents string is 100,000.
• The maximum number of agents active is 1,000.

acquireAgent(AgentState agentState)

Acquires an agent based on an Agent State.

Input

agentState: Both currentContactState and currentScheduleGroup are used to determine the Agent Group.

Response

AgentState (D)

Availability

Engage 7.9.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

releaseAgent(AgentState agentState)

Releases an agent based on the Agent Group.

Input

agentGroup : Identifies the Agent to release.

Response

AgentState (D)

Availability

Engage 7.9.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

deleteAgents(User[] agents)

Removes agents from the supplied organization (Agent Group or Account).

Input

agents : A set of users with an externalId that determines the user (agent) to be deleted.

Response

NONE

Availability

Engage 7.3.3

Errors returned

• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• This method may successfully delete some of the supplied agents and fail to delete others. In this case the failures will be returned as warnings (one per failure).
• The maximum number of items that may be supplied using this method is 1,000.

showAgentStateUsingUser(User agent)

Retrieves state information for the supplied Agent.

Input

agent : An externalId that determines the user (agent).

Response

AgentState (D)

Availability

Engage 7.3.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

showAgentStateUsingDevice(Device device, Org org)

Retrieves AgentState information for the supplied Device. This method returns an AgentState object that reflects the Agent who is currently conversing with the supplied Client (as specified by the Device).

Input

• device: value to be searched (searches using externalId of Device)
• org : internalId or (externalId, parent, type)

Response

AgentState (D)

Availability

Engage 7.5.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced Org does not exist

Notes

• Only those devices currently Direct Connected will be searched.
• Unlike most show services, this service is not by unique key and the supplied device may not be found due to a timing issue or invalid input. In this case OBJECT_NOT_EXISTS will not be returned and the result will be empty.
• The supplied Org must be either a valid Account or Enterprise.

listAgentStatesUsingEntity(BaseEntity baseEntity)

Retrieves information related to all agent states for an Agent Group or Account.

Input

baseEntity: externalId or internalId (Agent Group or Account)

Response

AgentState[] (D)

Availability

Engage 7.6.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

The maximum number of items returned using this method is 1,000.

changeAgentState(AgentState agentState)

Updates fields/attributes of the supplied AgentState.

Input

agentState: internalId + any fields to be changed

Response

AgentState (D): Updated object.

Availability

Engage 7.3.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s
• INVALID_STATE – Invalid Agent State '%s'
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

Currently supported attributes are

• AgentState.Agent.LoginEnabled
• AgentState.requestedAction
• AgentState.Agent.Attributes[registrationMethod]
• AgentState.currentPhoneNumber
• AgentState.requestedWorkState.

showAgentGroupState(AgentGroup agentGroup)

Retrieves state information for the supplied Agent Group.

Input

agentGroup : externalId

Response

AgentGroupState (D)

Availability

Engage 7.7.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

listAgentGroupStates(Org org)

Retrieves information about the state of Agent Groups for an Account or an Agent Group.

Input

org : An external id that determines the organization in which the Agent is being Created (Agent Group or Account)

Response

AgentGroupState[] (D)

Availability

Future

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

The maximum number of items returned using this method is 1,000.

changeAgentGroupState(AgentGroupState agentGroupState)

Updates fields/attributes of the supplied AgentGroupState.

Input

agentGroupState: internalId of the associated AgentGroup + any fields to be changed

Response

NONE

Availability

Engage 7.6.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_INVALID_FORMAT – Attribute is not formatted correctly
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

Supported attributes are:

Attribute	Standard	Enhanced	Remote
allocatedCount	✔	If mode is group	✔
currentStartTime	✔	✔	✔
currentEndTime	✔	✔	✔
state	N/A	N/A	✔

createAgentGroup(AgentGroup agentGroup, Org parent)

Creates a new AgentGroup and adds it to the Org (parent)

Input

• agentGroup : full set of attributes
• parent : internalId or (externalId, parent, type)

Response

AgentGroup (D)

Availability

Engage 7.6.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_INVALID_DATA – Attribute contains invalid data '%s'
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of active organizations exceeded

Notes

• An externalId must be provided and must be unique within the context of its parent.
• The maximum number of AgentGroups simultaneously available is 50.
• The parent must be an Account.

deleteAgentGroup(AgentGroup agentGroup)

Deletes an AgentGroup

Input

agentGroup : internalId or (externalId and parent)

Response

NONE

Availability

Engage 7.7.5

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• INVALID_STATE – returned if the AgentGroup is currently being utilized.

showAgentGroup(AgentGroup agentGroup)

Retrieves information about the supplied AgentGroup.

Input

agentGroup: internalId or (externalId and parent)

Response

AgentGroup (D)

Availability

Engage 7.6.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

The maximum number of items returned using this method is 1,000.

changeAgentGroup(AgentGroup agentGroup)

Updates fields/attributes of the supplied AgentGroup.

Input

agentGroup: internalId of the AgentGroup + any fields to be changed

Response

AgentGroup (D): Updated object.

Availability

Engage 7.7.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• INVALID_STATE – Invalid Agent State '%s'
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

The only supported attributes are intensity, initialWorkState, and maxBreakTime.

createScheduleGroup(ScheduleGroup scheduleGroup, AgentGroup parent)

Creates a new ScheduleGroup and adds it to the AgentGroup.

Input

• scheduleGroup : full set of attributes
• parent : internalId or externalId

Response

ScheduleGroup (D)

Availability

Engage 7.6.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of active organizations exceeded

Notes

• If an externalId is provided it must be unique within the context of its parent.
• The maximum number of ScheduleGroups simultaneously available is 50.

deleteScheduleGroup(ScheduleGroup scheduleGroup

Deletes a ScheduleGroup (some business state validation required).

Input

scheduleGroup : internalId or externalId

Response

NONE

Availability

Future

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

Consider what happens if ScheduleGroup is currently being utilized.

showScheduleGroup(ScheduleGroup scheduleGroup)

Retrieves information about the supplied ScheduleGroup.

Input

scheduleGroup: internalId

Response

ScheduleGroup (D)

Availability

Engage 7.6.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist