> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/ai/products/ai-chat.md).

# AI chat

AI chat for the end users of your app — in the Admin Portal or in your own app through the SDK; what it can see, how to switch it on, and a turn run from code.

Your users want to ask "what is my profile?" or "show my last orders" and get an answer, not a form. A chat for end users must answer only about **that** user, stay inside a monthly budget, and never let a clever prompt reach someone else's data.

## How Norbix models it

The end-user chat runs on the **API host** of your project, as the signed-in **end user** (a project user from Membership):

| Piece                   | What it is                                                                                                                                                                       |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assistant** (`ast_…`) | Name, welcome message, system prompt, the toolsets it may use, optionally its own model. One is the default.                                                                     |
| **Toolsets**            | Only `own:records` (the user's own records), `own:profile` and `own:preferences`. Each tool is stamped with the caller's own user id; a call that names another user is refused. |
| **Session** (`aics_…`)  | One chat; listed, renamed, pinned, archived and deleted per user.                                                                                                                |
| **Turn** (`trn_…`)      | One question. `POST /v3/ai/chat/turn` answers at once with the turn id; the answer is then stored in the session and streamed as `ai.chat.turn.*` events.                        |
| **LLM**                 | The assistant's own, else the project default — see [LLM providers](/codemash/ai/products/llm-providers.md) (LLM = large language model).                                        |
| **Plan**                | Optional monthly quota per user, by role; [AI triggers](/codemash/ai/products/ai-triggers.md) fire at 80 % and 100 %.                                                            |

| Where your users chat | How                                                                                                                                                                                                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin Portal**      | Ready-made: the chat drawer appears when the chat is on — see [Admin → AI chat](/codemash/admin/admin/ai-chat.md).                                                                                                                                                |
| **Your own app**      | The SDK's `norbix.api.ai.*` methods, signed in as the end user (below).                                                                                                                                                                                           |
| **Cloud**             | No chat screen: Cloud's chat drawer is switched off in this release, and Cloud shows **Connect your AI** instead, for your own coding agent. Your team's chat (the Hub chat) runs through the SDK and CLI — see [Cloud → AI chat](/codemash/cloud/ai/ai-chat.md). |

### Switch it on

1. Connect an LLM that can chat — OpenAI, Groq, Mistral, OpenRouter or Grok ([LLM providers](/codemash/ai/products/llm-providers.md)).
2. On Project → Settings → [AI](/codemash/cloud/project/settings/ai.md), pick the **Default LLM** and **Add assistant** with the toolsets it may use (for example **Own records** and **Own profile**).
3. Show the chat: Project → Settings → **Admin Portal** → **Show AI chat**.
4. Your end user needs a role that allows the chat — the built-in **Authenticated** role does.

### A turn from your app

Run on a test project with the steps above (an OpenAI-shaped test model, assistant **Support** with Own records and Own profile), signed in as the end user *Ada Lovelace*:

```ts
import { Norbix } from '@norbix.ai/ts';

// bearerToken: the end user's sign-in token (Membership sign-in on the API host)
const norbix = new Norbix({ bearerToken, projectId });

const av = await norbix.api.ai.getEndUserChatAvailability();
// { enabled: true, available: true, assistants: [{ name: 'Support', … }] }

const turn = await norbix.api.ai.startEndUserChatTurn({ message: 'What is my profile?' });
// { turnId: 'trn_…', sessionId: 'aics_…', channel: 'ai-chat:pr_…:usr_…' }

// a few seconds later
const entries = await norbix.api.ai.getEndUserChatEntries({ sessionId: turn.sessionId });
```

The entries of that session:

```json
[
  ["user.message", "What is my profile?"],
  ["assistant.text", "Here is your profile: Ada Lovelace (ada.mux2auu4@example.test). Tell me if something there is wrong, and I will help you change it."]
]
```

(Shown as `[kind, text]` pairs.) To show the answer while it is written, open `norbix.aiChat({ authId })` — the stream of the channel above — and listen to `ai.chat.turn.token` and `ai.chat.turn.completed`.

{% hint style="warning" %}
On our test installation the `norbix.aiChat` stream opened but no `ai.chat.turn.*` event arrived, while the answer was stored as shown. Read the answer with `getEndUserChatEntries` (poll every second or two until an `assistant.text` entry appears) until the stream is confirmed.
{% endhint %}

When the chat cannot run, `getEndUserChatAvailability` says so: `available: false` and a `reason` (a `CM-ERRORS-AI-CHAT-…` code) — for example the chat is off, there is no assistant, or no LLM. A failed turn itself only says *Error while running chat turn*; the cause is in the Hub log.

## Where you use it

* Cloud: Project → Settings → [AI](/codemash/cloud/project/settings/ai.md) · [AI integrations](/codemash/cloud/ai.md) · [Cloud → AI chat](/codemash/cloud/ai/ai-chat.md)
* [Admin → AI chat](/codemash/admin/admin/ai-chat.md) — the portal with the chat built in · API: [Start End User Chat Turn](/codemash/api-reference/ai/chat/start-end-user-chat-turn.md) · [Get End User Chat Entries](/codemash/api-reference/ai/chat/get-end-user-chat-entries.md)
* [LLM providers](/codemash/ai/products/llm-providers.md) · [MCP servers](/codemash/ai/products/mcp-servers.md) · [AI triggers](/codemash/ai/products/ai-triggers.md)
* SDK: [AI](/codemash/sdks/ai.md) · API: [AI](/codemash/api-reference/ai.md)