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
@mediansh/widgetimport "@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.