Connect your AI Assistant to Twilio Conversations with React

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.

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.

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

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

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.

1
import { AssistantChat } from "@twilio-alpha/assistants-react";
2

3
export function App() {
4
  return <AssistantChat token="<token>" assistantSid="<assistantSid>" />;
5
}

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.

1
import { useAssistant } from "@twilio-alpha/assistants-react";
2

3
export function App() {
4
  const { messages, sendMessage } = useAssistant("<token>", {
5
    assistantSid: "<assistantSid>",
6
  });
7

8
  function send(evt) {
9
    evt.preventDefault();
10
    sendMessage(evt.target.message.value);
11
  }
12

13
  return (
14
    <>
15
      <ul>
16
        {messages.map((message) => {
17
          return (
18
            <li key={message.sid}>
19
              {message.author}: {message.body}
20
            </li>
21
          );
22
        })}
23
      </ul>
24
      <form onSubmit={send}>
25
        <input type="text" name="message" />
26
        <input type="submit" value="Send message" />
27
      </form>
28
    </>
29
  );
30
}

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.

1
import { useEffect, useState } from "react";
2

3
export function App() {
4
  const [conversationSid, setConversationSid] = useState();
5

6
  useEffect(() => {
7
    // fetches an existing conversation SID from the local storage if it exists
8
    setConversationSid(localStorage.getItem("CONVERSATIONS_SID") || undefined);
9
  }, []);
10

11
  function saveConversationSid(sid: string) {
12
    localStorage.setItem("CONVERSATIONS_SID", sid);
13
  }
14

15
  return (
16
    <AssistantChat
17
      token={"<token>"}
18
      conversationSid={conversationSid}
19
      onConversationSetup={saveConversationSid}
20
      assistantSid="<assistantSid>"
21
    />
22
  );
23
}

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

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.

1
import { AssistantChat } from "@twilio-alpha/assistants-react";
2

3
function fillForm(data) {
4
  // data will contain the data that the AI Assistant used to trigger the tool
5
  console.log(data);
6
}
7

8
export function App() {
9
  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:

{
  // anything you want to send to the UI tool
}

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:

• View a Next.js example application
• Learn how to have your AI Assistant transition a conversation to a Flex agent
• Learn how to have your AI Assistant transition a conversation to a Studio flow