> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# Control the AI Assistant from your code

> Get the AI Assistant store dispatcher, send messages, reset the thread, manage conversations, switch agents and context, and migrate from makeUserMessage to makeUserItem.

API reference: [useGenAiDispatcher()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.usegenaidispatcher/index.md) (function), [makeUserItem()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.makeuseritem/index.md) (function)

Drive the AI Assistant from your application by dispatching actions to its store. The [list of actions](https://www.gooddata.ai/docs/gooddata-ui/latest/ai-modules/ai-assistant/index.md#available-actions) is on the reference page.

## [Get the dispatcher](https://www.gooddata.ai/docs/gooddata-ui/latest/ai-modules/control-ai-assistant/#get-the-dispatcher)

Take the dispatcher from the `onDispatcher` callback of [`GenAIAssistant`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.genaiassistant/index.md) or [`GenAiStore`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.genaistore/index.md):

```tsx
import { useState } from "react";
import { GenAIAssistant, type GenAIAssistantProps } from "@gooddata/sdk-ui-gen-ai";

type ChatDispatcher = Parameters<NonNullable<GenAIAssistantProps["onDispatcher"]>>[0];

export const App = () => {
    const [dispatcher, setDispatcher] = useState<ChatDispatcher | null>(null);

    return <GenAIAssistant onDispatcher={(dispatch) => setDispatcher(() => dispatch)} />;
};
```

Inside a [`GenAiStore`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.genaistore/index.md), call the `useGenAiDispatcher` hook instead:

```tsx
import { useGenAiDispatcher, startNewConversationAction } from "@gooddata/sdk-ui-gen-ai";

const MyComponent = () => {
    const dispatch = useGenAiDispatcher();

    const handleNewConversation = () => {
        dispatch(startNewConversationAction());
    };

    return <button onClick={handleNewConversation}>New Conversation</button>;
};
```

## [Reset the chat thread](https://www.gooddata.ai/docs/gooddata-ui/latest/ai-modules/control-ai-assistant/#reset-the-chat-thread)

Dispatch `clearThreadAction`:

```tsx
import { clearThreadAction } from "@gooddata/sdk-ui-gen-ai";

// Retrieve dispatcher from chat UI
dispatcher(clearThreadAction());
```

## [Send messages and manage conversations](https://www.gooddata.ai/docs/gooddata-ui/latest/ai-modules/control-ai-assistant/#send-messages-and-manage-conversations)

The examples below use `dispatcher` from the previous section. `conversation` is an [`IChatConversationLocal`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.ichatconversationlocal/index.md), for example from `useGenAiCurrentConversation`, and `userContext` is an `IGenAIUserContext`.

```tsx
import {
    clearThreadAction,
    startNewConversationAction,
    setCurrentConversationAction,
    setFullscreenAction,
    newMessageAction,
    pinConversationAction,
    renameConversationAction,
    deleteConversationAction,
    setSelectedAgentAction,
    setAmbientUserContextAction,
    setUserContextAction,
    makeUserItem,
} from "@gooddata/sdk-ui-gen-ai";

// Retrieve dispatcher from chat UI

// Clear thread action
dispatcher(clearThreadAction());
// For case with single conversation only
dispatcher(newMessageAction(makeUserItem({ type: "text", text: "Hello" })));
// For case with multiple conversations
dispatcher(startNewConversationAction());
dispatcher(setCurrentConversationAction({ conversation }));
dispatcher(newMessageAction(makeUserItem({ type: "text", text: "Hello" })));

// Switch the assistant to the fullscreen layout
dispatcher(setFullscreenAction({ isFullscreen: true }));

// Pin/unpin conversation
dispatcher(pinConversationAction({ conversation, pinned: true }));

// Rename conversation
dispatcher(renameConversationAction({ conversation, title: "Weekly performance review" }));

// Delete conversation
dispatcher(deleteConversationAction({ conversation }));

// Change assistant agent
dispatcher(setSelectedAgentAction({ agentId: "new-agent-id", showChangeEvent: true }));

// Set ambient user context
dispatcher(setAmbientUserContextAction({ userContext }));

// Set or merge user context
dispatcher(setUserContextAction({ userContext, replaceUserContext: true }));
```

## [Migrate from makeUserMessage to makeUserItem](https://www.gooddata.ai/docs/gooddata-ui/latest/ai-modules/control-ai-assistant/#migrate-from-makeusermessage-to-makeuseritem)

If your integration still sends messages like this:

```tsx
dispatcher(newMessageAction(makeUserMessage([makeTextContents("Hello", [])])));
```

Migrate to `makeUserItem`:

```tsx
dispatcher(newMessageAction(makeUserItem({ type: "text", text: "Hello" })));
```

When migrating, remove `makeUserMessage` and `makeTextContents` from imports and use `makeUserItem` for new user chat items.