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. Yourpackage.json
file should indicate a Looker version of0.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
- Go to https://api.slack.com/apps.
- Choose Slash Commands and click Create New Command.
- Create a command to use for Lookerbot. For example, Looker uses
/lookerbot
for our internal Slack. - 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. - Under Settings, choose Install App again; then select Reinstall App and authenticate.
- 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:
- Create a dashboard with a single element in the Lookerbot command folder. Currently, only dashboards with single elements can be used with Lookerbot.
- 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.
- Add dashboard filters to pass filter values to the command if necessary.
- 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
.
- @mention Lookerbot. This can be done in any channel in which Lookerbot is present.
- Use the slash command. This can be done if the slash command has been configured during setup.
- 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:
- Text: If the underlying Look is a table, the data will return as text:
- Single Value Text: If the underlying Look is a single value visualization, the data will return as a text value:
- 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:
- In Looker, navigate to the dashboard.
- Click Edit, and then click the Settings icon.
- In the Description field, enter the description you want to appear in the Lookerbot help menu.
- Click Save.
Updating the Lookerbot App
The easiest way to update the Lookerbot app is with the following steps:
- Install the Heroku Toolbelt.
- In the terminal, log in to the Heroku tools:
heroku login
- Clone your Heroku app locally:
heroku git:clone -a your-heroku-app-name
- Move into the newly cloned app:
cd your-heroku-app-name
- Add the looker-slackbot Git remote:
git remote add origin https://github.com/looker/looker-slackbot.git
- Pull the new changes from GitHub to your local repository:
git pull origin master
- Push and deploy the new changes to Heroku:
git push heroku master