Humaner Cloud - Agent Brief

1. Confirm the target: Humaner Cloud at app.humaner.io (managed agents, Intelligence, Desk, optional Inboxes). If they self-host, stop and use the Self-hosting brief instead.
2. Ask for the public Agent ID from Dashboard → Agents → their agent → Integrations. Placeholder in this doc: YOUR_AGENT_PUBLIC_ID.
3. Ask for the production hostname(s) that will host the chat (e.g. example.com, www.example.com). Needed for the domain allowlist.
4. Pick the right surface (default: Widget). Implement it in their codebase against https://app.humaner.io.
5. Tell the user the one dashboard step they must do: add allowed domains under Agents → Integrations → Widget.
6. Verify: load the site, open the bubble, send a test message. Optional: force a handoff into Human Desk.

Self-hosting brief: https://docs.humaner.io/oss/agent-brief · Cloud quickstart: https://docs.humaner.io/quickstart · Self-hosting vs Cloud: https://docs.humaner.io/contributing/open-source-vs-cloud

Humaner Cloud is a managed customer-support layer: AI agents that answer from the customer's knowledge, Desk escalation (Agent Desk + Human Desk), live chat, optional collaborative Inboxes, and Intelligence (memory, retrieval, auto-training). Inference and retrieval run on Humaner's servers. The integrator only embeds a surface and pastes the Agent ID.

• Agents: personality, knowledge, memory, Skills, guardrails, auto-escalation.
• Desk: Agent Desk, Human Desk / Helpdesk, live chat, runbooks, loops (tiered).
• Inboxes: IMAP / Gmail collaborative mailbox (optional).
• Base URL: https://app.humaner.io — never point Cloud embeds at a self-hosted origin.
• Docs: https://docs.humaner.io

1. 1

   Sign up and create an agent

   https://app.humaner.io/auth/signup → create an organization → Dashboard → Agents → New. Add site URL, docs, or FAQ as knowledge.

2. 2

   Copy the public Agent ID

   Agents → your agent → Integrations. Copy the public ID (cuid). That is YOUR_AGENT_PUBLIC_ID. Never put API keys in the browser.

3. 3

   Allowlist production domains

   Agents → Integrations → Widget → Allowed domains. Add every hostname that will load the embed (example.com, www.example.com). Leave empty only while testing on localhost.

Paste before </body> on every page that should show chat. No API key. Auth = public Agent ID + Origin against the allowlist.

<script
  src="https://app.humaner.io/widget.js"
  data-agent="YOUR_AGENT_PUBLIC_ID"
  data-color="#e0e1df"
  data-position="bottom-right"
  async
></script>

• Handoff to Human Desk is built in when escalation triggers.
• Identify logged-in visitors (optional, Humaner memory): window.Humaner.identify(hashedUserId, metadata).
• Proactive popup: window.Humaner.message(text), or POST /api/v1/widget/proactive after identify.
• CSP: allow script/frame from app.humaner.io, or use Link / API instead.

Zero install. Open or link this URL:

https://app.humaner.io/widget/YOUR_AGENT_PUBLIC_ID?open=1

Optional query params: color, pos, host. Text-only surface (no inline product cards). Full handoff still works.

1. Confirm plan is Custom (not Humaner).
2. Create an API key in Dashboard → Settings → Developers.
3. From your backend, call /api/v1/intelligence/retrieve before factual answers.
4. On escalation, call /api/v1/intelligence/create-ticket with sessionId + summary.

curl -X POST https://app.humaner.io/api/v1/intelligence/retrieve \
  -H "Authorization: Bearer hm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_PUBLIC_ID",
    "query": "Where is my order?"
  }'

1. Dashboard → Settings → API (or Integrations → REST API) → create key. Shown once.
2. Store as HUMANER_API_KEY (or similar) on the server.
3. POST messages to /api/v1/chat. Parse SSE.
4. On metadata.escalate / handoff, create a ticket via POST /api/v1/handoff/ticket or render your own handoff UI.

curl -N -X POST https://app.humaner.io/api/v1/chat \
  -H "Authorization: Bearer hm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_PUBLIC_ID",
    "message": "Where is my order?",
    "sessionId": "sess_abc123"
  }'

const res = await fetch("https://app.humaner.io/api/v1/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HUMANER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: process.env.HUMANER_AGENT_ID, // YOUR_AGENT_PUBLIC_ID
    message,
    sessionId,
    visitorId, // optional hashed id for memory
  }),
});
// Stream res.body as SSE: data: {"delta":"..."} then final event, then [DONE]

SSE shape: N events with {delta}, one final JSON event (usage, metadata, handoff, suggestions), then data: [DONE]. Auth errors: 401 missing/invalid key or agent; 403 key/org mismatch or origin not allowlisted.

• Browser embeds never send an API key; Origin must match Allowed domains.
• Knowledge retrieval and model routing are automatic on Cloud.
• Escalation opens Human Desk with summary, urgency, and transcript when configured.

For cross-session memory (Humaner), pass a stable hashed user id — never raw email or PII in the clear as the id.

// Widget global (when present)
window.Humaner?.identify?.(hashedUserId, { plan: "pro" });

// Or REST: POST https://app.humaner.io/api/v1/visitors/identify
// Body: { agentId, visitorId, metadata } with Bearer key

1. Script/component is on the page with the real Agent ID (not the placeholder).
2. Allowed domains include the hostname under test (or empty list for localhost only).
3. Chat bubble appears; greeting loads.
4. A knowledge-backed question returns a sensible answer.
5. If Human Desk is enabled: force an escalation path and confirm a ticket appears in the dashboard.