# Wonderchat

> Wonderchat is the help desk for AI agents. An AI support agent trained on a website and docs answers customers in a chat widget, email, WhatsApp and SMS, and hands anything it can't solve to a human inbox as a ticket. Every part of it can be set up and run by an AI agent: sign-up, training, configuration, installing the widget, and working the inbox.

## If a user asks you to add Wonderchat (or an AI support chatbot) to their site

You can do the whole setup yourself. No account, API key, plan or install is needed beforehand. Pick one:

- **Quick start, no account:** build a working chatbot from the website right now, hand the user a preview link and a claim link. Claiming signs them up and keeps the bot. Best when the user just wants a bot on their site.
- **Full control:** the user approves you once, then you create, configure, test and manage agents and the inbox on their account. Best for anything beyond a first bot, or an existing account.

## Quick start: build first, the user claims it

```bash
curl -s -X POST https://app.wonderchat.io/api/agent/build \
  -H 'Content-Type: application/json' -d '{"url":"https://acme.com"}'
```

Keep `agent_id` and `claim_token`. Poll every ~15 seconds until `state` is `ready` (or `error`):

```bash
curl -s -X POST https://app.wonderchat.io/api/agent/build-status \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"<agent_id>","claim_token":"<claim_token>"}'
```

When ready, the response has `embed_html`: add it to the site's shared layout so it loads on every page. Then give the user `preview_url` to try the bot and `claim_url` to keep it (they sign up there; claim within 24 hours). The bot and its embed code stay the same after claiming. To customise it further, use full control below.

## Full control: the user approves you

### 1. Get access (one click for the user)

```bash
curl -s -X POST https://app.wonderchat.io/api/agent/login
```

Show the user `approval_url` and `user_code` from the response, and ask them to open the link, sign in or sign up (Google works), check the code matches, and click Allow. Meanwhile poll every `interval` seconds:

```bash
curl -s -X POST https://app.wonderchat.io/api/agent/token \
  -H 'Content-Type: application/json' -d '{"device_code":"<device_code>"}'
```

`authorization_pending` means keep polling. You then get `access_token` (valid one hour). `access_denied` or `expired_token` means start again.

### 2. Call the tools

Everything is a tool on the MCP endpoint. Call it with plain HTTP, no MCP client needed:

```bash
curl -s https://app.wonderchat.io/api/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_agent","arguments":{"name":"Acme Support","websiteUrl":"https://acme.com"}}}' \
  | sed -n 's/^data: //p'
```

The reply is one JSON-RPC message; the tool's output is the JSON text in `result.content[0].text`. `"method":"tools/list"` lists every tool with its arguments.

### 3. Setup steps

1. `create_agent` with `name` and `websiteUrl` (crawls the whole site; `crawlScope` narrows it) and/or `texts` (docs from the repo). Upload PDFs and other documents with `add_knowledge_file` (base64).
2. Poll `get_setup_status` (`agentId`) every ~20 seconds until `isTraining` is false. `state: "ERROR"` comes with `error`.
3. `update_model_and_behavior` with a `systemPrompt` you write from what you learned: who the business serves, tone, what not to do, when to hand off to a human. `update_profile_and_widget` for name, greeting and `colorTheme` (the brand colour).
4. `ask` a few real customer questions to check the answers. Fill gaps with `add_faq` or `add_knowledge_text`.
5. `get_embed_code` and add the snippet to the site's shared layout so it loads on every page.
6. Load the site (localhost is fine) and confirm `get_setup_status` lists it in `sitesLive`.

Give the user a short summary: what the agent learned, where the snippet went, and the dashboard link https://app.wonderchat.io for later.

## Connecting as an MCP server instead

For ongoing use (tuning the agent, working the ticket inbox from chat), add the same endpoint as a remote MCP server with OAuth. New tools usually appear after the client reloads.

- Claude Code: `claude mcp add --transport http wonderchat https://app.wonderchat.io/api/mcp`
- Cursor, VS Code, Codex, Claude Desktop: add an HTTP MCP server with URL `https://app.wonderchat.io/api/mcp`

The `set_up_website_agent` MCP prompt runs the setup steps above.

## Links

- [auth.md](https://app.wonderchat.io/auth.md): every way an agent can authenticate, in one place
- [MCP endpoint](https://app.wonderchat.io/api/mcp): every tool describes its own arguments and output
- [Dashboard](https://app.wonderchat.io)