SDK API reference

The widget has no event emitter and no callbacks (there is no onOpen, onQuote or similar). The integration surface is: start it (init), control it (WidgetHandle), or skip the built-in interface and build your own on the headless client (createClient), where you see every call and result yourself.

init(options)#

function init(options: InitOptions): WidgetHandle

Mounts the widget (a launcher button and the chat panel in a closed Shadow DOM) and returns a handle. Calling it again returns the existing instance (there is one widget per page). It throws Error('Recent Visits: invalid key') if the key is malformed, and apiBase must use https (http is allowed only on localhost) or similar for a bad apiBase. Call it in the browser only; the server is contacted for the look at load and for a session when the visitor opens the chat.

InitOptions is every option of the configuration reference plus key, apiBase, storage, persist and getChallengeToken.

import { init } from '@recent-visits/widget'

const widget = init({ key: 'rvk_AAAAAAAAAAAAAAAAAAAAAAAA', launcher: { label: 'Ask us' } })

WidgetHandle#

import { init } from '@recent-visits/widget'

const widget = init({ key: 'rvk_AAAAAAAAAAAAAAAAAAAAAAAA' })
widget.update({ appearance: 'dark', theme: { radius: 8 } })
document.querySelector('#chat-button')?.addEventListener('click', () => widget.open())
// later, for example when your single-page app unmounts:
widget.destroy()

From a script tag#

The auto-start tag does not hand you the handle, but because init returns the existing instance you can fetch it:

<script
  src="https://recent-visit.com/widget/1/widget.js"
  data-key="rvk_AAAAAAAAAAAAAAAAAAAAAAAA"
  async
></script>
<script>
  window.addEventListener('load', function () {
    var widget = window.RecentVisits.init({ key: 'rvk_AAAAAAAAAAAAAAAAAAAAAAAA' })
    widget.open()
  })
</script>

createClient(options) (headless)#

function createClient(options: ClientOptions): Client

ClientOptions: key (required), apiBase, storage ('memory' by default for the client; 'session' keeps the session token in sessionStorage), timeoutMs (default 30,000; chat streams get 120,000), fetch (inject your own) and getChallengeToken. It never uses cookies (credentials: 'omit') or localStorage. The client creates and renews its session by itself.

Chat events#

chat takes { message, conversationId?, visitorName?, tourSlug? } and calls onEvent with a ChatEvent:

It resolves to { status: 'streamed', conversationId }, { status: 'closed' } (the agency closed the conversation) or { status: 'queued', conversationId } (a person has taken over; the message was queued for them). Pass the returned conversationId on the next call to continue the conversation.

import { createClient, WidgetApiError } from '@recent-visits/widget'

const client = createClient({ key: 'rvk_AAAAAAAAAAAAAAAAAAAAAAAA', storage: 'session' })

export async function ask(message: string, conversationId?: string) {
  let reply = ''
  const result = await client.chat({ message, conversationId }, (event) => {
    if (event.type === 'text') reply += event.delta
    if (event.type === 'error') console.error(event.message)
  })
  return { reply, conversationId: result.status === 'closed' ? undefined : result.conversationId }
}

export async function loadTours() {
  try {
    return await client.tours({ limit: 6, difficulty: 'easy' })
  } catch (error) {
    if (error instanceof WidgetApiError && error.code === 'rate_limited') return []
    throw error
  }
}

Quote requests#

QuoteInput requires name, email, message and consent: true; optional tourSlug (your tour), conversationId, phone, country, travelDate, durationDays, travelers, budget, currency. A website field is a bot trap: leave it empty. Only send consent: true after the visitor has agreed to share their details with the agency. See Examples.

Errors: WidgetApiError#

Every failed call throws WidgetApiError with code, status (HTTP status, 0 for network) and sometimes retryAfter (seconds). It never contains the session token.

Helpers and constants#

• resolveConfig(input) returns { config, warnings }: the validated, complete configuration and the list of console warnings for an options object. Useful for checking your options without starting the widget.
• linkify(text) and safeHref(url): the helpers the widget uses to make links from text (only https and Recent Visits paths become links).
• DEFAULT_API_BASE: https://recent-visit.com.
• Exported types include InitOptions, WidgetHandle, WidgetOptions, AppearanceOptions, ThemeInput, NotificationsInput, Client, ClientOptions, ErrorCode, SessionInfo, PublicConfig, Tour, TourQuery, ChatInput, ChatEvent, ChatResult, HandoffResult, MessagesResult, AgencyMessage and QuoteInput.

Data shapes#

A session lasts 30 minutes of inactivity and at most 12 hours in total; the client renews it before it expires. tours limits: limit 1 to 24 (default 12), minDays and maxDays 1 to 60.

Server validation of a quote request#

The server refuses a quote request that fails these rules with invalid_request: name 2 to 120 characters, a valid email, message 10 to 3,000 characters, phone up to 40, country up to 80, travelDate as YYYY-MM-DD, durationDays 1 to 120, travelers 1 to 50, currency three letters (default USD), consent exactly true, and no unknown fields. A successful request returns HTTP 201. The same email asking about the same tour again within a day is refused with rate_limited.

HTTP endpoints#

The widget and client talk to https://recent-visit.com/api/widget/v1 (a different apiBase for staging). These endpoints exist for the SDK; use the SDK rather than calling them yourself.

Calls other than config and starting a session use Authorization: Bearer <session token>. There is no cookie authentication. Within version 1 the service only adds optional fields and new error codes; see Versioning.