Queues

Queues are public entry points. Operators can be assigned to queues based on their department or area of expertise. A queue is online to receive chats from customers if at least one operator assigned to the queue is available for chat.

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.

Queue Instance Resource

An Queue instance resource represents a single queue connected to the user account provided during authentication.

Resource URI

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

Resource Properties

A Queue resource is represented by the following properties:

Property Description
id Unique integer identifier for a queue.
type String that is always "queue"
name String of up to 40 characters that uniquely identifies the queue. The name of a queue forms the node identifier of a queue's JID (Jabber ID) and thus must conform to the XMPP standard for node identifier and be lowercase. That is, queue names cannot contain spaces or any of the characters "&'/:<>@\. Because both queues and users have JIDs, a queue cannot have the same name as a user and vice versa.
enabled UNUSED
transcripts Boolean indicating if chat transcripts are saved for this queue. When created, a queue defaults to transcripts = null.
email String containing an e-mail address that is forwarded to if someone sends an e-mail to a queue's JID. Forwarding functionality not yet implemented.
avatar String containing the URL for a queue's avatar. Queue avatars give a graphical identity to a queue. If string is empty, then a default avatar will be used for the queue.
show String reflecting the current availability of the queue for chat. Possible values are "chat", "available", "dnd", "away", "xa", "unavailable". The Presence API also provides this information.
status String containing a natural-language description of a queue's availability.

HTTP GET

Allows you to retrieve a queue's information.

Response

Returns a JSON response containing a representation of a queue, including the properties above.

Example

GET /2011-12-03/queues/8724

{
  "id": 8724,
  "type": "queue",
  "name": "example_queue",
  "enabled": true,
  "transcripts":null,
  "email": "support@libraryh3lp.com",
  "avatar": "",
  "show": "unavailable",
  "status": ""
}

HTTP POST

Not supported.

HTTP PUT

Allows you to modify the properties of an existing queue.

PUT data

Requests include, as JSON PUT data, any of the following properties. If a property is omitted, then it is assumed that it should be set to null.

Property Description
parentId Integer. The folder ID that should contain the queue. A parentId of 0 places the queue at the top level of your account folder hierarchy.
transcripts Boolean indicating if chat transcripts are saved for this queue.
name String of up to 40 characters that uniquely identifies the queue. The name of a queue forms the node identifier of a queue's JID and thus must conform to the XMPP standard for node identifier and be lowercase. That is, queue names cannot contain spaces or any of the characters "&'/:<>@\. Because both queues and users have JIDs, a queue cannot have the same name as a user and vice versa.
email String containing an e-mail address that is forwarded to if someone sends an e-mail to a queue's JID.
avatar String containing the URL for a queue's avatar. Queue avatars give a graphical identity to a queue. If string is empty, then a default avatar will be used for the queue.

Response

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

Example

PUT /2011-12-03/queues/9347
{
  "parentId": 0,
  "name": "my-renamed-queue"
}

[
  {
    "id": 9347,
    "type": "queue",
    "name": "my-renamed-queue",
    "enabled": true,
    "transcripts": true,
    "email": "",
    "avatar": "",
    "show": "unavailable",
    "status": ""
  }
]

HTTP DELETE

Allows you to delete 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/9347

{
  "success": true
}

Queues List Resource

The Queues list resource represents the set of Queues managed by the user whose credentials were used to make the API request.

Resource URI

/2011-12-03/queues

HTTP GET

Returns all the queues managed by the user whose credentials were used to make the API request.

Response

Returns a JSON response containing a list of Queue resources.

Example - list all queues

GET /2011-12-03/queues

[
  {
    "id": 8724
    "type": "queue",
    "name": "example_queue",
    "enabled": true,
    "transcripts": null,
    "email": "support@libraryh3lp.com",
    "avatar": "",
    "show": "unavailable",
    "status": ""
  }, {
    "id": 9347
    "type": "queue",
    "name": "my-renamed-queue",
    "enabled": true,
    "transcripts": true,
    "email": "",
    "avatar": "",
    "show": "unavailable",
    "status": ""
  },
]

HTTP POST

Allows you to create a new queue.

Required POST data

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

Property Description
name String of up to 40 characters that uniquely identifies the queue. The name of a queue forms the node identifier of a queue's JID and thus must conform to the XMPP standard for node identifier and be lowercase. That is, queue names cannot contain spaces or any of the characters "&'/:<>@\. Because both queues and users have JIDs, a queue cannot have the same name as a user and vice versa.
type Always "queue".

Response

If successful, returns a JSON response containing the resource representation of the newly created queue. If unsuccessful, 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 creation of a queue

POST /2011-12-03/queues
{
  "name": "my-new-queue"
  "type": "queue"
}

[
  {
    "id": 9347,
    "type": "queue",
    "name": "my-new-queue",
    "enabled": true,
    "transcripts": null,
    "email": "",
    "avatar": "",
    "show": "unavailable",
    "status": ""
  }
]

Example - failure to create a queue

POST /2011-12-03/queues
name=my-new-queue&type=queue

{
  "success": null,
  "message": "Sorry, a queue with that name already exists. Please choose another name."
}

HTTP PUT

Not supported.

HTTP DELETE

Not supported.