Skip to main content

Assistants: Quick start

In this guide, you’ll learn how to integrate a Dopt-powered AI Assistant into your product.

1. Sign up for a free Dopt account​

To get a free Dopt account, sign up here.

2. Identify users to Dopt​

Dopt requires you to identify users so we can provide analytics on who's seen what and also allow you to target users via user or group properties.

You’ll need your users API key to start identifying users. You can retreive that by going to the Settings page and then navigating to Environments. We’ll use the Development environment so click Development and then the Generate API key button. After the key is generated, copy it to a safe place.

For this example, we’ll identify a user using the users API via a cURL command:

curl 'https://users.dopt.com/identify' \
 -X POST \
 -H 'Content-Type: application/json' \
 -H 'x-api-key:$USERS_API_KEY' \
 -d '{
  "identifier": "example_user",
  "properties": {
    "name": "Example User",
    "email": "user@example.com"
  }
}'

We’ve now identified a user called example_user with a name and an email property.

3. Create an Assistant​

We’ll create a assistant in Dopt.

Navigate to the assistant page and click the Create assistant button. Set the identifier to my-first-assistant.

4. Create the example app​

Run the following command in your terminal:

npm create @dopt/example@latest -- --template assistant-quick-start

This will create a new project in a folder named dopt-example-assistant-quick-start.

Next, run the following commands to start the app:

cd dopt-example-assistant-quick-start
npm run dev

5. Install Dopt​

Install the Dopt AI Assistant SDK​

Run the following command to install the Dopt AI Assistant SDK.

npm install @dopt/ai-assistant-react

Initialize Dopt​

We now need to initialize Dopt by adding the DoptAiProvider to the example app.

First, you’ll need your AI API key.

You can retreive that by going to the Settings page and then navigating to Environments. We’ll use the Development environment so click Development and then copy the AI API key.

Open src/main.tsx in the project and import DoptAiProvider from @dopt/ai-assistant-react. Wrap the provider around the <App /> element. The provider requires us to define userId, apiKey.

  • Set userId to example_user. This is the user we identified to Dopt in step 2.
  • Set apiKey to the AI API key you retreived earlier.

Your final code should look like this:

src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';

import { DoptAiProvider } from '@dopt/ai-assistant-react';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <DoptAiProvider
      userId="example_user"
      apiKey="YOUR_AI_API_KEY"
    >
      <App />
    </DoptAiProvider>
  </React.StrictMode>
);

6. Add the contextual AI Assistant​

Install the react contextual assistant​

Run the following command to install the react contextual assistant component:

npm install @dopt/react-contextual-assistant

Initialize the provider and add the highlight component​

We now need to initialize the contextual assistant's provider and add its highlight component.

Open src/main.tsx in the project and import ContextualAssistant from @dopt/react-contextual-assistant.

The ContextualAssistant is a default export with a family of components in it.

In this step, we are going to leverage the ContextualAssistant.Provider and ContextualAssistant.Highlight components.

This ContextualAssistant.Provider should go inside the DoptAiProvider and the ContextualAssistant.Highlight inside of the ContextualAssistant.Provider. These components should wrap around the <App /> element.

The contextual assistant provider requires us to define an assistant prop, which we can set to the assistant's identifier we created earlier.

  • Set assistant to my-first-assistant.

Your final code should look like this:

src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';

import { DoptAiProvider } from '@dopt/ai-assistant-react';

import ContextualAssistant from '@dopt/react-contextual-assistant';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <DoptAiProvider
      userId="example_user"
      apiKey="YOUR_AI_API_KEY"
    >
      <ContextualAssistant.Provider assistant="my-first-assistant">
        <ContextualAssistant.Highlight>
          <App />
        </ContextualAssistant.Highlight>
      </ContextualAssistant.Provider>
    </DoptAiProvider>
  </React.StrictMode>
);

Render the assistant popover​

We can now add contextual assistant popover to the page.

Open src/App.tsx in the project and import the default export ContextualAssistant and useContextualAssistant from @dopt/react-contextual-assistant.

import ContextualAssistant, {
  useContextualAssistant
} from '@dopt/react-contextual-assistant';

Use the useContextualAssistant hook to activate the contextual assistant on button click.

First, instantiate the hook.

const contextualAssistant  = useContextualAssistant();

Then add a button to the header element that enables the contextual assistant.

<button onClick={() => contextualAssistant.setActive(true)}>
  Assist! (⌘E){contextualAssistant.active && ' ✅'}
</button>

At this point, clicking the button should enable the hover interaction. Press the Escape key to exit it.

Now, let's add the contextual assistant popover and show it once a selection has been made. You can add this anywhere in the jsx of src/App.tsx. In this example, we'll add it to the top of jsx.

