Quickstart

Learning Objectives

In this quickstart, you'll learn to configure your first Query. We will use an API based on a publicly available holiday API to look up the public holidays through your bot.

Before you start, make sure...

  1. You have the access to the Queries Workspace.

Step 1: Create a New Query

  1. Go to Queries Workspace
  2. Click Create.
  3. Enter a name and description. Feel free to copy from below:

    Name

    Copy
    Copied
    2023 Holiday Calendar

    Description

    Copy
    Copied
    🎄 Lookup the list of public holidays for 2023.

Overview

Do not enter placeholder values (test, demo, etc.)

These values will be

  1. Shown directly to your users
  2. Used to build the generative intent

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

Step 2: Setup Your API Request

In this step, you will teach Queries how to interact with your APIs.

  1. Select the pre-configured Creator Studio Sample Endpoints connector. This contains any relevant authentication + connection information for your API, along with a base url (https://us-central1-creator-studio-demo.cloudfunctions.net in this case)
    Missing connector?

    If you do not see the Creator Studio Sample Endpoints connector, work with your Moveworks Customer Success team to register a new connector.

  2. Fill in the "API endpoint" path for the holiday calendar api, which is /holidays. This gets appended to the connector's base URL.
    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.

url stitching
  1. Select POST under the "Method" section.
3 connector select
  1. Paste the following text in the "JSON request body" section (leave the "headers" and "query parameters" sections empty).
    Copy
    Copied
    {
    "year": 2023
}
4 api select
  1. 🎉 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.

Based on your instructions, Queries will perform response synthesis on the API data to design the final message to the user.

Response Synthesis

  1. Specify the root element. This is the key to either the list of records lives, or dictionary containing the individual record retrieved by the API.

    In the following snippet, data.holidays is the root element.

    Copy
    Copied
    {
  "data": {
    "holidays": [
      {
        "name": "Holiday 1",
        "date": "Date 1"
      },
      ...
    ]
  }
}
  2. Map the identifier. This is the most obvious "title" for a given record, something that a user would use to uniquely identify the record.

    For a holidays query, let's use the name.

  3. Map the description. This is a "primary" attribute. Especially if the identifier is an alphanumeric ID, the description is helpful to contextualize what the record is.

    For a holidays query, let's use the date.

  4. You can leave "Additional Info" blank for now, but you can label other attributes that Moveworks can use in response synthesis.

    For example, the global key refers to if the Holiday is a Worldwide Holiday.

10 identifier description
  1. Add a button to link users to a website listing the public holidays for the year.

    Button Name

    Copy
    Copied
    View Holidays

    URL

    Copy
    Copied
    https://date.nager.at/PublicHoliday/Country/US

Optional button and field information

  1. 🎉 Your API response is labeled. For best practices & advanced details, see our response synthesis guide

Step 4: Generate Your Intent

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

  1. Choose This lookup doesn't contain any keyword.

Utterance configuration Since this query will always return the holidays for 2023, there are no slots. You can learn more about slot extraction configuration options here.

  1. Add at least 3 ways to ask about this query.

    Utterance configuration

Temporary Step

This only applies to our pre-launch customers, we will automate the generation of these utterances based on the API schema by our public launch.

For this use case, we can use

  • show upcoming vacations - a "command-line" utterance
  • What holidays do we have in 2023 - a "general utterance"
  • When is MLK day? - a "sample record" utterance

If you need help coming up with these, see our intent tuning tips

Step 5: Control Access & Launch

  1. Choose Launch to selected emails(Testing)
  2. Add your work email address under Allow Emails Values
  3. Click Launch.
    Do not use this endpoint in production.

    Our team publishes test endpoints for your experimentation as part of the Creator Studio Sample Endpoints connector. These are not stable APIs designed for production use across your entire company.

Select launch employees

Do not attempt to edit the Query.

If you need to make changes to your Query, please exit Creator Studio first, otherwise you may produce duplicate Queries.

You can learn more about the other launch management options here.

Step 6: Test!

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

Try a complex utterance like the one shown below. Even though it looks nothing like the original queries, it still works great!

14 summary

Read more about why this works with our generative intents!

🎉 Congrats! Now, make it more powerful

When combined with the right complimentary technologies, you can accomplish incredible things with Queries.

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

Copyright © Moveworks 2023. All right reserved.