On this pageProducts used

Connect your AI Assistant to Twilio Conversations with React

(warning)

Twilio Alpha - Developer Preview

AI Assistants is a Twilio Alpha project that's in Developer Preview. To request access, please join the waitlist.

View the current limitations for details about feature limits during developer preview.

While you can use any of Twilio's Conversations SDKs with AI Assistants, there is a dedicated React SDK that provides additional convenience and functionality on top of Twilio Conversations specifically for your AI Assistant use case. The added functionality includes React hooks and UI components powered by Twilio Paste.

This document outlines the steps required to connect your AI Assistant to Twilio Conversations using the React SDK and build a chat interface from the built-in React components.

Setup

Configure Twilio Conversations

The AI Assistants React SDK is built on top of the Twilio Conversations SDK for all messaging communication. To use the SDK, you must first configure a Twilio Conversations service for your AI Assistant.

Generate access tokens

Next, generate client-side access tokens for Twilio Conversations.

When you generate the tokens, the identity used to generate the token will be used for any Customer Memory capabilities that you have enabled.

Install the SDK

The command below uses npm to install the Alpha React and Conversations SDKs.


_10npm install @twilio-alpha/react @twilio/conversations

Use built-in UI components

The React SDK comes with the built-in ability to render a full chat UI by using the <AssistantChat /> component.

To use the component, you will need both a valid Twilio Conversations access token, which you generated in the steps above, and the SID of your Assistant, which you can find in the Assistants section of the Twilio Console. Make sure you replace <token> and <assistantSid> with the respective values.


_10import { AssistantChat } from "@twilio-alpha/assistants-react";
_10
_10export function App() {
_10  return <AssistantChat token="<token>" assistantSid="<assistantSid>" />;
_10}

(warning)

Warning

The access token is not your Twilio Auth Token. It's instead a Twilio Conversations access token. You should generate these on your backend and have your React code fetch the token from your endpoint.

Bring your own UI

If you prefer to use your own UI components with an AI Assistant, you can use the useAssistant hook instead. It returns both a messages array that contains all the messages as well as a sendMessage function to send a new message to your Assistant.

Below is an example of using the useAssistant hook to build a chat UI using only native HTML components.

App.jsx


_30import { useAssistant } from "@twilio-alpha/assistants-react";
_30
_30export function App() {
_30  const { messages, sendMessage } = useAssistant("<token>", {
_30    assistantSid: "<assistantSid>",
_30  });
_30
_30  function send(evt) {
_30    evt.preventDefault();
_30    sendMessage(evt.target.message.value);
_30  }
_30
_30  return (
_30    <>
_30      <ul>
_30        {messages.map((message) => {
_30          return (
_30            <li key={message.sid}>
_30              {message.author}: {message.body}
_30            </li>
_30          );
_30        })}
_30      </ul>
_30      <form onSubmit={send}>
_30        <input type="text" name="message" />
_30        <input type="submit" value="Send message" />
_30      </form>
_30    </>
_30  );
_30}

Reuse existing sessions

By default, every time the <AssistantChat /> component and useAssistant hook are used, it will create a new Twilio conversation (aka a session). If you want to reuse the existing session between page refreshes, you can use the conversationSid property and the onConversationSetup handler to persist the session (for example, via localStorage). This gives you full control of how you want to manage the session. If you do not provide a conversationSid, the component will automatically create one.

App.jsx


_23import { useEffect, useState } from "react";
_23
_23export function App() {
_23  const [conversationSid, setConversationSid] = useState();
_23
_23  useEffect(() => {
_23    // fetches an existing conversation SID from the local storage if it exists
_23    setConversationSid(localStorage.getItem("CONVERSATIONS_SID") || undefined);
_23  }, []);
_23
_23  function saveConversationSid(sid: string) {
_23    localStorage.setItem("CONVERSATIONS_SID", sid);
_23  }
_23
_23  return (
_23    <AssistantChat
_23      token={"<token>"}
_23      conversationSid={conversationSid}
_23      onConversationSetup={saveConversationSid}
_23      assistantSid="<assistantSid>"
_23    />
_23  );
_23}

Use UI Tools to have your Assistant interact with the UI

There are situations where you might want your AI Assistant to not only perform actions in backend systems using APIs, but also interact with the website where the user is chatting with the Assistant. In this case, you can use UI Tools.

You can use this to have the AI Assistant perform these actions, among others:

fill out a form on the page
show a disclaimer
render a richer UI for output from the Assistant

(warning)

Warning

The current solution is limited and only an initial proof of concept. Note that when the AI Assistant triggers a UI Tool, it does not know whether the Tool action succeeded.

To expose UI Tools using the AI Assistants React SDK, pass an object with function handlers into your <AssistantChat /> component or your useAssistant hook using the toolHandlers property, as in the example below.

App.jsx


_10import { AssistantChat } from "@twilio-alpha/assistants-react";
_10
_10function fillForm(data) {
_10  // data will contain the data that the AI Assistant used to trigger the tool
_10  console.log(data);
_10}
_10
_10export function App() {
_10  return <AssistantChat token="<token>" assistantSid="<assistantSid>" toolHandlers={{fillForm}} />;
_10}

For your AI Assistant to call this Tool, you will have to configure the Tool within your Assistant's configuration in the Console. For the fillForm example above, the configuration might look similar to this:

Field	Example Configuration	Notes
Name	Fill sales request form	Use a name that's descriptive to you and the UI the same way as for any other tool. This will not have to match the name of your function. That name gets configured in the URL.
Description	Use this to prepopulate a talk to sales form on behalf of the customer. After you trigger this tool, ask the customer to cross check the request and submit it.	Use this description to tell the AI Assistant when to use the tool.
Input	`{ // anything you want to send to the UI tool }`	The Assistant will pass any data described here to the UI.
Method	`POST`
URL	`https://<your-functions-domain>.twil.io/tools/ui-tools?toolName=<yourUiToolFunction>`	This URL assumes you've deployed the AI Assistants Samples code into your Twilio account using the instructions in the project. The `toolName` value is the name of the function you passed into `toolHandlers`. In this example, it would be `fillForm`

Learn more

You've now connected your AI Assistant to Twilio Conversations and explored the built-in UI from the React SDK, as well as seen how to bring your own UI and have your Assistant interact with the UI. View the links below to learn more about working with your AI Assistant: