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.
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.
_10npm 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.
_10import { AssistantChat } from "@twilio-alpha/assistants-react";_10_10export function App() {_10 return <AssistantChat token="<token>" assistantSid="<assistantSid>" />;_10}
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.
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.
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.
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:
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.
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 |
| 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 |
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: