customer-agent/docs/settings-reference.md

# Settings reference

## Agent settings (admin)

| Setting | Required | Description |
|---------|----------|-------------|
| **Name** | Yes | Business name shown in the chat header |
| **Greeting** | No | First bot message; default is generated from the name |
| **Voice instructions** | No | Tone and style for the model |
| **Escalation email** | Recommended | Email for leave-a-message handoffs (SMTP must be configured by Synderesis) |
| **Escalation URL** | No | Optional visitor-facing link (contact form, Calendly…) |
| **Escalation webhook** | Optional | HTTPS URL for signed JSON events (`X-Synderesis-Signature`) |
| **Allowed origins** | Yes for production | Comma-separated site origins, e.g. `https://www.myshop.com`. Use `*` only for testing |
| **Status** | — | `active` or `disabled` (via API; admin can delete) |
| **Readiness** | Auto | Checklist: name, handoff, knowledge, origins, production lock |
| **Brand colour** | No | Hex e.g. `#2e4a86` — colours the bubble / buttons |
| **Bubble position** | No | `left` or `right` (default right) |
| **Logo URL** | No | HTTPS image for the chat avatar |
| **Launcher label** | No | Optional text on the floating button |

## Knowledge

| Setting | Description |
|---------|-------------|
| **Title** | Label for a document (e.g. “Shipping FAQ”) |
| **Body** | Plain text content (upload multiple docs) |
| **File upload** | `.txt` / `.md` / `.csv` / `.pdf` via admin |
| **Page URL** | Public `https://` page import (SSRF-safe; no private IPs) |
| **Source type** | `manual`, `file`, `url` (CMS auto-sync later) |
| **Coverage** | Admin panel + `GET /v1/agents/{id}/coverage` — unknown questions |

Limits (server-side): max documents per agent, max characters per document — see API if you hit errors.

## Public site key

| Action | Effect |
|--------|--------|
| **Create agent** | Issues a new `pk_live_…` key (shown once) |
| **Rotate site key** | Old key stops working; new key shown once |
| **Embed snippet** | Ready-to-paste HTML using the current base URL |

## Embed `data-*` attributes

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `data-site-key` | **Yes** | — | Public `pk_live_…` key |
| `data-api-base` | Recommended | Script origin | API origin, e.g. `https://www.synderesis.eu` |
| `data-open` | No | off | `1` opens the panel on load |
| `data-chips` | No | built-in | Suggestion buttons, `\|`-separated |
| `data-color` | No | from agent | Override brand hex colour |
| `data-position` | No | from agent | `left` or `right` |

## WordPress plugin settings

| Setting | Description |
|---------|-------------|
| **Enable** | Inject widget sitewide |
| **Site key** | `pk_live_…` |
| **API base URL** | Usually `https://www.synderesis.eu` |
| **Open on load** | Optional |
| **Suggestion chips** | Optional custom chips |

## What webmasters never configure

- Hugging Face / OpenRouter / model names
- Retrieval databases
- Secret API keys
- Server deploy

Those stay with Synderesis operators.