Core concepts

Assistants

What an assistant is, how to address one, and which parts of it your code can see.

An assistant is the thing you configured in Studio: instructions, a persona, a model, optionally a voice, optionally a catalogue, and however many knowledge bases you linked to it.

Over the API it is a resource with an id. You do not configure it here — you talk to it.

Addressing one#

Assistants are addressed by their id, a UUID shown on the assistant's page in Studio and returned by GET /v1/assistants.

Code
9f2b1c84-6e3a-4d17-b0c5-2e7a8f41d9b3

This is not the token in a shared link like /a/xk39fq2p. That one is a public routing token, and it can be rotated when a link has been shared too widely. The id cannot, which is exactly why your integration uses it: rotating a link must not break your code.

Draft and published#

An assistant has a status: draft, published, or disabled.

Chat and voice require published. A draft returns 409 with the code assistant_not_published.

That may look strict for a key that already belongs to your workspace, but the person on the other end of your integration is still a member of the public. Publishing is the deliberate act that says "this is ready for them", and an API that quietly bypassed it would make the status meaningless.

Reading is not restricted. GET /v1/assistants lists every assistant with its status, so you can build against a draft's shape before it goes live.

What your code can see#

GET /v1/assistants/{assistant_id} returns everything needed to render a surface without guessing.

JSON
{
  "id": "9f2b1c84-6e3a-4d17-b0c5-2e7a8f41d9b3",
  "name": "Marina sales desk",
  "description": "Answers questions about available units.",
  "status": "published",
  "greeting": "Hi! How can I help you today?",
  "starter_prompts": [
    "What's available under 2M?",
    "How do service charges work?"
  ],
  "channels": { "chat": true, "voice": true },
  "branding": {
    "display_name": "Marina Sales",
    "tagline": "Ask us anything about the development",
    "accent": "#0ea5a4",
    "logo_url": null
  },
  "pre_chat_form": {
    "enabled": true,
    "intro": "So we can follow up:",
    "fields": [
      { "key": "name", "label": "Your name", "type": "text", "required": true },
      { "key": "email", "label": "Email", "type": "email", "required": true }
    ]
  },
  "catalogue": {
    "record_label": "property",
    "record_label_plural": "properties"
  }
}

Read it once at page load and let it drive your interface. Then changing the greeting in Studio changes your product, with nothing to redeploy.

greeting#

The opening line. Show it as the assistant's first message.

It is not a turn: it does not appear in the transcript, and it does not cost tokens. Do not send it back as part of a message.

starter_prompts#

Tappable openers, for a visitor who has not decided what to ask yet. Optional to show, and usually worth it — an empty chat box is the most common place people leave.

channels#

Which doors are switched on. If voice is false, the speech endpoints return 409, so hide the microphone rather than letting someone press it.

branding#

Present so an embedded surface can match its parent. If you are building a bespoke interface you will probably ignore all of it, which is fine — it is offered, not imposed.

pre_chat_form#

If enabled, collect these fields before opening a session and pass them as visitor. Required fields are enforced server-side: a session request without them returns 422.

Their real value arrives later. The answers land on the session, so Assistant history in Studio shows a name and an email beside the conversation instead of an anonymous transcript.

catalogue#

Present only when a catalogue is attached, and only as its vocabulary — the singular and plural nouns the assistant uses. Use them in your own copy so a button says "Compare properties" rather than "Compare records".

No schema, no field list, no ids. What a catalogue actually returns arrives in the canvas event when a search runs.

What your code cannot see#

Not exposed, and not by omission:

  • The system prompt. Your instructions are your competitive position; they do not travel to a browser via an endpoint that a proxy might forward.
  • Model and provider. Which model answers is configuration, and code that branches on it breaks the day you change it in Studio.
  • Credentials. Obviously.
  • Webhook tool definitions. Your endpoints and their parameters.

You will see the effects of all of this — that a tool ran, and what it returned — in the chat stream.

One assistant, many surfaces#

Nothing stops an assistant serving its shared link, an embedded widget and your API integration at once. They are three doors into the same configuration.

Conversations are labelled by which door they came through, so Assistant history and API → Usage can tell them apart. Limits do not blur either: API traffic is governed by rate limits on your key, and the public link keeps its own separate budget. A busy integration cannot exhaust your shared link, and a viral link cannot throttle your product.

Next#