POST /api/v1/widget/proactive

Queue a teaser bubble and notification badge on the live widget for an identified visitor.

Request

Field	Type	Required	Description
agentId	string	Yes	The agent's public ID
visitorId	string	Yes	The same ID you passed to window.Humaner.identify()
message	string	Yes	280 characters max. Shown in the teaser bubble.

const res = await fetch("https://app.humaner.io/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?"
  })
});

Response

200 OK

{
  "id": "8f2c1a90-4b3e-4d11-9c0a-2f6e1b8d4a77",
  "visitorId": "usr_hashed_123",
  "message": "Need a hand getting started?",
  "expiresAt": "2026-08-16T13:05:00.000Z"
}

The widget polls GET /api/v1/widget/proactive while closed. From the page you can skip the queue: window.Humaner.message(text).

Errors

Status	Meaning
400	agentId, visitorId, or message missing or too long
401	Missing API key, or called without a key from the browser
403	Origin not on the allowed-domains list
404	Agent not found
429	Rate limit hit