Context | Yext Hitchhikers Platform

Very often, you’ll want your Yext Chat bot to behave differently depending on the context it’s being shown in. For example, you might want the chat bot to respond differently depending on the page it’s located on. Or you might want the chat bot to respond differently depending on who the user is.

Yext Chat supports these use cases by allowing you to pass “context” to the bot, and then reference that context within the instructions. You can pass whatever data you want to as context, but a few common examples include:

• A unique user ID that can be referenced in subsequent API calls
• Demographic information about the user, such as their age or gender
• Information about the page the chat bot is located on, such as the ID of a location or product
• AB testing flags

Usually, you’ll want to set context dynamically within your front-end code by accessing some other value, such as the location of the page, or the user’s ID. Here’s how to do this.

Script Tag

If you’re using the script tag integration, you can set context using the setContext method.

<link rel="stylesheet" href="https://assets.sitescdn.net/chat/v0/chat.css" />
<script defer src="https://assets.sitescdn.net/chat/v0/chat.umd.js" onload="initChat()"></script>
<script>
  function initChat() {
    // First, initialize the chat widget as you would normally
    window.ChatApp.mount({
      apiKey: "<YOUR_API_KEY>",
      botId: "my-chat-bot",
      title: "My Chat Bot",
      stream: false,
    });
	  // Next, get whatever information you need to pass to the bot
		// (You write this code)
		const { userId, locationId } = getContextData();
		// Finally, set the context in the chat apps
    window.ChatApp.setContext({
			userId: userId,
			locationId: locationId
    });
  }
</script>

Headless SDK

If you’re using the headless SDK, you can use the setContext hook. Here’s an example in React:

import { useEffect } from "react";
import { useChatActions } from "@yext/chat-headless-react";
import { ChatPanel } from "@yext/chat-ui-react";

function MyApp() {
  const chat = useChatActions();

  // Write your code to get the data
  const { userId, locationId } = getContextData();

  // Set the context once when your application loads
  useEffect(() => {
    chat.setContext({
      userId: "1234",
      businessId: "3472542",
    });
  }, []);

  return <ChatPanel />;
}

Using Context in Instructions

Once you’ve set context on the front-end, you can reference that context within the instructions of your bot. When you are setting up an instruction you can use the bracket notation [[context.INSERT_CONTEXT_ID]] to pull the information you set up in the previous step.

Here are a couple examples of ways you might use the context and how you would reference them in your bot configuration:

• Using a User ID (e.g., [[context.userID]]), fetch data about that user’s order history to answer questions such as “when will my order arrive”
• Limit Yext Search results to a specific category (e.g., [[context.category]]) or even to a specific product (e.g., [[context.product]])

Location-Specific Chat Bot Example

Often, you’ll want Yext Chat to answer questions about a single physical location. For example, if you have are using Yext Chat on your restaurant chain’s landing pages, you might want it to answer questions only about the location whose page it’s located on.

You can accomplish this by passing the location’s ID in Yext Content, using the Yext Content API to fetch data about it, and then using that data to answer the user’s question.

1. Add Context to the Chat Front-End

First, set the location ID on the front-end. Depending on how your pages are set up, this may be stored somewhere in the DOM or on the window.

<link rel="stylesheet" href="https://assets.sitescdn.net/chat/v0/chat.css" />
<script defer src="https://assets.sitescdn.net/chat/v0/chat.umd.js" onload="initChat()"></script>
<script>
  function initChat() {
    window.ChatApp.mount({
      apiKey: "<YOUR_API_KEY>",
      botId: "my-chat-bot",
      title: "My Chat Bot",
      stream: false,
    });
	  // Get the location ID
		const locationId = getLocationId();
		// Finally, set the context in the chat apps
    window.ChatApp.setContext({
			locationId: locationId,
    });
  }
</script>

2. Reference context in the bot configuration

Next, you can reference this data inside the instructions of your bot by using bracket notation [[context.locationId]] and use it to look up information about that entity within Yext Chat.

Here’s a simple example of how your bot configuration might look. This configuration has a single goal called answer-location-question which uses the Yext Content API to fetch information about that location and answer the user’s question about it. In the code you will see that the location ID is inserted in the URL of the API call:

{
  "$id": "yext-marketing-bot",
  "$schema": "https://schema.yext.com/config/chat/chat-bot/v1",
  "name": "Location Bot",
  "initialMessage": "Hi! This is the bot for Bob's Burgers. How can I help you?",
  "goals": {
    "answer-location-question": {
      "goal": "Answer a question about Yext.",
      "instructions": [
        {
          "restApi": {
            "method": "GET",
            "url": "https://cdn.yextapis.com/v2/accounts/me/content/my-content-endpoint/[[context.locationId]]?apiKey=<YOUR_API_KEY_HERE>"
          }
        },
        {
          "reply": {
            "instruction": "Based on the data you found, answer the user's question.",
            "mode": "DIRECT_ANSWER"
          }
        }
      ]
    }
  }
}