SDK configuration reference

Where options come from#

The widget's look and wording come from three places, strongest first:

1. Options in your page: data-* attributes, data-config, or the object passed to init() or widget.update().
2. Settings saved in the Widget Studio (your portal). The widget fetches them from Recent Visits when the page loads. Production shows the published settings; Test shows your draft.
3. Built-in defaults.

Options are merged field by field: a value in your page replaces only that field, and anything you leave out falls back to the next layer. Everything is validated by the widget: an invalid value is replaced by the safe default and a warning is written to the browser console (Recent Visits widget: …). None of these options grants access to anything; the agency, its tours and what the assistant may say come from the server for your key.

Core options#

These control how the widget starts. They are available to init() (and, for the script tag, as the attributes shown).

Appearance and wording#

Text options are plain text: control characters and angle brackets are removed and the text is clipped to the limit. Images must be https (or a small base64 raster image) and must be allowed by your site's Content-Security-Policy.

Features and page context#

Notifications and invitations#

The widget never uses browser push notifications and never asks for permission. A small invitation next to the launcher is off unless you turn it on.

An invitation is never shown once the visitor has opened the chat, never in a background tab, and hides itself after autoHideMs.

Example#

import type { InitOptions } from '@recent-visits/widget'

export const options: InitOptions = {
  key: 'rvk_AAAAAAAAAAAAAAAAAAAAAAAA',
  appearance: 'auto',
  theme: { primary: '#0b5c4a', accent: '#b45309', radius: 14 },
  position: 'right',
  launcher: { label: 'Ask our travel guide', icon: 'compass' },
  assistant: { name: 'Trek Buddy' },
  header: { title: 'Ask Alpha Treks' },
  welcomeMessage: 'Namaste! Ask me about treks and tours.',
  suggestedQuestions: ['Explore tours', 'Create my trip plan'],
  features: { talkToAgency: false },
}

As a script tag the same values go in data-config as JSON:

<script
  src="https://recent-visit.com/widget/1/widget.js"
  data-key="rvk_AAAAAAAAAAAAAAAAAAAAAAAA"
  data-config='{"theme":{"primary":"#0b5c4a","radius":14},"launcher":{"label":"Ask our travel guide"},"assistant":{"name":"Trek Buddy"}}'
  async
></script>

If data-config is not valid JSON the widget logs data-config is not valid JSON and was ignored and carries on.

Limits inside the chat and the quote form#

These are fixed in the built-in interface and are not options.

Script tag notes#

• apiBase must be given as data-api-base; a value inside data-config is overridden by the attribute (which is empty when absent).
• getChallengeToken is a function and cannot be passed as JSON; use init() if you need it.
• data-config must be a JSON object; an array or a non-object is ignored.