Getting started with Looker

Best Practices

Documentation

Community

Training

Certification

Articles in this section

Using Lookerbot for Slack

Avatar
Lindsey Meyer
  • Updated
Follow

This article is an overview of how to use Lookerbot, one of three integrations that Looker provides for sharing Looker data in Slack. In addition to Lookerbot, you can deliver Looker content or create alert notifications to Slack using the Slack Attachment (API Token) integration. You can also deliver Looker content or create alert notifications to Slack using Looker's Slack integration.

Lookerbot for Slack integrates with Looker so that you can query all your data directly from Slack, allowing everyone in your company to share data easily and answer data-driven questions instantly. Lookerbot can automatically expand Looker URLs. You can also create custom commands to run saved queries. Before you can get started using Lookerbot, it must be set up following the technical setup instructions in Looker's open source GitHub repository.

In February 2021, Slack deprecated some API endpoints that affect how Lookerbot interacts with data actions. Please pull the latest updates from Looker's Lookerbot GitHub repo. Your package.json file should indicate a Looker version of 0.0.16 or later.

Expanding Looker URLs

If Lookerbot is added to a channel and the LOOKER_SLACKBOT_EXPAND_URLS variable is set to true, Lookerbot will automatically expand shared URLs and Look URLs. If the Explore has an associated visualization, Lookerbot will show an image of that visualization. If the Explore is a table, Lookerbot will show the data as text.

For example, these two URLs will expand like so:

https://learnbeta.looker.com/x/3Hq6Q2j # share URL
https://learnbeta.looker.com/looks/263 # Look URL

The ability to expand Looker URLS is not available in Slack direct messages, because of the distinction made between private/public channels and direct messages in the legacy unfurling API capabilities used in Lookerbot.

Lookerbot will need to be invited to any public or private channels to be able to post in them or send data to them using the Scheduler. If you do not see that Lookerbot is available in a channel, please make sure it has been invited (on your channel settings, select Add people to #channel_name, find Lookerbot the same way you find individual users, and select it). Or, for bots using legacy tokens, make sure that the Looker application has been added to that channel (select Add an App for your channel's settings and find the Looker app).

Slack Commands

Lookerbot also allows you to create custom commands for running saved queries. This allows you to easily run common queries and answer frequent questions!

Slash commands are not required to interact with Lookerbot. To use all of Lookerbot's functions, you can also message the bot directly or mention it in a Slack channel in which Lookerbot is present: @lookerbot help

If the Slack integration if enabled for your Slack workspace, you cannot use /looker slash commands with the Lookerbot. In place of @looker or /looker, use @lookerbot or /lookerbot.

Creating Commands

  1. Go to https://api.slack.com/apps.
  2. Choose Slash Commands and click Create New Command.
  3. Create a command to use for Lookerbot. For example, Looker uses /lookerbot for our internal Slack.
  4. Set the URL to wherever you have your bot server hosted (if you used Heroku to set up the server, this will be the unique app name that you chose). The path to the slash command endpoint is /slack/receive, so if your server is at https://example.com, the URL would be https://example.com/slack/receive.
  5. Under Settings, choose Install App again; then select Reinstall App and authenticate.
  6. Under Basic Information, grab the verification token. You'll use this to set the SLACK_SLASH_COMMAND_TOKEN environment variable.

Creating Custom Commands

To create custom commands, make sure to specify a custom command folder, using the LOOKER_CUSTOM_COMMAND_SPACE_ID variable during setup. Any dashboard saved in this folder will be available to use as a command.

To create a new command:

  1. Create a dashboard with a single element in the Lookerbot command folder. Currently, only dashboards with single elements can be used with Lookerbot.
  2. Give the dashboard a discoverable name. The name of the dashboard will be the name of the command. We recommend using only a few lowercase letters for ease of use.
  3. Add dashboard filters to pass filter values to the command if necessary.
  4. Optionally, add a description to the dashboard. This will appear next to the command when a user types help.

If you would like to split up commands into logical groups, you can create subfolders within the Lookerbot command folder. This will group the commands in the help list.

Using Commands

You use a command by typing the name of the command, and then any filter values you want to add. Filters are optional, and the query will run without that filter if no values are specified. For example, we can run the customer map in command, filtered for New York, like so:

There are three ways to use commands:

If you are also using the Slack (Beta) action, you cannot use /looker slash commands. In place of @looker or /looker, use @lookerbot or /lookerbot.
  1. @mention Lookerbot. This can be done in any channel in which Lookerbot is present.
  2. Use the slash command. This can be done if the slash command has been configured during setup.
  3. Direct message Lookerbot. If you send a message directly to Lookerbot, you don't need to prepend the command with anything.

Data Formats

Commands will return data in different ways depending on the visualization type of the underlying Look. There are three possible return formats:

  1. Text: If the underlying Look is a table, the data will return as text:
  2. Single Value Text: If the underlying Look is a single value visualization, the data will return as a text value:
  3. Image: If the underlying Look is a chart, the data will return as an image of the visualization:

Hiding Commands and Subfolders

If you have some commands you do not want to appear in the help menu but that you still want to use with Lookerbot, you can hide either the command or the entire subfolder in which the command is saved.

Hide a command or subfolder by starting the name with [Hidden]. For example, this subfolder and this command will not be visible in the help menu:

Lookerbot's help menu lists the available commands as well as a description of the dashboard that gets returned:

  1. In Looker, navigate to the dashboard.
  2. Click Edit, and then click the Settings icon.
  3. In the Description field, enter the description you want to appear in the Lookerbot help menu.
  4. Click Save.

Updating the Lookerbot App

The easiest way to update the Lookerbot app is with the following steps:

  1. Install the Heroku Toolbelt.
  2. In the terminal, log in to the Heroku tools: 
    heroku login
  3. Clone your Heroku app locally: 
    heroku git:clone -a your-heroku-app-name
  4. Move into the newly cloned app: 
    cd your-heroku-app-name
  5. Add the looker-slackbot Git remote: 
    git remote add origin https://github.com/looker/looker-slackbot.git
  6. Pull the new changes from GitHub to your local repository: 
    git pull origin master
  7. Push and deploy the new changes to Heroku: 
    git push heroku master

Related articles