Developer docs

Build with ChatWithHuman.ai

Everything you need to integrate human escalation into your AI agent: REST API, live event stream, and copy-paste examples.

Talk to sales openapi.json for agents

Quickstart

01
Get your API key
Sign up and generate a key from your dashboard (/dashboard/keys). Keys are prefixed cwh_live_, shown once, and can be revoked at any time.
02
Escalate a session
POST to /api/sessions with your agent_id and context. Add "tier": "priority" for guaranteed fast response at $25/min (Standard is $10/min). ChatWithHuman.ai matches the session to an available human expert.
03
Stream the reply
Open GET /api/sessions/{id}/events (Server-Sent Events) to receive status changes and the human's messages, then resume your agent flow. Webhooks are planned.

API reference

Base URL: https://chatwithhuman.ai/api

POST/sessions

Create a new escalation session. Returns a session_id, estimated wait time, and the tier and rate that apply.

Field	Type	Description
agent_idrequired	string	Your registered agent identifier.
context	string	Plain-text summary of the issue for the human expert. Strongly recommended.
tier	"standard" \| "priority"	Pricing tier for this session. Defaults to standard ($10/min); priority is $25/min with guaranteed fast human response. Legacy priority: "high" also selects priority.
webhook_url	string	Stored with the session. Webhook delivery is planned, not live — use the event stream.
metadata	object	Arbitrary key-value pairs, echoed back in the response.

response

{  "session_id": "ses_x9k2m",  "status": "queued",  "eta_seconds": 12,  "billing_started": false,  "tier": "standard",  "rate_cents_per_minute": 1000,  "metadata": {}}

GET/sessions/{id}

Retrieve the current state of a session, including its tier and full message transcript.

response

{  "id": 42,  "sessionId": "ses_x9k2m",  "agentId": "agent_abc123",  "status": "connected",  "priority": "normal",  "tier": "standard",  "context": "User is asking about a refund for order #8821",  "webhookUrl": null,  "operatorId": "operator_1",  "billingStartedAt": "2026-10-14T21:18:04.000Z",  "closedAt": null,  "createdAt": "2026-10-14T21:17:52.000Z",  "userId": "usr_\u2026",  "messages": [    {      "id": 7,      "sessionId": "ses_x9k2m",      "role": "human",      "content": "Hi \u2014 I can help with that refund.",      "createdAt": "2026-10-14T21:18:10.000Z"    }  ]}

POST/sessions/{id}/messages

Send a message into a session. Agents should pass role "agent".

Field	Type	Description
contentrequired	string	The message text to send.
role	"agent" \| "human" \| "system"	Defaults to human — set "agent" when your agent is speaking.

response

{  "message_id": "msg_7",  "created_at": "2026-10-14T21:18:04.000Z"}

GET/sessions/{id}/events

Server-Sent Events stream: status changes, new messages, and a ping every 20 s.

response

data: {"type":"status","status":"connected"} data: {"type":"message","message":{"id":7,"role":"human","content":"Hi — I can help with that refund.", …}} data: {"type":"ping"}

PATCH/sessions/{id}

Close a session with {"status": "closed"}. Billing stops and an invoice is created (whole minutes × tier rate, 1-minute minimum, no platform fee). Returns the updated session.

Field	Type	Description
statusrequired	"connected" \| "closed"	"closed" ends the session; "connected" is set when an operator joins.
operator_id	string	Operator joining the session (with status "connected").

response

{  "sessionId": "ses_x9k2m",  "status": "closed",  "priority": "normal",  "billingStartedAt": "2026-10-14T21:18:04.000Z",  "closedAt": "2026-10-14T21:20:18.000Z",  "\u2026": "\u2026"}

GET/billing/usage

Invoices plus all-time and 30-day totals for your account (signed-in session). Filter by agent.

Field	Type	Description
agentId	string (query)	Only this agent's invoices.
limit / offset	integer (query)	Pagination; defaults 20 / 0.

response

{  "invoices": [    {      "invoiceId": "inv_3f9a\u2026",      "sessionId": "ses_x9k2m",      "totalMinutes": 2,      "ratePerMinute": "10.0000",      "subtotalCents": 2000,      "platformFeeCents": 0,      "totalCents": 2000,      "currency": "usd",      "status": "pending"    }  ],  "totals": {    "totalSessions": 47,    "totalMinutes": 312,    "totalCents": 312000  },  "last30Days": {    "sessions": 12,    "minutes": 80,    "revenueCents": 80000  }}

Webhooks (planned)

Not live yet: the server stores webhook_url but does not deliver events. Today, consume the same events from GET /api/sessions/{id}/events (Server-Sent Events). The planned events are listed below; signing will be documented when delivery ships.

