Widgets are what guests use to chat with operators on your website. They are highly customizable and whitelabel. The Widgets resource lets you create and manage as many widgets as you'd like.
LibraryH3lp supports cookie-based authentication. To learn more, you can read the details on authentication.
Requests are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
A Widget instance resource represents a single widget managed by the user account provided during authentication.
/2011-12-03/widgets/{WidgetId}
A Widget resource is represented by the following properties:
| Property | Description |
|---|---|
| id | Unique integer identifier for a widget. |
| name | A descriptive string for a widget. |
| shared | A Boolean indicated whether a widget is shared among all LibraryH3lp users (not just users under your top-level admin account). Default is null. |
| background-color | The CSS color for the background of your widget. Default is #FFFFFF. |
| border | The CSS border around your widget. Note this is the shorthand property. Default is 2px inset black. |
| buttons-color | The CSS color for text in the buttons div of the widget. Default is #0000FF. |
| height | The height of the widget. Default is 200px. |
| identity | The typing identity of the operator as seen by the guest. Default is operator. |
| librarian-color | The CSS color of the identity for the operator and associated time stamps. Default is #0000FF. The use of the word "librarian" is a throwback to our company's library roots. |
| more-css | A free form string that allows you to add addtional CSS values to a widget's CSS. For example, you can hide widget icons. Default is an empty string. |
| patron-color | The CSS color of the identity for the guest and associated time stamps. Default is #FF0000. The use of the word "patron" is a throwback to our company's library roots. |
| recv-background | The CSS color for the background for the chat history within your widget. Default is #FFFFFF. |
| recv-border | The CSS border around the chat history. Note this is the shorthand property. Default is 2px solid #C0C0C0. |
| recv-color | The CSS color for the chat text in the chat history. Default is #000000. |
| send-background | The CSS color for the background for the entry area within your widget. Default is #FFFFFF. |
| send-border | The CSS border around the entry area. Note this is the shorthand property. Default is 2px solid #C0C0C0. |
| send-color | The CSS color for the text in the entry area. Default is #000000. |
| sounds | A Boolean indicating whether sounds are enabled by default. |
| theme | The icon theme to use for the widget. Default is simpletext. |
| title | The title text for the widget. Default is an empty string. |
| title-color | The CSS color for the title text. Default is #444444. |
| title-size | The font size for the title text. Default is 16px. |
| width | The width of the widget. Default is 320px. |
Returns a JSON response containing a representation of a widget, including the properties above.
GET /2011-12-03/widgets/411
[
{
"id": 411,
"name": "example widget",
"shared": null,
"background-color": "#FFFFFF",
"border": "2px inset black",
"buttons-color": "#0000FF"
"height": "200px"
"identity": "operator"
"librarian-color": "#0000FF"
"more-css": ""
"patron-color": "#FF0000"
"recv-background": "#FFFFFF"
"recv-border": "2px solid #C0C0C0"
"recv-color": "#000000"
"send-background": "#FFFFFF"
"send-border": "2px solid #C0C0C0"
"send-color": "#000000"
"sounds": true
"theme": "simpletext"
"title": "Example Widget"
"title-color": "#444444"
"title-size": "16px"
"width": "320px"
}
]
Not supported.
Allows you to modify the properties of an existing widget.
You must include, as JSON PUT data, all of the properties of a widget excluding id.
Always returns a JSON response containing the representation of the widget resource.
PUT /2011-12-03/widgets/411
{
"name": "a renamed widget",
"shared": null,
"background-color": "#FFFFFF",
"border": "2px inset black",
"buttons-color": "#0000FF"
"height": "200px"
"identity": "operator"
"librarian-color": "#0000FF"
"more-css": ""
"patron-color": "#FF0000"
"recv-background": "#FFFFFF"
"recv-border": "2px solid #C0C0C0"
"recv-color": "#000000"
"send-background": "#FFFFFF"
"send-border": "2px solid #C0C0C0"
"send-color": "#000000"
"sounds": true
"theme": "simpletext"
"title": "A New Widget"
"title-color": "#444444"
"title-size": "16px"
"width": "320px"
}
[
{
"id": 411,
"name": "a renamed widget",
"shared": null,
"background-color": "#FFFFFF",
"border": "2px inset black",
"buttons-color": "#0000FF"
"height": "200px"
"identity": "operator"
"librarian-color": "#0000FF"
"more-css": ""
"patron-color": "#FF0000"
"recv-background": "#FFFFFF"
"recv-border": "2px solid #C0C0C0"
"recv-color": "#000000"
"send-background": "#FFFFFF"
"send-border": "2px solid #C0C0C0"
"send-color": "#000000"
"sounds": true
"theme": "simpletext"
"title": "A New Widget"
"title-color": "#444444"
"title-size": "16px"
"width": "320px"
}
]
Removes a widget.
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. |
DELETE /2011-12-03/widgets/411
{
"success": true
}
The Widgets list resource represents the set of Widgets managed by the user whose credentials were used to make the API request.
/2011-12-03/widgets
Returns all the widgets managed by the user whose credentials were used to make the API request.
Returns a JSON response containing a list of Widget resources.
GET /2011-12-03/widgets
[
{
"id": 411,
"name": "example widget",
"shared": null,
"background-color": "#FFFFFF",
"border": "2px inset black",
"buttons-color": "#0000FF"
"height": "200px"
"identity": "operator"
"librarian-color": "#0000FF"
"more-css": ""
"patron-color": "#FF0000"
"recv-background": "#FFFFFF"
"recv-border": "2px solid #C0C0C0"
"recv-color": "#000000"
"send-background": "#FFFFFF"
"send-border": "2px solid #C0C0C0"
"send-color": "#000000"
"sounds": true
"theme": "simpletext"
"title": "Example Widget"
"title-color": "#444444"
"title-size": "16px"
"width": "320px"
}
]
Allows you to add a new widget.
You must include, as JSON POST data, all of the properties of a widget except id as JSON.
If successful, returns a JSON response containing the resource representation of the newly created widget. 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. |
POST /2011-12-03/widgets
{
"name": "a new widget",
"shared": null,
"background-color": "#FFFFFF",
"border": "2px inset black",
"buttons-color": "#0000FF"
"height": "200px"
"identity": "operator"
"librarian-color": "#0000FF"
"more-css": ""
"patron-color": "#FF0000"
"recv-background": "#FFFFFF"
"recv-border": "2px solid #C0C0C0"
"recv-color": "#000000"
"send-background": "#FFFFFF"
"send-border": "2px solid #C0C0C0"
"send-color": "#000000"
"sounds": true
"theme": "simpletext"
"title": "A New Widget"
"title-color": "#444444"
"title-size": "16px"
"width": "320px"
}
[
{
"id": 4158,
"name": "a new widget",
"shared": null,
"background-color": "#FFFFFF",
"border": "2px inset black",
"buttons-color": "#0000FF"
"height": "200px"
"identity": "operator"
"librarian-color": "#0000FF"
"more-css": ""
"patron-color": "#FF0000"
"recv-background": "#FFFFFF"
"recv-border": "2px solid #C0C0C0"
"recv-color": "#000000"
"send-background": "#FFFFFF"
"send-border": "2px solid #C0C0C0"
"send-color": "#000000"
"sounds": true
"theme": "simpletext"
"title": "A New Widget"
"title-color": "#444444"
"title-size": "16px"
"width": "320px"
}
]
Not supported.
Not supported.