Slack Tutorial - Slash Commands

This tutorial demonstrates using Cloud Functions to implement a Slack Slash Command that searches the Google Knowledge Graph API.

Objectives

• Create a Slash Command in Slack.
• Write and deploy an HTTP Cloud Function.
• Search the Google Knowledge Graph API using the Slash Command.

Costs

This tutorial uses billable components of Cloud Platform, including:

• Google Cloud Functions

Use the Pricing Calculator to generate a cost estimate based on your projected usage.

Before you begin

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. In the Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to the project selector page

3. Verifica che la fatturazione sia attivata per il tuo progetto.

   scopri come attivare la fatturazione

4. Enable the Cloud Functions and Google Knowledge Graph Search APIs.

   Enable the APIs

5. Update gcloud components:

   gcloud components update

6. Prepare your development environment.

   Node.js

   Go to the Node.js setup guide

   Python

   Go to the Python setup guide

   Go

   Go to the Go setup guide

Visualizing the flow of data

The flow of data in the Slack Slash Command tutorial application involves several steps:

1. The user executes the /kg <search_query> Slash Command in a Slack channel.
2. Slack sends the command payload to the Cloud Function's trigger endpoint.
3. The Cloud Function sends a request with the user's search query to the Knowledge Graph API.
4. The Knowledge Graph API responds with any matching results.
5. The Cloud Function formats the response into a Slack message.
6. The Cloud Function sends the message back to Slack.
7. The user sees the formatted response in the Slack channel.

It may help to visualize the steps:

Creating the Knowledge Graph API key

In the Google Cloud Console Credentials page, click the Create credentials button and select API key. Remember this key, as you will use it to access the Knowledge Graph API in the next section.

Preparing the function

1. Clone the sample app repository to your local machine:

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

2. Change to the directory that contains the Cloud Functions sample code:

   Node.js

   cd nodejs-docs-samples/functions/slack/

   Python

   cd python-docs-samples/functions/slack/

   Go

   cd golang-samples/functions/slack/

3. Configure the app:

   Node.js

   Using the config.default.json file as a template, create a config.json file with the following contents:

   {
   "SLACK_SECRET": "YOUR_SLACK_SIGNING_SECRET",
   "KG_API_KEY": "YOUR_KG_API_KEY",
   }

   • Replace YOUR_SLACK_SIGNING_SECRET with the signing secret provided by Slack in the Basic information page of your app configuration.
   • Replace YOUR_KG_API_KEY with the Knowledge Graph API Key you just created.

   Python

   Edit the config.json file to have the following contents:

   {
   "SLACK_SECRET": "YOUR_SLACK_SIGNING_SECREET",
   "KG_API_KEY": "YOUR_KG_API_KEY",
   }

   • Replace YOUR_SLACK_SIGNING_SECRET with the signing secret provided by Slack in the Basic information page of your app configuration.
   • Replace YOUR_KG_API_KEY with the Knowledge Graph API Key you just created.

   Go

   Edit the config.json file to have the following contents:

   {
   "SLACK_SECRET": "YOUR_SLACK_SIGNING_SECRET",
   "KG_API_KEY": "YOUR_KG_API_KEY",
   }

   • Replace YOUR_SLACK_SIGNING_SECRET with the signing secret provided by Slack in the Basic information page of your app configuration.
   • Replace YOUR_KG_API_KEY with the Knowledge Graph API Key you just created.

Deploying the function

To deploy the function that is executed when you (or Slack) make an HTTP POST request to the function's endpoint, run the following command in the directory that contains the Cloud Functions sample code:

Node.js

gcloud functions deploy kgSearch --runtime nodejs8 --trigger-http

You can use the following values for the --runtime flag to specify your preferred Node.js version:

• nodejs6 (deprecated)
• nodejs8
• nodejs10 (beta)

Python

gcloud functions deploy kg_search --runtime python37 --trigger-http

Go

gcloud functions deploy KGSearch --runtime go111 --trigger-http

You can use the following values for the --runtime flag to specify your preferred Go version:

• go111
• go113 (beta)

Configuring the application

After the function is deployed, you need to create a Slack Slash Command that sends the query to your Cloud Function every time the command is triggered:

1. Create a Slack App to host your Slack Slash Command. Associate it with a Slack team where you have permissions to install integrations.

2. Go to Slash commands and click the Create new command button.