Event	Description
session.queued	Session created and waiting for a human expert.
session.connected	Human expert joined. Billing starts.
session.message	New message from the human expert.
session.closed	Session ended. Includes final duration and cost.

live today: SSE stream

// Live today: stream session events over SSE
const res = await fetch(`https://chatwithhuman.ai/api/sessions/${sessionId}/events`, {
  headers: { Authorization: `Bearer ${process.env.CHATWITHHUMAN_API_KEY}` },
});
for await (const chunk of res.body) {
  // data: {"type":"message","message":{...}}
  process.stdout.write(chunk);
}

API keys

Keys are prefixed cwh_live_ and shown once at creation. Sandbox (test) keys are planned; today every session is matched to real humans and billed.

-Store keys in environment variables — never commit them to source control.
-Rotate by creating a new key, deploying it, then revoking the old one (DELETE /api/keys/{keyId}).
-Scope keys per agent to isolate usage and billing.

SDKs

SDK	Install	Status
Node.js	`npm install @chatwithhuman/node`	planned
Python	`pip install chatwithhuman`	planned
Go	`go get github.com/chatwithhuman/go-sdk`	planned
REST	`No install required`	stable

Implemented routes

The routes the current server actually serves, under /api on the site origin. Full schemas: /openapi.json (OpenAPI 3.1).

Method	Path	Summary
POST	/api/sessions	Escalate: create a session (queued for a human)
GET	/api/sessions	List sessions (operator queue)
GET	/api/sessions/history	Search past sessions with duration and invoice
GET	/api/sessions/{id}	Get a session with its full transcript
PATCH	/api/sessions/{id}	Change session status (connect = billing starts, close = invoice)
POST	/api/sessions/{id}/messages	Send a message into a session
GET	/api/sessions/{id}/events	Server-Sent Events stream for a session
GET	/api/operators	List human operators
PATCH	/api/operators/status	Set an operator online/offline
GET	/api/schedule	Bookings, operators and availability
POST	/api/schedule	Book a session with an operator in advance
GET	/api/keys	List the signed-in user's API keys (hash never returned)
POST	/api/keys	Create an API key (raw key returned once, prefix cwh_live_)
DELETE	/api/keys/{keyId}	Revoke an API key
GET	/api/billing/usage	Invoices plus all-time and 30-day totals
POST	/api/billing/meter	Record a billing event for a session
GET	/api/billing/invoices/{invoiceId}	Invoice with its billing events
POST	/api/billing/invoices/{invoiceId}/charge	Charge an invoice to the signed-in user's saved card (Stripe)
GET	/api/stripe/config	Whether payments are configured (publishable key, mode)
GET	/api/stripe/products	Active Stripe products with their default price
POST	/api/stripe/create-checkout-session	Create a Stripe Checkout session (single price or cart)
GET	/api/stripe/session/{sessionId}	Verify a Checkout session after redirect
POST	/api/stripe/webhook	Stripe webhook receiver (verifies stripe-signature)
GET	/api/auth/{path}	better-auth GET handler (e.g. get-session)
POST	/api/auth/{path}	better-auth POST handler (sign-in, sign-up, sign-out)
GET	/api/sales-chat	Sales chat mode (llm \| scripted), lead fields, handoff contact and limits
POST	/api/sales-chat	Send one message to the AI sales assistant (lead qualification + human handoff)
POST	/api/leads	Submit a sales lead directly (for agents and forms)
GET	/api/admin/leads/{leadId}	Full lead + transcript (admins only; linked from lead alert emails)
GET	/api/health	Liveness probe
GET	/api/status	Service health checks (API, Database, Authentication, Chat Sessions, Webhook Handler)

MCP server

plannedThere is no MCP server yet. The descriptor at /.well-known/mcp.json documents the intended shape so agent runtimes can plan for it. Until then, use the REST API in /openapi.json. Descriptor: /.well-known/mcp.json

Planned tool	REST equivalent (today)	Arguments
escalate_to_human	POST /api/sessions	agent_id, context, priority?, metadata?
send_message	POST /api/sessions/{id}/messages	session_id, content
get_session	GET /api/sessions/{id}	session_id
close_session	PATCH /api/sessions/{id}	session_id (status: "closed")

## Quickstart

Get your API key

Escalate a session

Stream the reply

## API reference

POST/sessions

GET/sessions/{id}

POST/sessions/{id}/messages

GET/sessions/{id}/events

PATCH/sessions/{id}

GET/billing/usage

## Webhooks (planned)

## API keys

## SDKs

## Implemented routes

## MCP server

Quickstart

API reference

Webhooks (planned)

API keys

SDKs

Implemented routes

MCP server