Jump to

• Request
• Response
• Examples

Get agents and queues

post

/engagement/api/agent/{fqSiteName}/v1/retrieveAgentsAndQueues

This operation is used by the agent to retrieve agent and queue information.
The following is the list of exception codes that can be returned from this operation:

• ACCESS_DENIED - Authentication failed.
• UNKNOWN_EXCEPTION - An unknown error has occurred.
• BAD_REQUEST - A field in the request is invalid.
• INTERNAL_SERVER_ERROR - An error occurred within the core server.
• INVALID_FIELD - An invalid agent information type was sent on the request.

Request

Path Parameters

• fqSiteName: string
  The fully qualified site name.

Header Parameters

• X-AID: string
  A header element containing the agent account identifier.
• X-JSESSIONID: string
  A header element containing the unique session identifier returned in the create automated agent session call.

Body ()

The object containing the request information.

Root Schema : com.rightnow.chat.rest.agent_api.model.requests.v1.RetrieveAgentsAndQueuesRequest

Type: object

Show Source

• id: integer(int64)
  The identifier associated with the specified type field value.
• includeAgentInformation: boolean
  Indicates whether a list of agent information objects are required. If true, then it returns the list of agent information objects in the response. If true, then you must provide a value for 'id' and 'type' fields.
• includeQueueInformation: boolean
  Indicates whether a list of queue information objects are required. If true, then it returns the list of queue information objects in the response.
• includeQueueStatistics: boolean
  Indicates whether the queue statistics information is required. If true, then it returns the queue statistics information in the list of queue information objects in the response.
• sequenceNumber(optional): integer(int64)
  The client application defined transaction sequence number.
• timeCreated(optional): integer(int64)
  The time the request was created in milliseconds.
• type: string
  Allowed Values: [ "GROUP", "PROFILE", "ENGAGEMENT" ]

  The identifier type.

