API
For developers who want to build their own UI.
Before you start you only need:
- Your API key of course.
- The agent(s) ID(s) to integrate.
How it works
Hover to zoom
Opening greeting
Fetch the agent's greeting once on load and show it before the first user message.
const res = await fetch("https://app.humaner.io/api/v1/agents/AGENT_ID", {
headers: { Authorization: "Bearer hm_live_xxxxxxxx" }
});
const { greeting } = await res.json();Chat endpoint
POST /api/v1/chat streams the reply over SSE. See the Chat reference for the full event shape.
Handoff
When the final SSE event includes handoff, create a Desk ticket with POST /api/v1/handoff/ticket.
Proactive popup
Push a teaser bubble and a red badge onto the live widget for an identified visitor. The widget polls for queued messages while it is closed.
| Surface | How |
|---|---|
| Widget settings | Integrations → Widget → Proactive message. Delay + copy, once per visitor. |
| Page JS | window.Humaner.message("Need a hand?") after the embed script loads. |
| REST | POST /api/v1/widget/proactive with agentId, visitorId, and message. |
POST /api/v1/widget/proactive
await fetch("/api/v1/widget/proactive", {
method: "POST",
headers: {
Authorization: "Bearer hm_live_xxxxxxxx",
"Content-Type": "application/json"
},
body: JSON.stringify({
agentId: "AGENT_ID",
visitorId: "usr_hashed_123",
message: "Need a hand getting started?"
})
});Call window.Humaner.identify(visitorId) first so the widget can match the queued message. Identify is required for the REST path.
What stays widget-only?
- Live chat with a human member handling: the API can only get async email handoff
- Built-in in-chat UI components (product cards, booking calendars, return forms). But you can build these too if you need.