POST /api/v1/chat
Send a message. Get back the reply, simple.
Request
Auth: Authorization: Bearer <api_key>. Content-Type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
| agentId | string | Yes | Agent public ID |
| message | string | Yes | Customer message. Max 4,000 chars |
| sessionId | string | No | Conversation id. Generated if omitted |
| visitorId | string | No | Stable hashed user id. Cross-session memory on Humaner |
const res = await fetch("https://app.humaner.ai/api/v1/chat", {
method: "POST",
headers: {
Authorization: "Bearer hu_1b1a577877",
"Content-Type": "application/json",
},
body: JSON.stringify({
agentId: "ag_demo123",
sessionId: crypto.randomUUID(),
message: "Where is my order?",
}),
});
// Responses stream as SSE — { delta } chunksSSE response
- N events: data: {"delta":"..."} — append to the reply
- 1 final JSON event: usage, metadata, handoff, suggestions
- data: [DONE]
Stream shape
data: {"delta":"Your order "}
data: {"delta":"shipped."}
data: {"usage":{...},"metadata":{...},"handoff":null,"suggestions":["..."]}
data: [DONE]Final event fields
| Field | Use it for |
|---|---|
| usage.sessionId | Persist for the next turn |
| usage.grounded | Whether the answer used your knowledge |
| metadata.intent | Optional UI routing (order_status, etc.) |
| metadata.escalate | true → show handoff / create ticket |
| metadata.urgency | low | medium | high | critical |
| metadata.cancellationIntent | true → run your retention flow |
| handoff | null, or { humanDesk, email } when escalate is true |
| suggestions | Optional quick-reply chips |