Agent-first onboarding

With agent-first onboarding, an AI agent such as Claude Code, Codex or Cursor sets Wiredesk up for someone. It sends a website URL, with no Wiredesk account and no API key. Wiredesk builds a trial agent from the site and returns a key that works for that trial. The AI agent tunes the agent and tests it. Then it gives the person one link, where they chat with the agent and claim it into an account. If you already have an account, make an API key instead.

Paste this into your AI agent

Copy this prompt into an AI agent that can make web requests, such as Claude Code, Cursor, Codex or Windsurf. Change the website to yours first.

Prompt

Set up Wiredesk for my business's website: https://YOUR-WEBSITE.com

Wiredesk is an AI agent that answers customers on chat, phone and email.
Read https://wiredesk.ai/docs/developers/agent-onboarding.md and follow it.
No Wiredesk account or API key is needed to start.

1. Start a trial: POST https://wiredesk.ai/api/v1/onboarding with my
   website_url, and your own name as agent_name. Keep the api_key it
   returns to yourself.
2. Check GET https://wiredesk.ai/api/v1/onboarding/{id} until knowledge
   is done. This usually takes a minute or two.
3. Test the agent with 5 questions my customers would ask
   (POST /api/v1/agents/{agent_id}/chat). If an answer is wrong or vague,
   fix the instructions or add knowledge, then test again.
4. Give me the claim_url, say what the agent has read, and list what
   you changed. I'll try the agent there and claim it.

The agent works for a few minutes and then gives you a link. On that page you chat with your new agent. Sign up or sign in, then press Claim this agent. It’s free, and you don’t need a card.

Chat apps that can only read web pages, such as ChatGPT or Claude on the web, can’t start a trial, because they can’t send a POST. Use an agent that can run commands, or sign up and paste your website there.

The rest of this page is for the AI agent, or for you if you’re building the integration yourself.

How it works

POST /onboarding with the website. No key needed. Wiredesk reads a few pages, drafts the agent’s name, greeting and instructions, and starts crawling the whole site. The response includes a key for the trial and claim_url.
With that key, the AI agent uses the rest of the API or the MCP server like any other caller. For example, it can change the instructions, add knowledge, and send test messages.
GET /onboarding/{id} returns the setup checklist. The AI agent fixes what is not done.
The AI agent gives the person claim_url. On that page they chat with the agent, sign up or sign in, and press Claim this agent.

A trial lasts 7 days. If nobody claims it by then, Wiredesk deletes it.

Start

curl https://wiredesk.ai/api/v1/onboarding \
  -H "Content-Type: application/json" \
  -d '{ "website_url": "https://acmeplumbing.com", "agent_name": "Claude" }'

Field
`website_url`	Required. The business’s public website.
`purpose`	What the agent is for: `answers` (the default) answers questions about the business, `support` helps existing customers with problems, `bookings` takes bookings, and `custom` is anything else.
`agent_name`	Your name, as the AI agent doing the setup. The claim page shows it: “Claude built this from acmeplumbing.com”.
`client_id`	Your runtime’s own id, if it has one.

The response is 201:

{
  "data": {
    "id": "ob_3f9a1c2d4e5f60718293a4b5c6d7e8f9",
    "object": "onboarding",
    "status": "active",
    "agent_id": "8f0e…",
    "website_url": "https://acmeplumbing.com/",
    "setup_agent": "Claude",
    "claim_url": "https://console.wiredesk.ai/try/ob_3f9a1c2d4e5f60718293a4b5c6d7e8f9",
    "claim": { "email": null, "plan": "free", "claimed_at": null },
    "created_at": "2026-10-10T12:00:00.000Z",
    "expires_at": "2026-10-17T12:00:00.000Z",
    "api_key": "wd_…",
    "api_base": "https://wiredesk.ai/api/v1",
    "mcp_url": "https://wiredesk.ai/api/mcp",
    "setup": [
      { "key": "knowledge", "state": "pending", "detail": "Still reading the website. Check again in a minute." },
      { "key": "instructions", "state": "done", "detail": "164 words." },
      { "key": "greeting", "state": "done", "detail": "Acme Plumbing, how can I help?" },
      { "key": "appearance", "state": "pending", "detail": "Reading the website's colours. Check again in a few seconds." }
    ]
  }
}

Save id, agent_id and api_key. The key is shown only once. Do not show the full key to the person. Starting takes a few seconds: Wiredesk reads the home page and a few others and drafts the agent before it answers. The rest of the site, and its colours, are read afterwards. A site Wiredesk cannot read returns 502, and nothing is created.

Set up and test the agent

Send the trial’s key as Authorization: Bearer wd_…. It works for this trial’s agent only.

# Change the instructions
curl -X PATCH https://wiredesk.ai/api/v1/agents/AGENT_ID \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "instructions": "You answer for Acme Plumbing in Ithaca, NY…" }'

# Teach it something the site does not say
curl https://wiredesk.ai/api/v1/agents/AGENT_ID/knowledge \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "type": "text", "label": "Call-out fee", "content": "Emergency call-outs are $95 before 8pm." }'

# Ask it what a customer would
curl https://wiredesk.ai/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you do emergency call-outs on Sunday?" }'

Useful calls during setup:

PATCH /agents/{agent_id} changes the name, greeting or instructions.
GET /agents/{agent_id}/knowledge shows when the website is ready.
POST /agents/{agent_id}/knowledge adds pasted text or another website.
POST /agents/{agent_id}/chat sends a test message.

