Quickstart

From a new account to an answered test message, in the dashboard.

Before you start

You need	Detail
An account	Sign up at median.sh/sign-up.
An organization	A new account lands on Create an organization. Enter a Name. The Slug fills in from it. Click Create organization. You become its owner.
The admin or owner role	Only admins and owners create keys, edit the agent and add knowledge. See Roles.
The Standard or Pro plan, with credits	AI replies need a paid plan. On Explore, or with no credits left, every message goes to your team. See Plans.

Set up

Create a key

Open Settings → API. Under Median keys, click Create key. Optionally enter a name, such as Production, and click Create key.

The Copy your keys dialog shows two values:

Label	Starts with	Put it
Median key · server only	`median_key_`	Your server environment, as `MEDIAN_KEY`
Public key · safe for the browser	`median_pk_`	The widget’s `apiKey`

The Median key is shown once. Copy both values before you click Done.

Try it without code (optional)

Press Try the widget in the new key dialog, or open https://median.sh/widget?key=median_pk_... with your public key. The page shows Your live widget and the real widget. Messages you send there land in your inbox.

Install and mount

npm install @mediansh/widget

pnpm add @mediansh/widget

yarn add @mediansh/widget

bun add @mediansh/widget

import "@mediansh/widget/styles.css";
import { MedianSupport } from "@mediansh/widget";

<MedianSupport apiKey="median_pk_..." />;

Render it once, in your root layout or top-level component. The launcher appears in the bottom right corner. Install the widget covers deriving the key on your server, identity, and stacks without React.

Teach the agent

Open Agent → Profile. Set a Name and a Personality. Each field saves when you leave it.
Open Knowledge. Click Add, then Add content, then Create a document.
Enter a title, write an answer your customers need, and click Save.

Send a test message

Open your site or the test page, click the launcher, and ask something your document answers. The widget asks for an email before the first message. The agent replies in the panel.

Open Inbox. The thread is under Open.

If it does not answer

Cause	What you see	Fix
Explore plan, or no credits	The widget says “I’ve asked a teammate to step in. Someone will be with you shortly.” The thread is under Needs a person.	Upgrade or add credits in Settings → Billing. See Plans.
Empty knowledge	The agent has nothing to search. It answers only what it can confirm and hands the rest to your team.	Add a document in Knowledge.
Wrong key prefix	No launcher. The console says the apiKey “should start with median_pk_”.	Pass the `median_pk_` public key. If the `median_key_` value reached the browser, revoke it in Settings → API and create a new key.
Missing stylesheet	The widget is unstyled and sits inside your page layout.	Import `@mediansh/widget/styles.css` once.

Next steps

Install the widget

Keep the key on your server, and mount on any stack.

Identity

Tie conversations to your signed in users.

Custom tools

Let the agent look things up and act in your product.

Inbox

Pick up the threads the agent hands over.