Use case
Following the newly launched Coveo Slack Application, it is now possible to search your whole Coveo index directly from Slack with a single click or slash command. This is definitely a great approach to search, but what about Slack users that are not aware of this feature but actually need it? This is the use-case we will tackle in this project: automatically answering questions in targeted Slack channels.
It is not a secret that some Slack channels become a search dump and it is not always easy to address them all, even when the answers are sometimes easy to find. A great way to tackle this problem is to try to find questions and send them to the Coveo Search API. A simple way to do this is to listen to all the messages sent on a targeted channels, and only trigger a search on the ones containing a question mark.
A simple architecture for this idea would be to host a serverless function in AWS Lambda, and send the detected question to Coveo’s Search API. For better versioning, deployment, and monitoring approach, a serverless Application will be used for this project.
Integration requirements
- Coveo Platform rights to generate an API Key with the proper rights
- Write access in AWS for the following products: AWS Lambda, AWS Cloud Watch, AWS API Gateway and, AWS Parameter Store
- Slack Admin rights to create an application and deploy it in a workspace
Architecture
Building it
Create your .env file
For the publicly available variables needed for our application, we will add a .env
file at the root of our repo. You can copy the .env.example
content and fill the right side of the variables with the AWS region (default in North America would be us-east-1
but make sure to confirm this in your AWS console) and the Coveo-related properties. The Coveo pipeline is optional and will use default
if empty. Here’s an example :
COVEO_AWS_REGION=us-east-1
COVEO_ENDPOINT=https://platform.cloud.coveo.com
COVEO_ORG=myCompanyOrg
COVEO_PIPELINE=default
AWS_PROFILE=rd
AWS_SDK_LOAD_CONFIG=1
Create an Impersonation API key in the Coveo Platform
Before creating our API key, let’s set up our AWS parameter store to store it.
Create an AWS Parameter Store folder for your app
- Navigate to the Parameter Store landing page, and click Create parameter.
- Create a new name path for your application. For this example, we used the following path
/rd/coveo-autoreply-bot
with the parameter nameCOVEO_API_KEY
. Make sure to give a unique path to your app-related tokens so we can give our Lambda restricted access to it later in the configuration. Also, make sure to select theSecureString
type for the parameter.
We don’t have a value to store yet so we will generate an API Key.
Now that we are ready to create our secure parameter, let’s create our Coveo API KEY:
- In another tab, navigate to your Coveo platform and create a Key. Make sure you add
Search - Impersonation
,Analytics - Data, Push
, andAnalytics - Impersonate
. More on the impersonate Privilege and its danger(you can pick any value for the searchHub, keep it noted for later) - When done, click ** Add key** and, copy the generated key.
- Browse back to your parameter store and add the API Key in the
COVEO_API_KEY
parameter value. Submit by clicking Create parameter.
Keep that key private!!!
Create a Slack app
As an admin in the Slack workspace, navigate to https://api.slack.com/ and click Create an App
. Two choices will be given to you: From scratch or From an app manifest. Select From an app manifest
.
- Select the workspace where the app should be created and click Next.
- Copy the
manifestExample.yml
file into the manifest configuration. If you want a custom name, make sure to change thedisplay_information.name
and thebot_user.display_name
properties. Click onNext
. - Review the OAuth scopes, features, and settings, and click Create.
- Your app is now created. The Events request URL under Event Subscription will not work at this time but it’s normal; we will need to set up AWS to generate a proper request URL in the next section.
Store the confidential tokens in your parameter store, with the SecureString
type
To allow testing our app locally seamlessly, we will create a token that enables socket mode in development. We will that save that App Token, along with our Signing Secret and Bot Token in SSM.
- Navigate to
Basic Information
. - Navigate to
App-Level Tokens
. - Click Generate Token and Scopes.
- Add both
connections:write
andauthorization:read
scopes to your token. Give it a name and generate it. Copy the token starting withxapp
and store it in your Parameter Store with the same prefix path as before. For this example, we usedSLACK_APP_TOKEN
as the parameter name. - Navigate to
App Credentials
. - Show the
Signing Secret
and store it in your Parameter Store with the same prefix path as before. For this example, we usedSLACK_SIGNING_SECRET
as the parameter name. - Navigate to
OAuth & Permissions
. - Copy the
Bot User OAuth Token
under theOAuth Tokens for Your Workspace
section and store it in your Parameter Store. For this example, we usedSLACK_BOT_TOKEN
as the attribute name
Create a Lambda Application automatically with Serverless
The serverless.yaml
file, in conjunction with the handler.js
and app.js
are the ones that will be used by your AWS Lambda when deployed. For development ease, we will let serverless create an App using a CloudFormation template. The template will include:
- An S3 bucket to store and version your deployed app
- A Lambda function
- A Gateway Rest API to access the Lambda
- A Log Group to monitor your app
If you want to change the service name of your app (defaulted at autoreply-coveo-slack-bot), you can do it on the first line of the yaml file.
To deploy your app simply run npm run deploy:lambda
.
Warning: At first, your lambda will not have access to your parameter store so you will need to give it permission.
Add a policy to the lambda function to gain access to your parameters
- Open the AWS Lambda console and click on your function’s name.
- Select the
Configuration
tab, and then clickPermissions
. - Click on the Execution role name.
- In the Permission policies section, click Add permissions, and then click Create inline policy.
- With the Visual Editor, select System Manager as the Service,
GetParameter
as the Action, and the path to your application parameter folder followed by/*
for the resources. The review policy should look like this: - Click
Create policy
when completed.
Copy your Gateway API endpoint in the Slack app
Now that your app is deployed to AWS, you will need to update the Slack App URLs.
- Get your API Gateway endpoint URL. To do so, you can find it:
- In your terminal after having deployed your serverless app or in the AWS console. When found, copy it.
- In the AWS console by browsing to the Lambda landing page and clicking on the
Functions
side menu, and clicking on your function name. You should see the API Gateway in the trigger section of your function overview. By clicking on it, you should see the trigger appear with an API endpoint listed. Copy it.
- Go back to your Slack app setup and navigate to the Events request URL under the
Event Subscription
. Paste the gateway URL. It should mark asVerified
.
Install your Slack app to your workspace
- Go to your Slack app setup and navigate to the
Basic Information
. - Click
Install to Workplace
. - Confirm the information and the destination Workplace and click
Allow
.
Local Debugging
- To activate local debugging, you need to enable the Socket Mode in the application menu (found at https://api.slack.com/apps/$YOUR_APP_ID), in the
Socket Mode
menu underSettings
. This will redirect your app events over a WebSockets connection. - In your terminal, run
npm run dev
, which will run theapp.js
code, which is set up to work with the SocketMode and hot-reload your code. - You can now change your bot behavior with a live result.
- Once you are satisfied with the results, use
npm run deploy:lambda
to update you lambda !
Use it
In the channels you want questions answered, click the channel name and navigate to the Integrations tab. Under the Apps section, click Add, an App. And select your auto-reply bot app:
Now, if any questions returned answered, your bot will answer them:
In conclusion, this blog post showcased how to easily connect a Slack channel to an auto-reply bot querying Coveo. The GitHub repo can be found here.
Do you like connecting things together, getting access to all your content from wherever you want? Join Coveo and help make that dream a reality!