3. Enter /kg as the name of the command.

4. Enter the URL for the command:

   Node.js

   https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kgSearch

   Python

   https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kg_search

   Go

   https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/KGSearch

   where YOUR_REGION is the region where your Cloud Function is deployed and YOUR_PROJECT_ID is your Cloud project ID.

   Both values are visible in your terminal when your function finishes deploying.

5. Click Save.

6. Go to Basic Information.

7. Click Install your app to your workspace and follow the instructions on screen to enable the application for your workspace.

   Your Slack Slash Command should come online shortly.

Understanding the code

Importing dependencies

The application must import several dependencies in order to communicate with Google Cloud Platform services:

Node.js

functions/slack/index.js

View on GitHub

const config = require('./config.json');
const {google} = require('googleapis');
const {verifyRequestSignature} = require('@slack/events-api');

// Get a reference to the Knowledge Graph Search component
const kgsearch = google.kgsearch('v1');

Python

functions/slack/main.py

View on GitHub

import hashlib
import hmac
import json
import os

import apiclient
from flask import jsonify

with open('config.json', 'r') as f:
    data = f.read()
config = json.loads(data)


kgsearch = apiclient.discovery.build(
    'kgsearch',
    'v1',
    developerKey=os.environ.get('API_KEY') or config.get('KG_API_KEY'),
    cache_discovery=False)

Go

functions/slack/setup.go

View on GitHub

package slack

import (
	"context"
	"encoding/json"
	"log"
	"os"

	"google.golang.org/api/kgsearch/v1"
	"google.golang.org/api/option"
)

type configuration struct {
	ProjectID string `json:"PROJECT_ID"`
	Token     string `json:"SLACK_TOKEN"`
	Key       string `json:"KG_API_KEY"`
	Secret    string `json:"SLACK_SIGNING_SECRET"`
}

var (
	entitiesService *kgsearch.EntitiesService
	config          *configuration
)

func setup(ctx context.Context) {
	if config == nil {
		cfgFile, err := os.Open("config.json")
		if err != nil {
			log.Fatalf("os.Open: %v", err)
		}

		d := json.NewDecoder(cfgFile)
		config = &configuration{}
		if err = d.Decode(config); err != nil {
			log.Fatalf("Decode: %v", err)
		}
	}

	if entitiesService == nil {
		kgService, err := kgsearch.NewService(ctx, option.WithAPIKey(config.Key))
		if err != nil {
			log.Fatalf("kgsearch.NewClient: %v", err)
		}
		entitiesService = kgsearch.NewEntitiesService(kgService)
	}
}

Receiving the webhook

The following function is executed when you (or Slack) make an HTTP POST request to the function's endpoint:

Node.js

functions/slack/index.js

View on GitHub Feedback

/**
 * Receive a Slash Command request from Slack.
 *
 * Trigger this function by creating a Slack slash command with this URL:
 * https://[YOUR_REGION].[YOUR_PROJECT_ID].cloudfunctions.net/kgsearch
 *
 * @param {object} req Cloud Function request object.
 * @param {object} req.body The request payload.
 * @param {string} req.rawBody Raw request payload used to validate Slack's message signature.
 * @param {string} req.body.text The user's search query.
 * @param {object} res Cloud Function response object.
 */
exports.kgSearch = async (req, res) => {
  try {
    if (req.method !== 'POST') {
      const error = new Error('Only POST requests are accepted');
      error.code = 405;
      throw error;
    }

    // Verify that this request came from Slack
    verifyWebhook(req);

    // Make the request to the Knowledge Graph Search API
    const response = await makeSearchRequest(req.body.text);

    // Send the formatted message back to Slack
    res.json(response);

    return Promise.resolve();
  } catch (err) {
    console.error(err);
    res.status(err.code || 500).send(err);
    return Promise.reject(err);
  }
};

Python

functions/slack/main.py

View on GitHub

def kg_search(request):
    if request.method != 'POST':
        return 'Only POST requests are accepted', 405

    verify_signature(request)
    kg_search_response = make_search_request(request.form['text'])
    return jsonify(kg_search_response)

Go

functions/slack/search.go

View on GitHub

// Package slack is a Cloud Function which recieves a query from
// a Slack command and responds with the KG API result.
package slack

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"strconv"
	"strings"
	"time"
)

type oldTimeStampError struct {
	s string
}

