Queries Quickstart

Learning Objectives

In this quickstart, you'll learn to create a sample use case to find marketing campaign data. This will help you learn to use the Queries workspace.

Before you start, make sure...

  1. You have the access to the Queries Workspace.

Use Case Overview

Design Pattern: [DP-7] Lookup Single Record by Name

Use Case Description: Look up marketing insights by the marketing campaign's name.

[object Object]
Gwen11:43 AM

What was the most recent marketing campaign we ran for ACME?

Find Most Recent Campaign for ACME from PurpleCRM (API Documentation)

[object Object]
Moveworks11:43 AM

One moment, fetching your results. This may take ~10 seconds

CAMPAIGN-008: Revolutionize your supply chain management with our platform!
Open Rate: 9.87%
Total Recipients: 187,654
Unsubscribe Rate: 0.20%
Date Launched: 07/15/2023

Step 1: Create a New Query

  1. Click CREATE on the Queries Workspace homepage 100create
  2. Copy & Paste the Query Label: Campaign Marketing Insights
  3. Copy & Paste the Short Description: Look up Campaign Insights in PurpleCRM 200basic_info
Do not enter placeholder values (test, demo, etc.)

These values will be

  1. Shown directly to your users
  2. Used to build to influence the triggering of your use case

Using poor names will result in a poor chat & NLU experience.

  1. Click Next to go to the next step

Step 2: Setup Your API Request

In this step, you will set up the API Request to query the desired data.

  1. Select your previously set up Creator Studio Demo Function connector
  2. Click Next 300connector
  3. In API Endpoint Path, insert /getMostRecentCampaign
  4. In Method, insert GET
  5. In Query Parameters, insert org_name as the Key and {{query}} as the Value. {{query}} tells the bot where to insert the "slot" or keyword we are getting from a user's utterance in chat. 400api_part1
Do not put query parameters in the path.

Some APIs have query parameters in the URL path. Please enter these in the query parameters table.

  1. In Example value, insert ACME. The example value is replacing {{query}} above so we can test our API request.
  2. Click Test. If your Test response comes back 2xx then it was successful.
  3. Click Next 501api_part2_v2

    🎉 Your API Endpoint is setup! You can see our API configuration guide for advanced setup details

Step 3: Label the API Response

In this step, you will teach Queries how to present the API information to users.

  1. Click SET UP under Identifier and Description
  2. Set Identifier to id - This is the most obvious "title" for a given record, something that a user would use to uniquely identify the record.
  3. Set Description to campaignName - This is a "primary" attribute. Especially if the identifier is an alphanumeric ID, the description is helpful to contextualize what the record is.
  4. Click Save 600grounding_part1
  5. Check the checkbox for dateLaunched, openRate, totalRecipients, unsubscribeRate - These are all mapped as additional fields to show when a record is surfaced to the end user. 700grounding_part2
    Make sure you update the Label with user friendly names

    🎉 Your API response is labeled. For best practices & advanced details, see our API Labeling Guide

Step 4: Generate Your Intent

In this step, you will teach Queries when to present data to your users.

There are 10 example utterances that are generated

  1. There are 10 example utterances that are generated. Verify these are relevant utterances and replace them if not.
  2. Click Next 800triggering

Step 5: Launch Options & Publishing

  1. In Choose a launch option, select Launch to selected emails
  2. Add your email under Allow Emails Values
  3. Click Publish 900launch

Learn more about the other Launch Management Options.

Step 6: Test!

A few minutes after launching, you can test your new Query in chat!

Try the one below:

Copy
Copied
What is the performance of the ACME campaign in PurpleCRM?

Additional Resources

  • Not sure where to start? Check out our Idea Library for the touch of inspiration you need!