Building
Agents
An agent is one assistant, with its own name, appearance, keys and assigned material. Most accounts need only one. Several become necessary when different audiences must not share the same answers.
Creating an agent
Creation asks for very little, because behaviour comes from your material rather than from configuration.
| Field | Required | Limit | Notes |
|---|---|---|---|
| Name | Yes | 1 to 100 characters | Shown in the widget header, so write it for visitors rather than for your own records |
| Description | No | Up to 500 characters | Internal only. Visitors never see it |
| Appearance | No | Light or dark | Sets the widget surface, meaning its header and message colours |
| Tone | No | Five modes | Adaptive is the default; changes style, not factual authority |
An agent starts with no keys, so nothing is issued automatically. Create a secret key for server calls, or create a widget installation to get a publishable key and its embed snippet, both on the API Keys(sign in required) page. Create your first agent on the Agents(sign in required) page.
How many agents you may have at once depends on your plan. See Plans and Usage.
Tone
Tone controls how an agent phrases an answer. It does not change which sources it can use, make unsupported claims acceptable, or act as a custom prompt.
| Mode | Answer style |
|---|---|
| Adaptive | Matches how each visitor writes; the default |
| Professional | Polished, clear, and neutral |
| Friendly | Warm and approachable |
| Casual | Relaxed, everyday language |
| Concise | Short answers, straight to the point |
Test your selected tone with both a well-covered question and an unsupported one in the Playground.
Agent limits
| Plan | Maximum agents |
|---|---|
| Starter | 1 |
| Lite | 2 |
| Pro | 5 |
| Business | 20 |
| Enterprise | By contract |
These are account limits. More agents can separate audiences or knowledge scope, but they share the account's request quota and per-minute throughput.
Appearance
The light and dark choice is what the dashboard exposes today, and it drives the colours the hosted widget renders. The remaining display values below have sensible defaults and are returned by the appearance endpoint, which is what the widget reads and what your own interface can read too.
| Value | Default |
|---|---|
| Surface | Dark |
| Launcher position | Bottom right |
| Corner style | Rounded |
| Welcome message | Hi! How can I help you today? |
| Input placeholder | Type your message... |
If you are building your own interface, read these values rather than copying them into your code, so an agent stays consistent with what its owner configured. See Official SDK or REST API.
Status
An agent is either active or inactive, and the switch takes effect everywhere at once.
- Active. It answers on the widget, the SDK and the API.
- Inactive. It refuses every request on every surface, including the Playground, while keeping its material, its keys and its installations intact.
Deactivating is the right move for taking an assistant down temporarily, during a content rewrite for example. Deleting is not reversible.
Editing and deleting
Renaming an agent or changing its appearance takes effect on the next page load for embedded widgets, and immediately for your own interface. Neither affects its keys.
Deleting an agent is permanent. Its keys stop working straight away, so any site still embedding them will show a refused request rather than a chat bubble. Deactivate first if you are not certain.
Getting it in front of visitors
Each installation on the API Keys(sign in required)page provides the embed snippet, prefilled with its publishable key. For a website that snippet is all you need, once the site's origin is on the installation's allowed origins.
| Goal | Read next |
|---|---|
| Drop a chat bubble on a website | Embed widget |
| Build a custom chat interface | Official SDK |
| Call it from a backend or an automation | REST API |
| Decide which sites may use the key | Allowed origins |
An agent with no material will answer, but it will decline almost everything, because it has no material to answer from. Attach a knowledge base before you launch. Questions it cannot answer from the available material are listed on the Knowledge Gaps(sign in required) page.
Keys are created, rotated and revoked on the API Keys(sign in required) page, one at a time. Rotating a key issues a replacement of the same class and leaves the other class alone, and the previous value stops working immediately, so update wherever that one key is deployed. The prefixes are wcx_pk_ for a publishable key and wcx_sk_ for a secret key.
Give an agent the name a visitor should see, not the name your team uses internally. It appears in the widget header, and "Support" is clearer to a customer than "prod-bot-v2".
Appearance control is currently the light and dark surface choice. The other display values listed above exist with the defaults shown and are returned by the appearance endpoint, but there is no editor for them yet, so treat them as fixed for now rather than as settings you can tune.