func (e *oldTimeStampError) Error() string {
	return e.s
}

const (
	version                     = "v0"
	slackRequestTimestampHeader = "X-Slack-Request-Timestamp"
	slackSignatureHeader        = "X-Slack-Signature"
)

type attachment struct {
	Color     string `json:"color"`
	Title     string `json:"title"`
	TitleLink string `json:"title_link"`
	Text      string `json:"text"`
	ImageURL  string `json:"image_url"`
}

// Message is the a Slack message event.
// see https://api.slack.com/docs/message-formatting
type Message struct {
	ResponseType string       `json:"response_type"`
	Text         string       `json:"text"`
	Attachments  []attachment `json:"attachments"`
}

// KGSearch uses the Knowledge Graph API to search for a query provided
// by a Slack command.
func KGSearch(w http.ResponseWriter, r *http.Request) {
	setup(r.Context())

	bodyBytes, err := ioutil.ReadAll(r.Body)
	if err != nil {
		log.Fatalf("Couldn't read request body: %v", err)
	}
	r.Body = ioutil.NopCloser(bytes.NewBuffer(bodyBytes))

	if r.Method != "POST" {
		http.Error(w, "Only POST requests are accepted", 405)
	}
	if err := r.ParseForm(); err != nil {
		http.Error(w, "Couldn't parse form", 400)
		log.Fatalf("ParseForm: %v", err)
	}

	// Reset r.Body as ParseForm depletes it by reading the io.ReadCloser.
	r.Body = ioutil.NopCloser(bytes.NewBuffer(bodyBytes))
	result, err := verifyWebHook(r, config.Secret)
	if err != nil {
		log.Fatalf("verifyWebhook: %v", err)
	}
	if !result {
		log.Fatalf("signatures did not match.")
	}

	if len(r.Form["text"]) == 0 {
		log.Fatalf("emtpy text in form")
	}
	kgSearchResponse, err := makeSearchRequest(r.Form["text"][0])
	if err != nil {
		log.Fatalf("makeSearchRequest: %v", err)
	}
	w.Header().Set("Content-Type", "application/json")
	if err = json.NewEncoder(w).Encode(kgSearchResponse); err != nil {
		log.Fatalf("json.Marshal: %v", err)
	}
}

The following function authenticates the incoming request by verifying the X-Slack-Signature header provided by Slack:

Node.js

functions/slack/index.js

View on GitHub Feedback

/**
 * Verify that the webhook request came from Slack.
 *
 * @param {object} req Cloud Function request object.
 * @param {string} req.headers Headers Slack SDK uses to authenticate request.
 * @param {string} req.rawBody Raw body of webhook request to check signature against.
 */
const verifyWebhook = req => {
  const signature = {
    signingSecret: config.SLACK_SECRET,
    requestSignature: req.headers['x-slack-signature'],
    requestTimestamp: req.headers['x-slack-request-timestamp'],
    body: req.rawBody,
  };

  if (!verifyRequestSignature(signature)) {
    const error = new Error('Invalid credentials');
    error.code = 401;
    throw error;
  }
};

Python

functions/slack/main.py

View on GitHub

# Python 3+ version of https://github.com/slackapi/python-slack-events-api/blob/master/slackeventsapi/server.py
def verify_signature(request):
    timestamp = request.headers.get('X-Slack-Request-Timestamp', '')
    signature = request.headers.get('X-Slack-Signature', '')

    req = str.encode('v0:{}:'.format(timestamp)) + request.get_data()
    request_digest = hmac.new(
        str.encode(config['SLACK_SECRET']),
        req, hashlib.sha256
    ).hexdigest()
    request_hash = 'v0={}'.format(request_digest)

    if not hmac.compare_digest(request_hash, signature):
        raise ValueError('Invalid request/credentials.')

Go

functions/slack/search.go

View on GitHub

