Skip to main content

Widget and JavaScript SDK

One script tag on your site. The look is set in the Studio and applies live; what the agent may do is pinned to a version.

The widget is a web component served by your own instance, at /widget/widget.js. It renders with the design you set for the agent, from colors and shape to copy, launcher and zones. A saved design applies at once, without republishing the agent.

<script src="https://rikoo.example.com/widget/widget.js"
        data-rikoo-token="rk_wgt_..." defer></script>

The Studio gives you this snippet on the agent page: Deploy tab, Configure the widget, then the Go live section. The public token is its only attribute. It names the deployment, and the deployment carries the agent, the environment and the pinned version. The widget talks to the instance that served the script.

Behavior is frozen, presentation is live

The two change at different times, on purpose. A color change does not need a new agent version. A change to what the agent may do never reaches a visitor without one.

Controlling it from your page​

For more than a script tag, the SDK of the @rikoo/widget package gives you the widget as an object. You can open it in a display mode (compact, sidebar, fullScreen, modal), close it, hide it, start a new conversation, declare the screen the visitor is on with setContext, and subscribe to its events (open, close, conversation-started, turn-completed).

app.js
import rikoo from '@rikoo/widget';

const widget = rikoo.init({
  token: 'rk_wgt_...',
  appUrl: 'https://rikoo.example.com',
});

await widget.open.sidebar();
await widget.newConversation();

The display calls return a promise that settles once the widget has rendered the requested state. The script tag exposes the same object as window.rikoo, so a page without a bundler can call rikoo.init too. Each init call with a different token mounts one more widget on the page.

Knowing who is talking​

By default a visitor is anonymous and their conversation belongs to their browser. Each deployment has a visitor identity mode: anonymous (the default), verified or required. In the last two, your backend signs a short-lived assertion for each signed-in user, and the widget presents it before every turn. Rikoo checks the signature against the public key you registered and ties the conversation to that user, across their devices. In verified mode, a visitor without a valid assertion continues anonymously. In required mode, they are refused.

Rikoo only holds the public key, and a visitor cannot claim to be someone else by editing the page.

Working with the host page​

The widget can be allowed to read the field the visitor designates and write into it, to fill a form, to take a screenshot of the page, or to observe the page's network calls to origins you list. Each capability is off by default and needs two keys:

  • The operator enables it in the agent configuration (config.inPage). It is frozen with the agent version, so a change needs a new version.
  • The visitor triggers it with a gesture: placing the cursor in a field, or choosing the screenshot entry and sending the previewed image. Nothing is read before that gesture.

Network observation has no visitor gesture, because the data belongs to the site. The list of origins bounds it, and what leaves the browser is the method, status, origin and path, duration and size, never the query string or the headers. A bounded, scrubbed excerpt of the bodies is sent only if the operator also allows it. Filling a form sends the form's structure (types, labels, required fields, lists of choices), never what the visitor already typed, and the widget never submits it. A write into a field can be undone: the visitor gets their text back in one click.

Allowed origins are enforced on the server

A widget only answers for the origins you list on its deployment. Copying the script tag onto another domain does not work: the API checks the Origin of each request, not the script.

License​

The widget, its SDK and the browser extensions built from it are under the Rikoo Widget License, not the AGPL-3.0: embedding the widget never affects the license of your site. It is free of charge for every edition. You may embed it, and adapt it for that purpose, on the sites and applications you operate, so that their visitors talk to a Rikoo instance. You may not redistribute it as a standalone work, connect it to another backend, or use it to build a competing product.