The same key works with the MCP server at https://wiredesk.ai/api/mcp. A trial’s chats stop at $2 of usage, which is about 100 replies, until someone claims it.

Check the setup

curl https://wiredesk.ai/api/v1/onboarding/ob_3f9a… \
  -H "Authorization: Bearer wd_…"

data.setup lists four items. Each item has a state and a detail.

`key`	Done when
`knowledge`	The website has been read. It is `pending` while the site is crawled, usually a minute or two, and `warning` if the crawl failed.
`instructions`	The agent has instructions.
`greeting`	The agent has a greeting.
`appearance`	The widget uses the site’s colours. It is `pending` for up to half a minute after the start while they are read, and `warning` if Wiredesk could not read them. The person can set them after claiming.

Share claim_url once the knowledge is done and the test answers use facts from the website.

Hand it to the person

Give the person claim_url. Tell them what the agent is for, what it has read, and anything you changed. If they have told you the email they will sign up with, save it first. The sign-up form then has it filled in:

curl https://wiredesk.ai/api/v1/onboarding/ob_3f9a…/claim \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@acmeplumbing.com" }'

The response is the onboarding, with claim_url. The claim itself is always made by the person, signed in, on that page. The API cannot claim an agent for someone.

What claiming does

The person signs up or signs in, then presses Claim this agent:

They have no workspace yet. The trial’s workspace becomes theirs, with the agent, its knowledge and the test conversations.
They already have a workspace. The agent is copied into it, and the website is crawled again for the copy. The trial is deleted. They need to be an owner or admin there, and the workspace needs room under its plan’s agent limit.

A claimed agent is always on the Free plan, with no card. The person can upgrade later under Billing. See Plans and limits. After a claim, the trial’s key stops working. GET /onboarding/{id} with a key from the workspace the agent went to shows status: "claimed" and the agent’s new agent_id.

Delete a trial

If the person does not want the agent, or the setup went wrong:

curl -X DELETE https://wiredesk.ai/api/v1/onboarding/ob_3f9a… \
  -H "Authorization: Bearer wd_…"

This deletes the agent and the trial, and the key stops working. You cannot delete an agent someone has claimed: that returns 409 conflict.

Build trials for other people

If you build agents for others, such as an agency making demos for prospects, send your workspace’s full-access API key with the start:

curl https://wiredesk.ai/api/v1/onboarding \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "website_url": "https://acmeplumbing.com", "agent_name": "Northside Digital" }'

The trial is the same: its own workspace, its own key in the response, and a claim_url for the person it is for. The difference is the limit. The starts count against your workspace, 100 a day, rather than against your IP address. The key must be valid, or the start fails with 401. A trial’s own key counts by IP address, as if no key was sent.

From an agent’s API call

Your own Wiredesk agent can build a visitor a trial in the middle of a chat, with an API call action. Under Actions, add an API call:

Field	Value
Tool name	`build_trial_agent`
When should the agent call this?	When a visitor wants to try a chatbot or an agent for their own business, once they have given their website.
Method	`POST`
URL	`https://wiredesk.ai/api/v1/onboarding`
Params	`website_url`: “The visitor’s business website, e.g. acme.com” (required)
Request body	`{"website_url": "{{website_url}}", "agent_name": "Your company"}`
Response fields	`data.claim_url`
Authentication	Bearer token, with a full-access API key from your workspace
Channels	Chat

Then tell the agent, in its instructions, to ask for the visitor’s website when they want to try it, and to give them the data.claim_url it gets back. For example:

When someone wants to try us, start a pilot, or see a chatbot for their own business, don't take
their details first. Ask for their website address, call build_trial_agent with it, and tell them
it takes a few seconds. Give them the data.claim_url it returns, exactly as returned, as a link.
Never make up a link. If it fails, say so and offer to take their details instead.

Listing the response field keeps the trial’s own key out of the conversation. Starting a trial takes a few seconds, well within the 30 seconds an API call gets on chat.

Add the key. Without one the action still works, but a call from an agent reaches Wiredesk with no visitor address, so every such trial counts as the same caller and shares one limit of 10 a day with every other agent that calls without a key. With your workspace’s key it is 100 a day. Past the limit the agent gets a 429 and no link, and follows its instructions for a failure.

Limits

20 requests a minute and 10 trials a day from one IP address, and a daily limit across everyone. Past either limit, a start gets 429. For more, sign up and send your workspace’s key with each start.
A trial’s chats stop at $2 of usage.
A trial lasts 7 days.
Anyone with claim_url can claim the agent. Share it only with the person it is for.

Overview

API, webhooks and MCP

Chat widget

Phone

Security

Agent-first onboarding

Paste this into your AI agent

How it works

Start

Set up and test the agent

Check the setup

Hand it to the person

What claiming does

Delete a trial

Build trials for other people

From an agent’s API call

Limits

​Paste this into your AI agent

​How it works

​Start

​Set up and test the agent

​Check the setup

​Hand it to the person

​What claiming does

​Delete a trial

​Build trials for other people

​From an agent’s API call

​Limits

​Related

Paste this into your AI agent

How it works

Start

Set up and test the agent

Check the setup

Hand it to the person

What claiming does

Delete a trial

Build trials for other people

From an agent’s API call

Limits

Related