// VeryfyWebhook uses signature verification instead of tokens.
// see https://api.slack.com/docs/verifying-requests-from-slack
func verifyWebHook(r *http.Request, slackSigningSecret string) (bool, error) {
	timeStamp := r.Header.Get(slackRequestTimestampHeader)
	slackSignature := r.Header.Get(slackSignatureHeader)

	t, err := strconv.ParseInt(timeStamp, 10, 64)
	if err != nil {
		return false, fmt.Errorf("strconv.ParseInt(%s): %v", timeStamp, err)
	}

	if ageOk, age := checkTimestamp(t); !ageOk {
		return false, &oldTimeStampError{fmt.Sprintf("checkTimestamp(%v): %v %v", t, ageOk, age)}
		// return false, fmt.Errorf("checkTimestamp(%v): %v %v", t, ageOk, age)
	}

	if timeStamp == "" || slackSignature == "" {
		return false, fmt.Errorf("either timeStamp or signature headers were blank")
	}

	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		return false, fmt.Errorf("ioutil.ReadAll(%v): %v", r.Body, err)
	}

	// Reset the body so other calls won't fail.
	r.Body = ioutil.NopCloser(bytes.NewBuffer(body))

	baseString := fmt.Sprintf("%s:%s:%s", version, timeStamp, body)

	signature := getSignature([]byte(baseString), []byte(slackSigningSecret))

	trimmed := strings.TrimPrefix(slackSignature, fmt.Sprintf("%s=", version))
	signatureInHeader, err := hex.DecodeString(trimmed)

	if err != nil {
		return false, fmt.Errorf("hex.DecodeString(%v): %v", trimmed, err)
	}

	return hmac.Equal(signature, signatureInHeader), nil
}

func getSignature(base []byte, secret []byte) []byte {
	h := hmac.New(sha256.New, secret)
	h.Write(base)

	return h.Sum(nil)
}

// Arbitrarily trusting requests time stamped less than 5 minutes ago.
func checkTimestamp(timeStamp int64) (bool, time.Duration) {
	t := time.Since(time.Unix(timeStamp, 0))

	return t.Minutes() <= 5, t
}

Querying the Knowledge Graph API

The following function sends a request with the user's search query to the Knowledge Graph API:

Node.js

functions/slack/index.js

View on GitHub Feedback

/**
 * Send the user's search query to the Knowledge Graph API.
 *
 * @param {string} query The user's search query.
 */
const makeSearchRequest = query => {
  return new Promise((resolve, reject) => {
    kgsearch.entities.search(
      {
        auth: config.KG_API_KEY,
        query: query,
        limit: 1,
      },
      (err, response) => {
        console.log(err);
        if (err) {
          reject(err);
          return;
        }

        // Return a formatted message
        resolve(formatSlackMessage(query, response));
      }
    );
  });
};

Python

functions/slack/main.py

View on GitHub

def make_search_request(query):
    req = kgsearch.entities().search(query=query, limit=1)
    res = req.execute()
    return format_slack_message(query, res)

Go

functions/slack/search.go

View on GitHub

func makeSearchRequest(query string) (*Message, error) {
	res, err := entitiesService.Search().Query(query).Limit(1).Do()
	if err != nil {
		return nil, fmt.Errorf("Do: %v", err)
	}
	return formatSlackMessage(query, res)
}

Formatting the Slack message

Finally, the following function formats the Knowledge Graph result into a richly formatted Slack message that will be displayed to the user:

Node.js

functions/slack/index.js

View on GitHub Feedback

/**
 * Format the Knowledge Graph API response into a richly formatted Slack message.
 *
 * @param {string} query The user's search query.
 * @param {object} response The response from the Knowledge Graph API.
 * @returns {object} The formatted message.
 */
const formatSlackMessage = (query, response) => {
  let entity;

  // Extract the first entity from the result list, if any
  if (
    response &&
    response.data &&
    response.data.itemListElement &&
    response.data.itemListElement.length > 0
  ) {
    entity = response.data.itemListElement[0].result;
  }

  // Prepare a rich Slack message
  // See https://api.slack.com/docs/message-formatting
  const slackMessage = {
    response_type: 'in_channel',
    text: `Query: ${query}`,
    attachments: [],
  };

  if (entity) {
    const attachment = {
      color: '#3367d6',
    };
    if (entity.name) {
      attachment.title = entity.name;
      if (entity.description) {
        attachment.title = `${attachment.title}: ${entity.description}`;
      }
    }
    if (entity.detailedDescription) {
      if (entity.detailedDescription.url) {
        attachment.title_link = entity.detailedDescription.url;
      }
      if (entity.detailedDescription.articleBody) {
        attachment.text = entity.detailedDescription.articleBody;
      }
    }
    if (entity.image && entity.image.contentUrl) {
      attachment.image_url = entity.image.contentUrl;
    }
    slackMessage.attachments.push(attachment);
  } else {
    slackMessage.attachments.push({
      text: 'No results match your query...',
    });
  }

  return slackMessage;
};

