Skip to main content
Velor

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 →

Step 1

Install 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.

HTML
<!-- 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 Slug field 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:

HTML
<!-- 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:

HTTP
script-src https://app.velorplatforms.com
connect-src https://app.velorplatforms.com
img-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.
Step 2

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.

TypeScript
// 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, email and name are 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 userHash server-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 userHash verifies, 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 signed userId, so use the visitor’s email address as userId to enable them; the email field is not covered by the signature and is not trusted for this.
  • On sign-out call Velor.reset(), not identify() again. identify() merges into the current identity and cannot remove a field, so the previous user’s userHash would 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.
Step 3

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.

JSON
// 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": true on 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, plus Velor-Signature-256 (value v1=<hex>) and Velor-Timestamp for verification.
  • Actions are org-scoped. One tenant’s actions cannot be invoked by another tenant’s agent.
Step 4

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-signature and x-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-256 with the value v1=<hex>, plus Velor-Timestamp. Strip the v1= prefix before comparing — this page previously named the webhook header here, so a verifier written from it found no signature at all.

TypeScript
// 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 OK within your action’s timeout_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.

Question not answered here? caden@velorplatforms.com

Email us