Operators

When a user is assigned to staff a queue, he/she is then said to be an operator on that queue.

Authentication

LibraryH3lp supports cookie-based authentication. To learn more, you can read the details on authentication.

HTTP and HTTPS

Requests are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Operator Instance Resource

An operator instance resource represents a single operator assigned to a given queue and managed by the user account provided during authentication.

Resource URI

/2011-12-03/queues/{QueueId}/operators/{UserId}

Resource Properties

An Operator resource is represented by the following properties:

Property Description
queueId The integer identifier for the queue to which a user is assigned as an operator.
queue String of up to 60 characters which serves as the queue's descriptive name and the node for a queue's JID (Jabber ID).
queueShow String reflecting the current availability of the queue to which the operator is assigned for chat. Possible values are "chat", "available", "dnd", "away", "xa", "unavailable". The Presence API also provides this information.
userId The integer identifier for the user.
user String of up to 40 characters which serves as the user's username and the node for a user's JID.
userShow String reflecting the current availability of the user. Possible values are "chat", "available", "dnd", "away", "xa", "unavailable". The Presence API also provides this information.
enabled Boolean. If true, the operator's availability contributes to the collective availability of the queue and is able to receiving incoming chats on the queue. If null, the operator is suspended from queue participation. When created, an operator defaults to enabled = true.

HTTP GET

Not supported.

HTTP POST

Not supported.

HTTP PUT

Allows you to modify the properties of an operator.

Optional PUT data

You may include, as JSON PUT data, any of the following properties.

Properties Description
enabled Boolean. If true, the operator's availability contributes to the collective availability of the queue and is able to receiving incoming chats on the queue. If null, the operator is suspended from queue participation.

Response

Always returns a representation of the operator resource. If a parameter contains an illegal value, the illegal value is ignored and the original value retained and returned in the representation.

Example - suspend an operator

PUT /2011-12-03/queues/8451/operators/34814
{
  "enabled": null
}

[
  {
    "queueId": 8451
    "queue": "example-queue",
    "queueShow": "unavailable",
    "userId": 34814,
    "user": "example-user",
    "userShow": "unavailable",
    "enabled": null
  }
]

HTTP DELETE

Allows you to unassign an operator from a queue.

Response

Returns a JSON response with the following properties:

Property Description
success Boolean indicating if the request was successful.
message Optional. If success is null, message is a string describing the reason for the failed request.

Example

DELETE /2011-12-03/queues/8451/operators/34814

{
  "success": true
}

Operators List Resource

The Operators list resource represents the set of Operators assigned to a given queue managed by the user whose credentials were used to make the API request.

Resource URI

/2011-12-03/queues/{QueueId}/operators

HTTP GET

Returns all the operators managed or created by the user whose credentials were used to make the API request.

Response

Returns a JSON response containing a list of Operator resources.

Example - list all operators

GET /2011-12-03/queues/{QueueId}/operators

[
  {
    "queueId": 8451
    "queue": "example-queue",
    "queueShow": "unavailable",
    "userId": 30826
    "user": "test-user",
    "userShow": "unavailable",
    "enabled": true
  }, {
    "queueId": 8451
    "queue": "example-queue",
    "queueShow": "unavailable",
    "userId": 35158
    "user": "my-user",
    "userShow": "unavailable",
    "enabled": null,
  },
]

HTTP POST

Allows you to assign a user to a queue as an operator.

POST data

You must include, as JSON POST data, the following properties.

Property Description
userId The id for the user whom you wish to assign as an operator on the given queue.

Response

Returns a JSON response with the following properties:

Property Description
success Boolean indicating if the request was successful.
message Optional. If success is null, message is a string describing the reason for the failed request.

Example - successful assignment of an operator to a queue

POST /2011-12-03/queues/8451/operators
{
  "userId": 34814
}

{
  "success": true
}

HTTP PUT

Not supported.

HTTP DELETE

Not supported.