{contextualAssistant.selection && (
  <ContextualAssistant.Popover
    position="right"
    alignment="start"
    anchor={contextualAssistant.selection}
  >
    <ContextualAssistant.Content>
      <ContextualAssistant.Header>
        <ContextualAssistant.Title>
          ✨ AI assistant
        </ContextualAssistant.Title>
        <ContextualAssistant.DismissIcon
          onClick={() => contextualAssistant.close()}
        />
      </ContextualAssistant.Header>
      <ContextualAssistant.Body>
        {contextualAssistant.answer || contextualAssistant.content ? (
          <ContextualAssistant.Answer>
            {contextualAssistant.answer || contextualAssistant.content}
          </ContextualAssistant.Answer>
        ) : (
          <div style={{ display: 'grid', gap: 8 }}>
            <ContextualAssistant.Skeleton />
            <ContextualAssistant.Skeleton width="85%" />
            <ContextualAssistant.Skeleton width="95%" />
          </div>
        )}
        {contextualAssistant.documents &&
          contextualAssistant.documents.length > 0 && (
            <>
              <ContextualAssistant.BodyHeading>
                Sources
              </ContextualAssistant.BodyHeading>
              <ContextualAssistant.Sources>
                {contextualAssistant.documents.map(
                  ({ url, title, id }) => (
                    <ContextualAssistant.Source
                      key={id}
                      url={url}
                      index={id}
                    >
                      {title}
                    </ContextualAssistant.Source>
                  )
                )}
              </ContextualAssistant.Sources>
            </>
          )}
      </ContextualAssistant.Body>
    </ContextualAssistant.Content>
  </ContextualAssistant.Popover>
)}

Now, when you enable the contextual assistant and click and element you should see a popover with the Assistant's response.

Your final code should look like this:

src/App.tsx
import React from 'react';

import ContextualAssistant, {
  useContextualAssistant,
} from '@dopt/react-contextual-assistant';

function App() {
  const contextualAssistant = useContextualAssistant();
  return (
    <>
      {contextualAssistant.selection && (
        <ContextualAssistant.Popover
          position="right"
          alignment="start"
          anchor={contextualAssistant.selection}
        >
          <ContextualAssistant.Content>
            <ContextualAssistant.Header>
              <ContextualAssistant.Title>
                ✨ AI assistant
              </ContextualAssistant.Title>
              <ContextualAssistant.DismissIcon
                onClick={() => contextualAssistant.close()}
              />
            </ContextualAssistant.Header>
            <ContextualAssistant.Body>
              {contextualAssistant.answer || contextualAssistant.content ? (
                <ContextualAssistant.Answer>
                  {contextualAssistant.answer || contextualAssistant.content}
                </ContextualAssistant.Answer>
              ) : (
                <div style={{ display: 'grid', gap: 8 }}>
                  <ContextualAssistant.Skeleton />
                  <ContextualAssistant.Skeleton width="85%" />
                  <ContextualAssistant.Skeleton width="95%" />
                </div>
              )}
              {contextualAssistant.documents &&
                contextualAssistant.documents.length > 0 && (
                  <>
                    <ContextualAssistant.BodyHeading>
                      Sources
                    </ContextualAssistant.BodyHeading>
                    <ContextualAssistant.Sources>
                      {contextualAssistant.documents.map(
                        ({ url, title, id }) => (
                          <ContextualAssistant.Source
                            key={id}
                            url={url}
                            index={id}
                          >
                            {title}
                          </ContextualAssistant.Source>
                        )
                      )}
                    </ContextualAssistant.Sources>
                  </>
                )}
            </ContextualAssistant.Body>
          </ContextualAssistant.Content>
        </ContextualAssistant.Popover>
      )}
      <header>
        <button onClick={() => contextualAssistant.setActive(true)}>
          Activate Assist! (⌘E){contextualAssistant.active && ' ✅'}
        </button>
      </header>
      <main>
        <input type="text" defaultValue="Some text input" />
        <button>Some button</button>
        <select>
          <option>Some select</option>
          <option>Some select</option>
          <option>Some select</option>
          <option>Some select</option>
        </select>

        <textarea defaultValue="Some text area" />

        <input type="range" />

        <input type="color" />

        <label>
          <input type="checkbox" />
          Some checkbox
        </label>

        <div>Some div (non-interactive)</div>

        <a href="#">Some link</a>

        <div role="button">Some div with a button role</div>

        <div>
          <button>
            <span>Some</span> <span>nested</span> <span>button</span>
          </button>
        </div>

        <ul>
          <li>List</li>
          <li>List</li>
          <li>List</li>
        </ul>

        <form>
          <div>
            <label>Label</label>
            <br />
            <input type="text" defaultValue="Text" />
          </div>
          <div>
            <label>Label</label>
            <br />
            <select>
              <option>Select</option>
              <option>Select</option>
              <option>Select</option>
            </select>
          </div>
          <div>
            <label>
              <input type="radio" defaultChecked />
              Radio
            </label>
            <label>
              <input type="radio" />
              Radio
            </label>
          </div>
          <div>
            <button>Submit</button>
          </div>
        </form>

        <table>
          <thead>
            <tr>
              <th>Header</th>
              <th>Header</th>
              <th>Header</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>Cell</td>
              <td>Cell</td>
              <td>Cell</td>
            </tr>
            <tr>
              <td>Cell</td>
              <td>Cell</td>
              <td>Cell</td>
            </tr>
            <tr>
              <td>Cell</td>
              <td>Cell</td>
              <td>Cell</td>
            </tr>
          </tbody>
        </table>
      </main>
    </>
  );
}

export default App;

7. See everything in action​

Navigate to http://localhost:5173 and you should see a modal rendered on the page.

You’ve accomplished quite a few things!

  1. You’ve provided user and API key to the DoptAiProvider so Dopt knows who is using the assistant
  2. You’ve provided assistant id to the ContextualAssistant.Provider so we know which assistant should be leveraged
  3. You’ve bound the activation of the assistant to a button click
  4. You’ve bound the assistant popover visibility to a users selection with the contextual assistant

Next steps​