Chat SDKs | Yext Hitchhikers Platform

Yext Chat provides three Javascript SDKs you can use to build applications for the web:

• chat-core : A Typescript library for interacting with the Chat API. This library contains no UI or state management and can be used in Node applications, so it’s ideal for server-side applications like building a Slack or SMS bot.
• chat-headless : A Redux state management library that makes it easy to manage conversation state and interact with the Chat API, but doesn’t come with any UI or styling. If you want to use this library with React specifically, you can use the React bindings in chat-headless-react .
• chat-ui-react : A library of styled-but-customizable React UI components that make it easy to quickly build a chat UI in React. This library uses Tailwind CSS for styling.

Chat Core

Chat Core is a simple, stateless library for interacting with the Chat API. Here’s a simple example:

import { ChatCore, type Message } from "@yext/chat-core";

const chat = new ChatCore({
  botId: "<YOUR_BOT_ID>",
  apiKey: "<YOUR_API_KEY",
 })

const sampleMessage: Message = {
  source: "USER",
  timestamp: "2023-06-05T18:46:58.527Z",
  text: "Tell me a joke!",
}

const response = chat.getNextMessage({ messages: [sampleMessage]}

The most important method here is .getNextMessage, which retrieves the next message from the bot given the conversation history, which is an array of messages.

This method sends a POST request to the Chat API and returns its response.

Chat Headless

Whereas Chat Core is stateless wrapper on top of the Chat API, Chat Headless manages the entire state of the conversation for you using Redux . It provides methods for performing actions to manipulate the state.

Chat Headless can be used with any Javascript framework, but we also export simple React bindings in @yext/chat-headless-react , which is built on react-redux .

Here’s a simple example:

import { ChatHeadlessProvider } from "@yext/chat-headless-react"
import { MyComponent } from "./components/MyComponent"

const MyApp = () => {
  return (
    <ChatHeadlessProvider
      config={{
        apiKey: "<YOUR_API_KEY>",
        botId: "<YOUR_BOT_ID>",
      }}
    >
      <MyComponent />
    </ChatHeadlessProvider>
  )
}

Once your application is wrapped in a <ChatHeadlessProvider/> , you can use the useChatState and useChatActions hooks within any children components of the app.

import { useChatState, useChatActions } from "@yext/chat-headless-react"

const MyComponent = () => {
  const chat = useChatActions();
  const messages = useChatState(state => state.conversation.messages)
  return (
    <div>
      <ul>
        {
          messages.map(message => (
            <li>
              {message.text}
            </li>
          ))
        }
      <ul>
      <input
        onSubmit={(e => chat.getNextMessage(e.target.value))}
      />
    </div>
  )
}

Similarly to Chat Core, the most important hook action is getNextMessage, but in Chat Headless it only accepts one argument for the input, instead of an object.

Chat UI React

Chat UI React comes with a set of styled UI components that integrate with Chat Headless React. These components come with opinionated styling, but you can override it as needed.

Chat UI React exports four UI components:

• <ChatInput/> - the <input/> where the user types their message.
• <MessageBubble/> - handles the display of the messages, including different colors and alignment for bot vs user, showing timestamps on hover, and rendering markdown.
• <ChatPanel/> - combines the previous two components, handling formatting and other behavior like automatically scrolling to the bottom, etc. The Chat Panel can be used on any screen size - whether small mobile-sized popup or full desktop.
• <ChatPopUp/> - a traditional chat pop-up UI that can be easily placed on a page without affecting existing styling.