# ChatWithHuman.ai — For AI agents

> You are an AI agent and you need a human. One call opens a live session with a verified human expert; you stream their replies, keep talking, and hand control back when it is resolved.

## When to escalate

- Ambiguous intent you cannot resolve with another clarifying question.
- Sensitive context (money, health, legal, account access) that needs human judgment.
- A task that requires a human action or sign-off you cannot perform.
- The user explicitly asks for a human.

## The loop (implemented routes, see https://chatwithhuman.chrismai.ai/openapi.json)

| # | Call | What it does |
| --- | --- | --- |
| 1 | `POST /api/sessions` | Open a session with agent_id + context (Authorization: Bearer <API key>). Returns session_id, status "queued", eta_seconds. |
| 2 | `GET /api/sessions/{id}/events` | Server-Sent Events: status changes (queued → connected → closed) and human messages. Ping every 20 s. |
| 3 | `POST /api/sessions/{id}/messages` | Send your messages (role "agent") into the live session. |
| 4 | `GET /api/sessions/{id}` | Read status and the full transcript at any time; resume your flow when status is "closed". |

```bash
curl -X POST https://chatwithhuman.chrismai.ai/api/sessions \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agent_abc123","context":"User is asking about a refund for order #8821","tier":"priority"}'
# 201 {"session_id":"ses_…","status":"queued","eta_seconds":12,"billing_started":false,"tier":"priority","rate_cents_per_minute":2500,…}
```

```bash
curl -N https://chatwithhuman.chrismai.ai/api/sessions/ses_x9k2m/events \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY"
# data: {"type":"status","status":"connected"}
# data: {"type":"message","message":{"role":"human","content":"…"}}
```

```bash
curl -X POST https://chatwithhuman.chrismai.ai/api/sessions/ses_x9k2m/messages \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"agent","content":"Order #8821 was paid by card ending 4242."}'
```

```bash
curl https://chatwithhuman.chrismai.ai/api/sessions/ses_x9k2m \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY"   # status + full transcript
```

## Writing good context

- Put everything the human needs in `context`: the user goal, what you already tried, relevant ids.
- Use `tier: "priority"` ($25/min, guaranteed fast human response) when a user is waiting on it; otherwise the default `standard` ($10/min).
- Attach your own correlation ids in `metadata`; they are echoed back.

## Billing

Billing starts when a human connects (status "connected"), not when you create the session: whole minutes at the session tier rate (Standard $10/min, Priority $25/min), no platform fee.

| Plan | Rate | For | Billing | API `tier` | CTA |
| --- | --- | --- | --- | --- | --- |
| Standard | $10 / min | Developers and small teams | Pay-as-you-go · whole minutes while a human is connected, 1-minute minimum | `standard` | Get API key |
| Priority | $25 / min | Funded startups and crypto projects | Pay-as-you-go · choose per session with tier: "priority" | `priority` | Get API key |
| Enterprise | from $250,000 / year | Public companies and large institutions | Annual contract · invoiced per contract | contract | Contact sales |

No platform fee. Pick the tier per session with `"tier": "standard" | "priority"` in `POST /api/sessions`.

## Same call in other languages

```js
const res = await fetch("https://chatwithhuman.chrismai.ai/api/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHATWITHHUMAN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "agent_id": "agent_abc123",
    "context": "User is asking about a refund for order #8821",
    "tier": "standard"
  }),
});
const { session_id, eta_seconds } = await res.json();
```

```python
import os, requests

r = requests.post(
    "https://chatwithhuman.chrismai.ai/api/sessions",
    headers={"Authorization": f"Bearer {os.environ['CHATWITHHUMAN_API_KEY']}"},
    json={
        "agent_id": "agent_abc123",
        "context": "User is asking about a refund for order #8821",
        "tier": "standard",  # or "priority" ($25/min)
    },
)
session = r.json()  # {"session_id": "ses_x9k2m", "status": "queued", "tier": "standard", ...}
```

## MCP (planned)

There 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.

| Planned tool | Maps to | 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") |

## Contact sales (Enterprise or any plan question)

No API key needed. Store a lead directly, or talk to the AI sales assistant:

```bash
curl -X POST https://chatwithhuman.chrismai.ai/api/leads \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice Chen","company":"Example Corp","email":"alice@example.com","use_case":"Escalate compliance questions","volume":"20,000 min/month","timeline":"Q1","plan":"enterprise"}'

curl -X POST https://chatwithhuman.chrismai.ai/api/sales-chat \
  -H "Content-Type: application/json" \
  -d '{"message":"What does Enterprise include?","plan":"enterprise"}'
# → { "conversation_id": "lead_…", "mode": "llm" | "scripted", "reply": "…", "missing": [...], "handoff": { … } }
```

Pass `conversation_id` back on each turn. Rate-limited per IP. Human handoff: text or call Chris Mai, 415-375-5872.

## Machine-readable

- [/llms.txt](https://chatwithhuman.chrismai.ai/llms.txt): llmstxt.org index: summary + links
- [/llms-full.txt](https://chatwithhuman.chrismai.ai/llms-full.txt): All docs, pricing and FAQ inlined in one file
- [/openapi.json](https://chatwithhuman.chrismai.ai/openapi.json): OpenAPI 3.1 spec of the implemented /api routes
- [/agents.md](https://chatwithhuman.chrismai.ai/agents.md): Guide for AI agents: when and how to hand off to a human
- [/.well-known/ai-plugin.json](https://chatwithhuman.chrismai.ai/.well-known/ai-plugin.json): AI plugin manifest (points to openapi.json)
- [/.well-known/mcp.json](https://chatwithhuman.chrismai.ai/.well-known/mcp.json): MCP server descriptor — status: planned
- [/index.md](https://chatwithhuman.chrismai.ai/index.md): Markdown twin of every page (/docs.md, /pricing.md …)
- [/sitemap.xml](https://chatwithhuman.chrismai.ai/sitemap.xml): Sitemap incl. markdown twins
- [/robots.txt](https://chatwithhuman.chrismai.ai/robots.txt): Crawl policy — AI crawlers explicitly welcome