Widget URLs

Widget URLs take patron to your chat service with a single click and are also very handy for testing. And if your link is likely to be visited by a patron on a smart device (e.g. you tweeted it), then users on mobile devices will automatically receive the mobile-optimized widget.

Mobile widget attached to a queue:

    https://us.libraryh3lp.com/mobile/queue-name@chat.libraryh3lp.com

Regular widget attached to a queue:

    https://us.libraryh3lp.com/chat/queue-name@chat.libraryh3lp.com

Mobile widget attached to a user:

    https://us.libraryh3lp.com/mobile/username@libraryh3lp.com

Regular widget attached to a user:

    https://us.libraryh3lp.com/chat/username@libraryh3lp.com

Note: chats for specific users are treated as private conversations and are not logged, so they will not show up in Activity or Reports. They also can't be transferred. To provide logging and transfer capabilities for an individual, create a queue and assign only that one user to it.

Customizing your widget URL

The easiest way to customize your widget is to use the Widgets tab in the admin site. You can add a title, change colors, customize your identity, provide custom CSS, turn sound on by default, etc... Then, to use all those customizations, use the skin widget argument and provide your widget's ID number:

https://us.libraryh3lp.com/chat/queue-name@chat.libraryh3lp.com?skin=18907

Using the skin argument is the best way to send someone a widget URL over email, SMS, or Twitter since it results in the shortest URL.

Using specific widget arguments

You can change some widget settings as arguments in the widget URL. In the following example, a widget title is provided, and sound is turned on by default:

https://us.libraryh3lp.com/chat/queue-name@chat.libraryh3lp.com?skin=0&title=Ask+Us&sounds=true

Here is a complete list of arguments you can use in the widget URL include:

  • identity: identity of librarian as seen by patrons in the widget
  • theme: presence icon theme (Email us if you would like to contribute a new or localized theme.)
  • css: Accepts a path to a CSS file you provide on your own server. Default CSS is here.
  • title: Sets the widget title. Create spaces between words by using +. Example: Ask+Us.
  • sounds: Sets the default set of widget alert sound. If it is not specified, sound is off. Turn sound on by default by setting sounds to true.
  • skin: Refers to a widget ID from within the admin site.
  • language: Override the user's language browser setting and force the widget to display in the language of your choice. Requires that we have a localization for the specified language.
  • profile: Show chat operators the profile (metadata) for the stated queue, overriding the default (the queue to which the chat was actually sent).

Examples

To add a title and pick a new theme:

https://us.libraryh3lp.com/chat/queue-name@chat.libraryh3lp.com?title=My+Chat+Widget&theme=gota

CSS Hooks

The keyword to supply your own CSS is "css" and the argument should be a URL pointing to your file. The default CSS is:

https://us.libraryh3lp.com/css/chat.css

Your customizations will be added to the default, so that you have a chance to override what's there without having to reinvent the wheel. An example:

https://us.libraryh3lp.com/chat/queue-name@chat.libraryh3lp.com?css=https://my.library.edu/chat/custom.css

You should only provide the changes you're making from the default.

Title and CSS

https://us.libraryh3lp.com/chat/queue-name@chat.libraryh3lp.com?title=My+Chat+Widget&css=https://my.library.edu/chat/custom.css

Presence API

One last item of note. If you use the Presence API, you'll notice that it supplies an "openChat" method for convenience, so that you don't have to supply the raw chat URL. If you want to use the customization features with this method, just pass the options as part of the argument, as in:

libraryh3lp.openChat({title: 'My Chat Widget', theme: 'gota'});

The

 libraryh3lp.openChat()
method also works to customize follow-me widgets.


Document URL: https://docs.us.libraryh3lp.com/customizing-widgets-by-hand