Support Widget Advanced Usage

The Groove support widget is designed to be easily embedded into your website or application. For most uses, you can simply follow the instructions for installing your widget, and everything will work as intended.

For more advanced usage, you can modify the widget's embed code to change the behavior of the widget. This is a living document, and we will update it as we open up new functionality on the widget.

Command API

The groove object in your embed code manages a command queue that sends commands to the widget api. Using the groove.widget() method, you are able to communicate with the widget without actually worrying about it being fully loaded on the page. Normally, you will see this used to set up the widget id like so:

The widget() method takes the command as the first argument, and each additional argument is provided individually.

Here is a list of commands currently available to the command queue:

  • groove.widget('setWidgetId', 'WIDGET ID')
    • Sets the initial widget id. This is required for the widget to load.
  • groove.widget('setAutoload', false) (default: true)
    • Allows you to disable autoloading of the widget. This is useful for times when you need to manually load or unload the widget. For example, you may use Turbolinks in a Rails application and you only want to load the widget on certain pages. (If this is the case, check out our separate article on using the widget with Turbolinks).
  • groove.widget('load')
    • Once you disable autoloading, this command will load the widget when you are ready.
  • groove.widget('unload')
    • If you need to unload the widget, this command will reset everything back to the pre-autoloaded state.
  • groove.widget('open')
    • Programmatically opens the widget, just as if the user clicked on the widget button at the bottom of the screen.
  • groove.widget('close')
    • Programmatically closes the widget, just as if the user clicked on the close button inside the widget itself.
  • groove.widget('setCustomer', {custom: 'attributes'...})

Before the widget is loaded, commands will be queued up as you add them. During initialization, the widget will process all of the commands in the queue first, and then it will immediately process any additional widget() calls.

Here is an example of using the command api to control loading and opening of the widget: