Projects

A chat project is a self-contained chat setup: its own appearance and messages, its own agents, and its own conversation queue. An organization that runs one site needs exactly one, and that one already exists, so nothing here is required reading to get started.

Reach for a second project when you run a second site or brand and you do not want the two streams of conversations mixed together. Agents can be restricted to a subset of projects, so a team handling one brand never sees another brand's customers.

Which project a chat opens inlink

The API key decides, and only the API key. The client never names a project. In customer token mode it is the key that minted the token: the project is signed into the token at mint time. In key mode it is the key the app sends.

Whatever reaches the client can be read by anyone who can open the page or unpack the app. If the client could also name a project, anyone could open conversations against any project in your organization, or read another project's configuration. So the server ignores any project the client offers and reads it from the key alone.

That leads to one rule: issue one key per project.

Existing integrations keep workinglink

Every key issued before chat projects existed is bound to no project, so it falls into row two and resolves to the default project. That is the same data it always read and wrote. No redeploy of any widget or app is needed. This applies to the web widget and to the Android, iOS, React Native and Flutter SDKs equally, whichever auth mode they use, including deployed embeds that still pass the deprecated bare key ID.

Binding a key to a projectlink

In the dashboard, open API Keys, create or edit a key, choose Chat among its products, and pick the project from the picker that appears. Leave it on Organization default project to keep the fallback behaviour.

No client code changes: tokens minted with the key, the key itself in key mode, and deployed embeds that pass its bare key ID all resolve to the project you picked.

curl -X POST "{{baseUrl}}/api/v1/chat/sessions" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_storefront_key:YOUR_SECRET_KEY" \
  -d '{ "customerId": "usr_123", "customerName": "Ada Lovelace" }'

Use a different key for each site, mint each site's customer tokens with that site's key, and each site's conversations land in its own project.

Plan limitslink

Projects are included in your plan rather than billed separately, and each plan allows a set number. Creating one past that limit returns RESOURCE_LIMIT_EXCEEDED and names the current limit. Deleting a project frees its slot.

A project that still holds conversations cannot be deleted, and the default project cannot be deleted at all, since it is what unbound keys fall back to.