Web widget
The hosted web chat bundle makes its own API calls from the visitor’s browser: it bootstraps an anonymous visitor session, loads your widget configuration, and streams the conversation over that session. You write code in exactly two places against this surface: the embed snippet on your site, and the webhook endpoint that receives visitor conversation events. This page documents both, plus the curl calls to prove the round trip from your own terminal. All widget calls go to the public API host,https://api.orbit.devotel.io, on paths under /widget/ (no /api/v1 prefix).
What the widget actually calls
Bootstrap is the only unauthenticated call. When a session token expires or is rejected, the call returns
401 with WWW-Authenticate: Bearer error="invalid_token", and the bundle re-bootstraps with a fresh POST /widget/session.
Your server never needs the widget’s browser-side calls. The single contract you code against is the inbound webhook, covered in Verify the inbound webhook on your server.
Anonymous visitor registration round trip
The bundle posts your public widget id (copy it from Settings → Native Chat) to bootstrap a visitor. Reproduce the exact call with curl:curl
session_tokenis a visitor credential, not a server credential. It lives 30 minutes, is scoped to one visitor session, and belongs in the visitor’s browser only. Do not store it server-side or reuse it across visitors.configis what renders the launcher. Brand color, position, agent name and avatar, business hours, and the consent prompt all come from this object, exactly as set under Settings → Native Chat.- Bootstrap is origin-checked. The
Originheader of the request must match one of your allowed origins, or the call returns403. See Embed the widget.
Embed the widget
Copy the snippet from Settings → Native Chat and paste it before the closing</body> tag of every page that should show the launcher. The snippet looks like this:
Origin you have not listed are refused, so a leaked snippet on someone else’s site cannot mint visitor sessions against your account.
Manage the binding from Settings → Native Chat:
Style, greeting, business hours, and the consent prompt are configured on the same page and reach the visitor through the
config object above; styling and channel routing are walked through in Native chat widget channel config.
Test the round trip with curl
Assert the happy path and the origin gate before shipping an embed change:curl
403 here means the origin gate is doing its job, not that the widget is broken. Run both calls from CI against your staging origin whenever the embed snippet or the origin list changes.
Verify the inbound webhook on your server
When a visitor sends a message, Orbit POSTs the standard event envelope to your registered webhook endpoint, signed with your webhook secret. Verify the signature header before trusting the body, and dedupe on the event id header so a retried delivery never double-processes. The full verifier and retry semantics are in Build your first webhook receiver; the widget-specific receiver is:200 quickly and queue the work; the same delivery semantics and retry schedule as every other Orbit webhook apply.