Docs
Get live, self-serve.
Four steps: install the widget, identify your visitors, define your first action, and verify your webhooks. Everything else builds on these.
IT admin? SAML SSO setup guide → · All enterprise IT guides →
Launching or moving? Going-live checklist → · Switching from Intercom, Zendesk or Freshdesk → · Data export and leaving → · Incidents and status →
Reference docs
Getting started by channel
Set up the widget, API, voice, email, SMS, WhatsApp or Slack with the same steps the Channels page shows.
ReadAPI quickstart
Your first two API calls, read then write, in curl, TypeScript and Python. Every sample is run against the real handlers in our tests.
ReadAPI reference
Every public endpoint with its parameters, scopes, error responses and request and response examples.
ReadWebhook events
Complete reference for all 25+ event types, payload shapes, and signature verification.
ReadAPI error codes
Every error code, its HTTP status, and how to handle it in your integration.
ReadVoice integration
Connect Twilio, configure your AI voice agent, and place outbound calls via API.
ReadSMS & WhatsApp setup
US carrier registration, reading a delivery error, and the WhatsApp 24-hour reply window.
ReadSSO & SAML
Configure SAML 2.0 with Okta, Microsoft Entra ID, Google Workspace, and more.
ReadInstall the widget
Drop one script tag into your HTML. The loader is served from Cloudflare’s edge network and is never cached by browsers or CDNs, so a fix to the widget reaches every site without you changing anything. The widget appears as a small launcher in the bottom-right corner and streams responses token-by-token. The tags work the same withasync, defer or neither, in the head or at the end of the body.
<!-- Place before </body>. Replace your-org-slug with your workspace slug. --><script src="https://app.velorplatforms.com/widget.js" async></script><script> window.Velor = window.Velor || { q: [] }; Velor.q.push(["init", { orgSlug: "your-org-slug" }]);</script>- Your workspace slug is the
Slugfield under Settings → General in the dashboard. - The widget is rendered in an isolated shadow DOM — no style bleed, no global CSS conflicts.
- Mobile-responsive by default. Built for current evergreen browsers; automated browser tests run on Chromium.
- Restrict which websites may load your widget under Settings → Widget → Allowed origins. The list starts empty, which accepts any website, so installs work immediately; until you set it, the dashboard warns you and lists the sites that opened a chat in the last 7 days, with a one-click option to allow only those.
Content Security Policy
The snippet above includes a small inline script. If your site’s policy does not allow 'unsafe-inline', the browser refuses it and the widget never appears. Use this single tag instead — it needs no inline script:
<!-- One tag, no inline script. Replace your-org-slug with your workspace slug. --><script src="https://app.velorplatforms.com/widget.js" data-org-slug="your-org-slug" async></script>Then allow these directives:
script-src https://app.velorplatforms.comconnect-src https://app.velorplatforms.comimg-src https:style-src (nothing to add)script-src— loads widget.js itself, and for a non-English locale one small language file from the same origin (widget-locale-<code>.js). If your policy uses nonces instead of hosts, put the same nonce on the widget's <script> tag (and on the inline init stub if you use one): the widget copies it onto the language file. A policy with 'strict-dynamic' needs no extra step.connect-src— every chat request — opening the session, streaming replies, file uploads and ratings. Without it the launcher appears and every open fails with “We couldn’t reach chat”.img-src— only if you set an avatar image in Branding or your agent sends cards with images; list those image hosts instead of https: if you prefer.style-src— the widget's styles live in its own shadow root as a constructable stylesheet, which CSP does not govern. Browsers without constructable stylesheets (Safari before 16.4, Firefox before 101) need style-src 'unsafe-inline' for the widget to be styled.- Using nonces with
'strict-dynamic'? Host allowlists are then ignored, so add your page’s nonce to the tag.
Widget options and methods
Pass options in the init command. Anything you leave out takes the default described here. The greeting and the primary color fall back to what you saved under Settings → Widget; the launcher position is taken from there once the widget has loaded.
orgSlug- Your workspace slug. Not needed on a verified custom domain, where the workspace is resolved from the host.
position- Where the launcher sits: bottom-right, bottom-left, top-right or top-left. Default: bottom-right until the widget loads your workspace settings, after which the position saved in Settings → Widget applies.
theme- Colors as { primary, text, background }, each a hex value. Passing primary overrides the accent saved in Settings → Widget; text and background default to #111827 and #FFFFFF.
greeting- The first message the visitor sees. Passing it overrides the greeting saved in Settings → Widget. Default: the greeting saved in Settings → Widget, or a short generic welcome if none is saved.
openOnLoad- true opens the chat window as soon as the page loads. Default: false.
hideOnPaths- Page paths where the widget does not appear. A path ending in * matches that prefix, for example "/checkout*". Default: none, so the widget appears on every page. It follows client-side route changes, so it also hides and shows as your single-page app navigates.
locale- Interface language: en, es, fr, de, pt, it, nl, ja, ar, he, zh, zh-Hant, ko or hi. Default: the visitor's browser language, falling back to en. A tag such as pt-BR is reduced to pt. Arabic and Hebrew lay the chat out right-to-left; every language except English loads as a small separate file the first time it is needed, so the chat shows English for a moment and stays in English if that file is blocked. zh-Hant is Traditional Chinese; zh is Simplified. These translations are machine-translated and have not been reviewed by a native speaker; the satisfaction-survey email follows the conversation's language in en, es, fr, de, pt, it, nl and ja and is machine-translated too.
zIndex- Stacking order of the widget. Default: 2147483000, above almost any page content.
collectEmail- true shows a short form asking for an email address before the first message. Skipped for a visitor you have already identified. Default: false, unless your workspace turns it on in Settings → Widget.
apiOrigin- Overrides the host the widget talks to. For local development; leave it out in production. Default: https://app.velorplatforms.com.
includeFullPageUrl- By default the widget reports only the page's origin and path, dropping the query string and fragment so tokens in URLs are not sent. true sends the full address.
contactUrl- An https:// page or a mailto: address where visitors can reach you when chat is unavailable, shown under the banner that says so. The Contact link saved in Settings → Widget takes precedence when both are set. Anything else is ignored.
requireIdentityVerification- Deprecated and ignored. Requiring verified identity is a workspace setting (Settings → Widget), enforced on our servers; the widget logs a console warning if a snippet sets this.
Methods
Call them on window.Velor, or queue them with Velor.q.push(["open"]) before the script has loaded.
init- Starts the widget with the options above.
open- Opens the chat window.
close- Closes the chat window.
toggle- Opens it if closed, closes it if open.
identify- Attaches the signed-in visitor (see below). Merges into what is already known; it never removes a field.
send- Opens the chat window and sends a message as the visitor.
reset- Signs the visitor out of the widget: forgets the identity, the stored visitor id and the transcript, and closes the window.
destroy- Removes the widget from the page.
Identify visitors
Call Velor.identify() after authentication. The userHash is an HMAC-SHA256 of the userId, signed with VELOR_IDENTITY_SECRET on your server — this prevents a visitor from spoofing another user’s identity from the browser. Unauthenticated visitors are handled anonymously, unless you turn on Require verified identity to chat in Settings → Widget, which refuses every visitor without a valid userHash.
// Call after your user is authenticated.// userId must match the subject you HMAC-sign server-side.window.Velor?.identify({ userId: "usr_9k2m4p", // stable, opaque user identifier email: "maya@acme.com", // used for follow-up and visitor lookup name: "Maya Chen", // shown to the agent on the visitor card // HMAC-SHA256 of userId, signed with your VELOR_IDENTITY_SECRET. // Prevents visitor identity spoofing from the browser. userHash: "a3f9c2e1d4b7...",});userId,emailandnameare attached to the conversation, shown on the visitor card in your inbox, and included in the signed payload sent to your custom actions. Any other flat string, number, boolean or null field is forwarded as visitor metadata (20 keys, values up to 256 characters); nested objects are dropped.- Generate
userHashserver-side:createHmac('sha256', process.env.VELOR_IDENTITY_SECRET).update(userId).digest('hex') - Account lookups through connectors — Stripe customers, charges, refunds and subscriptions, Shopify orders, HubSpot, Salesforce and Intercom contact, deal and user records, and Zendesk tickets — run only for a visitor whose
userHashverifies, and only for their own records. The same holds when a teammate approves a queued request: it runs with the identity the visitor verified when they asked. The verified identity is the signeduserId, so use the visitor’s email address asuserIdto enable them; theemailfield is not covered by the signature and is not trusted for this. - On sign-out call
Velor.reset(), notidentify()again.identify()merges into the current identity and cannot remove a field, so the previous user’suserHashwould stay on every request and, on a shared device, resume their conversation for the next person.reset()forgets the identity, the stored visitor id and the transcript, closes the pane, and the next session starts a fresh anonymous visitor.
Define a custom action
Actions are JSON-schema definitions that tell the agent which endpoints it can call and with what parameters. Velor HMAC-signs every dispatch, validates inputs against the schema before calling your endpoint, and rate limits action calls (10 per conversation per hour, 500 per minute per workspace). Actions are created in the dashboard under Actions → New; there is no public API for creating them. The fields below are the ones that form takes.
// Fields of Actions → New in the dashboard (no public API creates actions).{ "name": "order_lookup", "display_name": "Order lookup", "description": "Look up an order by number or email address.", "endpoint_url": "https://api.acme.com/velor/order-lookup", "destructive": false, "parameter_schema": { "type": "object", "required": ["order_number"], "properties": { "order_number": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "timeout_ms": 3000}- Set
"destructive": trueon any action that modifies state — the visitor confirms on a card in the chat widget before it runs; on other channels it waits for a teammate’s approval. - Your endpoint receives a POST with JSON body matching the
parameter_schema, plusVelor-Signature-256(valuev1=<hex>) andVelor-Timestampfor verification. - Actions are org-scoped. One tenant’s actions cannot be invoked by another tenant’s agent.
Verify inbound webhooks
Velor signs outbound calls with HMAC-SHA256 over timestamp.rawBody, and there are two header sets, because webhooks and action dispatch are separate systems. Verify before trusting the payload, and reject deliveries older than five minutes yourself; Velor does not enforce the window for you.
- Webhooks (events you subscribe to) send
x-velor-signatureandx-velor-timestamp. The value is prefixed:sha256=<hex>, over`${timestamp}.${rawBody}`. The snippet below verifies these. - Action dispatch (calls to your own action endpoints) sends
Velor-Signature-256with the valuev1=<hex>, plusVelor-Timestamp. Strip thev1=prefix before comparing — this page previously named the webhook header here, so a verifier written from it found no signature at all.
// Node.js — verify an inbound Velor webhook.import { createHmac, timingSafeEqual } from "node:crypto";export function verifyVelorWebhook( rawBody: string, headers: Record<string, string>, secret: string,): boolean { // An unset secret is a misconfiguration, never "valid for any input". if (!secret) return false; const timestamp = headers["x-velor-timestamp"]; if (!timestamp) return false; // Two signatures can arrive. For 24 hours after you rotate the signing // secret, Velor sends x-velor-prev-signature alongside x-velor-signature: // the first is signed with the NEW secret, the second with the OLD one. // Checking both means a rotation does not break deliveries while you roll // the secret out — whichever one you currently hold will match. const candidates = [ headers["x-velor-signature"], headers["x-velor-prev-signature"], ].filter(Boolean); if (candidates.length === 0) return false; // x-velor-timestamp is unix seconds. Reject a delivery older than five // minutes — that is the replay window — and one more than a minute in the // future, which is clock drift rather than anything you need to accept. const ts = Number(timestamp); if (!Number.isFinite(ts)) return false; const skew = Date.now() / 1000 - ts; if (skew > 300 || skew < -60) return false; const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"); // timingSafeEqual throws when the buffers differ in length, so compare // lengths first — otherwise a malformed signature crashes this handler with // a RangeError and returns 500 where 401 belongs. return candidates.some( (sig) => sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected)), );}- Your webhook secret is in the dashboard under Actions → (action name) → Signing secret.
- Use
timingSafeEqual(not===) to compare signatures — constant-time comparison prevents timing attacks. - Return
200 OKwithin your action’stimeout_ms— the default is 5,000ms and the ceiling is 30,000ms — or the action times out and the agent reports a tool error to the visitor. In web chat the timeout is also shortened to fit the reply: a call never runs into the last 8,000ms of the 30-second reply window, which are kept for the answer. The example above sets 3,000ms; that is a value you choose, not the limit. - Velor reads at most 32 KB of your response; anything beyond that is cut off before the agent sees it. The whole body, not only the headers, has to arrive within
timeout_ms.
Versioning and deprecation
Every v1 response carries x-velor-api-version, the date of the contract it follows. We add without notice: new endpoints, new optional request fields, new response fields and new webhook event types, so ignore fields you do not recognize. We do not change or remove what you can rely on without the notice below: removing or renaming an endpoint, parameter or response field, changing a type, or making an optional parameter required.
When an operation is retired it is first marked deprecated: true in the OpenAPI document, and every response from it, errors included, carries a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) giving the date it stops working, with a Link to the operation to move to. The sunset date is at least 180 days after the announcement, and the operation keeps working until then.
No operation is deprecated today.
Reference
Developer guide
Full install reference, advanced visitor identification, action orchestration patterns, and eval framework.
Open guidePlatform overview
How KB retrieval, guardrails, and the escalation engine work under the hood.
Read overviewIntegrations
Ten pre-built connectors you install yourself, Salesforce and HubSpot on request, and the custom-actions system for everything else.
Browse integrationsSecurity & trust
Infrastructure, RLS, HMAC signing, SOC 2 posture, DPA, and sub-processor list.
Review securityQuestion not answered here? caden@velorplatforms.com
Email us