# Connect your AI Assistant to Twilio Conversations with React

> \[!WARNING]
>
> AI Assistants is a [Twilio Alpha](https://twilioalpha.com) project that's in **Developer Preview**.
>
> View the [current limitations](/docs/alpha/ai-assistants/pricing-and-limits) for details about feature limits during developer preview.

While you can use any of [Twilio's Conversations SDKs](/docs/conversations/sdk-overview) 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](https://paste.twilio.design).

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](/docs/conversations/sdk-overview) for all messaging communication. To use the SDK, you must first [configure a Twilio Conversations service for your AI Assistant](/docs/alpha/ai-assistants/code-samples/channel-conversations).

### Generate access tokens

Next, [generate client-side access tokens for Twilio Conversations](/docs/conversations/create-tokens).

When you generate the tokens, the `identity` used to generate the token will be used for any [Customer Memory](/docs/alpha/ai-assistants) capabilities that you have enabled.

### Install the SDK

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

```bash
npm install @twilio-alpha/assistants-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](https://console.twilio.com/us1/develop/ai-assistants/assistants). Make sure you replace `<token>` and `<assistantSid>` with the respective values.

```jsx
import { AssistantChat } from "@twilio-alpha/assistants-react";

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

> \[!WARNING]
>
> The access token is **not** your Twilio Auth Token. It's instead a [Twilio Conversations access token](/docs/conversations/create-tokens). 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.

```jsx App.jsx
import { useAssistant } from "@twilio-alpha/assistants-react";

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

  function send(evt) {
    evt.preventDefault();
    sendMessage(evt.target.message.value);
  }

  return (
    <>
      <ul>
        {messages.map((message) => {
          return (
            <li key={message.sid}>
              {message.author}: {message.body}
            </li>
          );
        })}
      </ul>
      <form onSubmit={send}>
        <input type="text" name="message" />
        <input type="submit" value="Send message" />
      </form>
    </>
  );
}
```

## 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`](https://developer.mozilla.org/en-US/docs/Web/API/Window/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.

```jsx App.jsx
import { useEffect, useState } from "react";

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

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

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

  return (
    <AssistantChat
      token={"<token>"}
      conversationSid={conversationSid}
      onConversationSetup={saveConversationSid}
      assistantSid="<assistantSid>"
    />
  );
}
```

## 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]
>
> 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.

```jsx App.jsx
import { AssistantChat } from "@twilio-alpha/assistants-react";

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

export function App() {
  return <AssistantChat token="<token>" assistantSid="<assistantSid>" toolHandlers={{fillForm}} />;
}
```

For your AI Assistant to call this Tool, you will have to [configure the Tool within your Assistant's configuration in the Console](/docs/alpha/ai-assistants/tools). 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       | <pre lang="typescript"><code>\{<br />  // anything you want to send to the UI tool<br />}</code></pre>                                                          | 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](https://github.com/twilio-labs/ai-assistants-samples) into your Twilio account using the instructions in the project. <br /><br /> 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:

* [View a Next.js example application](https://github.com/twilio-labs/ai-assistants-js/blob/main/examples/next-js-example/src/app/page.tsx)
* [Learn how to have your AI Assistant transition a conversation to a Flex agent](/docs/alpha/ai-assistants/code-samples/transition-flex)
* [Learn how to have your AI Assistant transition a conversation to a Studio flow](/docs/alpha/ai-assistants/code-samples/transition-studio)