Python

functions/slack/main.py

View on GitHub

def format_slack_message(query, response):
    entity = None
    if response and response.get('itemListElement') is not None and \
       len(response['itemListElement']) > 0:
        entity = response['itemListElement'][0]['result']

    message = {
        'response_type': 'in_channel',
        'text': 'Query: {}'.format(query),
        'attachments': []
    }

    attachment = {}
    if entity:
        name = entity.get('name', '')
        description = entity.get('description', '')
        detailed_desc = entity.get('detailedDescription', {})
        url = detailed_desc.get('url')
        article = detailed_desc.get('articleBody')
        image_url = entity.get('image', {}).get('contentUrl')

        attachment['color'] = '#3367d6'
        if name and description:
            attachment['title'] = '{}: {}'.format(entity["name"],
                                                  entity["description"])
        elif name:
            attachment['title'] = name
        if url:
            attachment['title_link'] = url
        if article:
            attachment['text'] = article
        if image_url:
            attachment['image_url'] = image_url
    else:
        attachment['text'] = 'No results match your query.'
    message['attachments'].append(attachment)

    return message

Go

functions/slack/format.go

View on GitHub

package slack

import (
	"fmt"

	"google.golang.org/api/kgsearch/v1"
)

func formatSlackMessage(query string, response *kgsearch.SearchResponse) (*Message, error) {
	if response == nil {
		return nil, fmt.Errorf("empty response")
	}

	if response.ItemListElement == nil || len(response.ItemListElement) == 0 {
		message := &Message{
			ResponseType: "in_channel",
			Text:         fmt.Sprintf("Query: %s", query),
			Attachments: []attachment{
				{
					Color: "#d6334b",
					Text:  "No results match your query.",
				},
			},
		}
		return message, nil
	}

	entity, ok := response.ItemListElement[0].(map[string]interface{})
	if !ok {
		return nil, fmt.Errorf("could not parse response entity")
	}
	result, ok := entity["result"].(map[string]interface{})
	if !ok {
		return nil, fmt.Errorf("error formatting response result")
	}

	attach := attachment{Color: "#3367d6"}
	if name, ok := result["name"].(string); ok {
		if description, ok := result["description"].(string); ok {
			attach.Title = fmt.Sprintf("%s: %s", name, description)
		} else {
			attach.Title = name
		}
	}
	if detailedDesc, ok := result["detailedDescription"].(map[string]interface{}); ok {
		if url, ok := detailedDesc["url"].(string); ok {
			attach.TitleLink = url
		}
		if article, ok := detailedDesc["articleBody"].(string); ok {
			attach.Text = article
		}
	}
	if image, ok := result["image"].(map[string]interface{}); ok {
		if imageURL, ok := image["contentUrl"].(string); ok {
			attach.ImageURL = imageURL
		}
	}

	message := &Message{
		ResponseType: "in_channel",
		Text:         fmt.Sprintf("Query: %s", query),
		Attachments:  []attachment{attach},
	}
	return message, nil
}

Slack API timeouts

The Slack API expects your function to respond within 3 seconds of receiving a webhook request.

The commands in this tutorial typically take less than 3 seconds to respond. For longer-running commands, we recommend configuring a function to push requests (including their response_url) to a Pub/Sub topic that acts as a task queue.

Then, you can create a second function triggered by Pub/Sub that processes those tasks and sends results back to Slack's response_url.

Using the Slash command

1. Type the command into your Slack channel:

   /kg giraffe

2. Watch the logs to be sure the executions have completed:

   gcloud functions logs read --limit 100
   

Cleaning up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this tutorial:

Deleting the project

The easiest way to eliminate billing is to delete the project that you created for the tutorial.

To delete the project:

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for this tutorial, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple tutorials and quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Cloud Console, go to the Manage resources page.

   Go to the Manage resources page

2. In the project list, select the project you want to delete and click Delete .
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Deleting the Cloud Function

To delete the Cloud Function you deployed in this tutorial, run the following command:

Node.js

gcloud functions delete kgSearch 

Python

gcloud functions delete kg_search 

Go

gcloud functions delete KGSearch 

You can also delete Cloud Functions from the Google Cloud Console.