{
    "required":[
        "id",
        "includeAgentInformation",
        "includeQueueInformation",
        "includeQueueStatistics",
        "type"
    ],
    "properties":{
        "includeAgentInformation":{
            "type":"boolean",
            "description":"Indicates whether a list of agent information objects are required. If true, then it returns the list of agent information objects in the response. If true, then you must provide a value for 'id' and 'type' fields."
        },
        "includeQueueInformation":{
            "type":"boolean",
            "description":"Indicates whether a list of queue information objects are required. If true, then it returns the list of queue information objects in the response."
        },
        "includeQueueStatistics":{
            "type":"boolean",
            "description":"Indicates whether the queue statistics information is required. If true, then it returns the queue statistics information in the list of queue information objects in the response."
        },
        "id":{
            "type":"integer",
            "format":"int64",
            "description":"The identifier associated with the specified type field value."
        },
        "type":{
            "type":"string",
            "description":"The identifier type.",
            "enum":[
                "GROUP",
                "PROFILE",
                "ENGAGEMENT"
            ]
        },
        "timeCreated":{
            "type":"integer",
            "format":"int64",
            "description":"The time the request was created in milliseconds."
        },
        "sequenceNumber":{
            "type":"integer",
            "format":"int64",
            "description":"The client application defined transaction sequence number."
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json; charset=utf-8

200 Response

The request completed successfully.

Body ()

Root Schema : com.rightnow.chat.rest.agent_api.model.responses.v1.RetrieveAgentsAndQueuesResponse

Type: object

Show Source

• agents: array agents
  The list of agent information objects.
• clientId(optional): integer(int64)
  The unique identifier of the agent client, created to identify the agent during this agent session.
• clientIdString(optional): string
  The unique identifier of the agent client in string format, created to identify the agent during this agent session.
• clientSendTime(optional): integer(int64)
  The time when the client request was received in yyyy-MM-dd'T'HH:mm:ssXXX format.
• queues: array queues
  The map of queue information objects keyed by the String representation of the queue identifier.
• sequenceNumber(optional): integer(int64)
  The client application defined transaction sequence number.
• sequenceNumberString(optional): string
  The client application defined transaction sequence number as a string.
• serviceFinishTime(optional): integer(int64)
  The time when the chat server completed processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format.
• serviceStartTime(optional): integer(int64)
  The time when the chat server began processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format.
• sessionId(optional): string
  The unique identifier of the agent session.

{
    "required":[
        "agents",
        "queues"
    ],
    "properties":{
        "agents":{
            "type":"array",
            "description":"The list of agent information objects.",
            "items":{
                "$ref":"#/definitions/com.rightnow.chat.rest.agent_api.model.types.v1.AgentInformation"
            }
        },
        "queues":{
            "type":"array",
            "description":"The map of queue information objects keyed by the String representation of the queue identifier.",
            "items":{
                "$ref":"#/definitions/com.rightnow.chat.rest.agent_api.model.types.v1.QueueInformation"
            }
        },
        "clientSendTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the client request was received in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "serviceStartTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the chat server began processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "serviceFinishTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the chat server completed processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "sessionId":{
            "type":"string",
            "description":"The unique identifier of the agent session."
        },
        "clientId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the agent client, created to identify the agent during this agent session."
        },
        "clientIdString":{
            "type":"string",
            "description":"The unique identifier of the agent client in string format, created to identify the agent during this agent session."
        },
        "sequenceNumber":{
            "type":"integer",
            "format":"int64",
            "description":"The client application defined transaction sequence number."
        },
        "sequenceNumberString":{
            "type":"string",
            "description":"The client application defined transaction sequence number as a string."
        }
    }
}

Nested Schema : agents

Type: array

The list of agent information objects.

Show Source

• Array of: object com.rightnow.chat.rest.agent_api.model.types.v1.AgentInformation

{
    "type":"array",
    "description":"The list of agent information objects.",
    "items":{
        "$ref":"#/definitions/com.rightnow.chat.rest.agent_api.model.types.v1.AgentInformation"
    }
}

Nested Schema : queues

Type: array

The map of queue information objects keyed by the String representation of the queue identifier.

Show Source

• Array of: object com.rightnow.chat.rest.agent_api.model.types.v1.QueueInformation

{
    "type":"array",
    "description":"The map of queue information objects keyed by the String representation of the queue identifier.",
    "items":{
        "$ref":"#/definitions/com.rightnow.chat.rest.agent_api.model.types.v1.QueueInformation"
    }
}

Nested Schema : com.rightnow.chat.rest.agent_api.model.types.v1.AgentInformation

Type: object

Show Source

• accountId(optional): integer(int64)
  The account identifier.
• accountIdString(optional): string
  The account identifier as a string.
• availableSessionCount(optional): integer(int32)
  The available session count of the agent.
• clientId(optional): integer(int64)
  The client identifier.
• clientIdString(optional): string
  The client identifier as a string.
• currentEngagementCount(optional): integer(int32)
  The number of engagements the agent is currently engaged in.
• groupId(optional): integer(int32)
  The group identifier.
• maximumSessionCount(optional): integer(int32)
  The maximum session count for the agent.
• mediaList(optional): array mediaList
  The media list.
• name: string
  The agent name.
• numberOfEngagementsInWrapUp(optional): integer(int32)
  The number of engagements the agent has in wrap up mode.
• profileId(optional): integer(int64)
  The profile identifier.
• profileIdString(optional): string
  The profile identifier as a string.
• status: string
  Allowed Values: [ "NONE", "AVAILABLE", "UNAVAILABLE" ]

  The agent status.
• subTypeId(optional): integer(int32)
  The sub-type identifier.

{
    "required":[
        "name",
        "status"
    ],
    "properties":{
        "maximumSessionCount":{
            "type":"integer",
            "format":"int32",
            "description":"The maximum session count for the agent."
        },
        "currentEngagementCount":{
            "type":"integer",
            "format":"int32",
            "description":"The number of engagements the agent is currently engaged in."
        },
        "availableSessionCount":{
            "type":"integer",
            "format":"int32",
            "description":"The available session count of the agent."
        },
        "numberOfEngagementsInWrapUp":{
            "type":"integer",
            "format":"int32",
            "description":"The number of engagements the agent has in wrap up mode."
        },
        "clientId":{
            "type":"integer",
            "format":"int64",
            "description":"The client identifier."
        },
        "clientIdString":{
            "type":"string",
            "description":"The client identifier as a string."
        },
        "name":{
            "type":"string",
            "description":"The agent name."
        },
        "accountId":{
            "type":"integer",
            "format":"int64",
            "description":"The account identifier."
        },
        "accountIdString":{
            "type":"string",
            "description":"The account identifier as a string."
        },
        "profileId":{
            "type":"integer",
            "format":"int64",
            "description":"The profile identifier."
        },
        "profileIdString":{
            "type":"string",
            "description":"The profile identifier as a string."
        },
        "groupId":{
            "type":"integer",
            "format":"int32",
            "description":"The group identifier."
        },
        "status":{
            "type":"string",
            "description":"The agent status.",
            "enum":[
                "NONE",
                "AVAILABLE",
                "UNAVAILABLE"
            ]
        },
        "subTypeId":{
            "type":"integer",
            "format":"int32",
            "description":"The sub-type identifier."
        },
        "mediaList":{
            "type":"array",
            "description":"The media list.",
            "items":{
                "$ref":"#/definitions/com.rightnow.chat.rest.common.model.types.v1.MediaInfo"
            }
        }
    }
}

Nested Schema : mediaList

Type: array

The media list.

Show Source

• Array of: object com.rightnow.chat.rest.common.model.types.v1.MediaInfo

{
    "type":"array",
    "description":"The media list.",
    "items":{
        "$ref":"#/definitions/com.rightnow.chat.rest.common.model.types.v1.MediaInfo"
    }
}

Nested Schema : com.rightnow.chat.rest.common.model.types.v1.MediaInfo

Type: object

Show Source

• autoInitiate(optional): boolean
  The indicator that the media info should be auto initiated. Default value is FALSE.
• environmentErrorList(optional): array environmentErrorList
  The media environment error list.
• type: string
  Allowed Values: [ "NONE", "CHAT", "COBROWSE", "VIDEO" ]

  The media type.

{
    "required":[
        "type"
    ],
    "properties":{
        "type":{
            "type":"string",
            "description":"The media type.",
            "enum":[
                "NONE",
                "CHAT",
                "COBROWSE",
                "VIDEO"
            ]
        },
        "environmentErrorList":{
            "type":"array",
            "description":"The media environment error list.",
            "items":{
                "type":"string"
            }
        },
        "autoInitiate":{
            "type":"boolean",
            "description":"The indicator that the media info should be auto initiated.  Default value is FALSE."
        }
    }
}

Nested Schema : environmentErrorList

Type: array

The media environment error list.

Show Source

• Array of: string

{
    "type":"array",
    "description":"The media environment error list.",
    "items":{
        "type":"string"
    }
}

Nested Schema : com.rightnow.chat.rest.agent_api.model.types.v1.QueueInformation

Type: object

Show Source

• availableAgentSessions(optional): integer(int64)
  The number of available agent sessions.
• availableAgentSessionsString(optional): string
  The number of available agent sessions as a string.
• engagementsInQueue(optional): integer(int32)
  The number of engagements currently in the queue.
• expectedWaitSeconds(optional): integer(int64)
  The expected wait time in the queue, in seconds. The value is zero or greater than zero. The value is -1 if there's inadequate information.
• expectedWaitSecondsString(optional): string
  The expected wait time in the queue as a string.
• profileIdsList(optional): array profileIdsList
  The list of profile Ids associated with the queue.
• profileIdsStringList(optional): array profileIdsStringList
  The list of profile Ids as a String associated with the queue.
• queueId: integer(int64)
  The queue identifier.
• queueIdString(optional): string
  The queue identifier as a string.
• totalAgentsRequestingNewEngagement(optional): integer(int32)
  Total number of agents who are available and have capacity.
• totalAvailableAgents(optional): integer(int32)
  Total number of agents whose status is available.
• totalUnavailableAgents(optional): integer(int32)
  Total number of agents whose status is unavailable.

{
    "required":[
        "queueId"
    ],
    "properties":{
        "queueId":{
            "type":"integer",
            "format":"int64",
            "description":"The queue identifier."
        },
        "queueIdString":{
            "type":"string",
            "description":"The queue identifier as a string."
        },
        "availableAgentSessions":{
            "type":"integer",
            "format":"int64",
            "description":"The number of available agent sessions."
        },
        "availableAgentSessionsString":{
            "type":"string",
            "description":"The number of available agent sessions as a string."
        },
        "totalAvailableAgents":{
            "type":"integer",
            "format":"int32",
            "description":"Total number of agents whose status is available."
        },
        "totalUnavailableAgents":{
            "type":"integer",
            "format":"int32",
            "description":"Total number of agents whose status is unavailable."
        },
        "totalAgentsRequestingNewEngagement":{
            "type":"integer",
            "format":"int32",
            "description":"Total number of agents who are available and have capacity."
        },
        "expectedWaitSeconds":{
            "type":"integer",
            "format":"int64",
            "description":"The expected wait time in the queue, in seconds. The value is zero or greater than zero. The value is -1 if there's inadequate information."
        },
        "expectedWaitSecondsString":{
            "type":"string",
            "description":"The expected wait time in the queue as a string."
        },
        "engagementsInQueue":{
            "type":"integer",
            "format":"int32",
            "description":"The number of engagements currently in the queue."
        },
        "profileIdsList":{
            "type":"array",
            "description":"The list of profile Ids associated with the queue.",
            "items":{
                "type":"integer",
                "format":"int64"
            }
        },
        "profileIdsStringList":{
            "type":"array",
            "description":"The list of profile Ids as a String associated with the queue.",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : profileIdsList

Type: array

The list of profile Ids associated with the queue.

Show Source

• Array of: integer(int64)

{
    "type":"array",
    "description":"The list of profile Ids associated with the queue.",
    "items":{
        "type":"integer",
        "format":"int64"
    }
}

Nested Schema : profileIdsStringList

Type: array

The list of profile Ids as a String associated with the queue.

Show Source

• Array of: string

{
    "type":"array",
    "description":"The list of profile Ids as a String associated with the queue.",
    "items":{
        "type":"string"
    }
}

400 Response

The validation of the request object failed.

Body ()

Root Schema : schema

Type: object

403 Response

The agent session identifier is unknown.

Body ()

Root Schema : schema

Type: object

404 Response

The resource was not found.

Body ()

Root Schema : schema

Type: object

500 Response

An error occurred in the chat server while processing the request.

Body ()

Root Schema : schema

Type: object

Back to Top

Examples

The following example shows how to have an agent retrieve agent and queue information.

cURL Command Example

curl -X POST https://chat_rest_server_domain.com/engagement/api/agent/day001_221100_sql_001h/v1/retrieveAgentsAndQueues?pool=297:1 -H 'Content-Type: application/json; charset=UTF-8' -H 'X-JSESSIONID: node01h8m13tljpm7ns8nayp0pid91' -d ' -H 'X-AID: 12' {"timeCreated" :160444022000, "sequenceNumber" : 10,  "includeAgentInformation": true,  "id": 14, "type": "GROUP", "includeQueueInformation": true, "includeQueueStatistics": true}'

Request Body Example

The following shows an example of the request body in JSON format.

{
  "includeAgentInformation": true,	
  "id": 14,
  "type": "GROUP",
  "includeQueueInformation": true,
  "includeQueueStatistics": true	
}

Response Header Example

The following shows an example of the response header.

Status: 200 OK
Content-Type: application/json;charset=utf-8

Response Body Example

The following shows an example of the response body in JSON format.

{
  "agents": [],
  "clientSendTime": 160444022000,
  "serviceStartTime": 1604440224927,
  "serviceFinishTime": 1604440224932,
  "sessionId": "node0f0ctgqi8tbj59nnw9r9wx0ee0",
  "clientId": 47,
  "clientIdString": "47",
  "sequenceNumber": 0,
  "sequenceNumberString": "0",
  "queues": [
    {
    "queueId": 1,
    "queueIdString": "1",
    "availableAgentSessions": 0,
    "availableAgentSessionsString": "0",
    "totalAvailableAgents": 0,
    "totalUnavailableAgents": 1,
    "totalAgentsRequestingNewEngagement": 0,
    "expectedWaitSeconds": 0,
    "expectedWaitSecondsString": "0",
    "engagementsInQueue": 0,
    "profileIdsList": [
      14
    ],
    "profileIdsStringList": [
      "14"
    ]
    }
  ]
}

Back to Top