← Documentación

Website widget

The widget is a single <script> tag that adds an Equilia persona to your site as a floating chat button. You do not write the tag yourself — the dashboard generates one already carrying your organization, persona and public key.

Before you start

A widget needs a persona attached to an origin — the domain the widget is allowed to run on. Each origin has its own public key, and the widget will refuse to start without one. If the dashboard tells you the persona has no associated origin, add the domain under Origins first, then come back.

Origins are why the public key is safe to publish: it only works from a domain you have registered.

Getting your snippet

  1. Open the dashboard and go to Personas.
  2. Select the persona you want to embed.
  3. Copy the widget script shown for it.
  4. Paste it into your site's HTML, just before the closing </body> tag.

What you get back looks like this, with your own values filled in:

<script
  src="https://equilia.site/api/v1/static/js/widget-script.js?v=1.0.14"
  data-config='{"ORG_ID":"...","PERSONA_ID":"...","PUBLIC_KEY":"...","WIDGET_POSITION":"bottom-right"}'
></script>

The configuration travels in a data-config attribute rather than an inline script, so the tag works on sites with a strict Content Security Policy that blocks inline JavaScript.

What the snippet carries

The inline configuration holds only what is needed to paint the launch button before anything loads. Everything else — header text, landing slides, enabled channels, language — is fetched from your persona the first time a visitor opens the widget, so most changes take effect without touching the tag.

  • ORG_ID, PERSONA_ID, PUBLIC_KEY — identify the persona and authorize the domain.
  • WIDGET_POSITION — where the button sits, for example bottom-right.
  • WIDGET_THEME — the colour set applied to the button and panel.
  • WIDGET_BUTTON_ICON_ONLY — show the chat icon instead of a text button. This is in the inline config on purpose: without it, an icon-only widget would briefly flash as a full text button before the persona configuration arrives.
  • EMBED_MODE — open the conversation in an inline panel rather than a new window.
  • API_BASE — only needed when self-hosting; otherwise it is derived from the script's own URL.

Because these values render the first frame, changing them means copying a fresh snippet from the dashboard. Everything else is live.

Embedding in the page instead of floating

By default the conversation opens in a new window. Setting EMBED_MODE keeps it inside an inline panel instead. If you want that panel in a specific place rather than floating over the page, add EMBED_CONTAINER_ID with the id of an element you have already rendered, and the widget will mount into it.

There is also STANDALONE_PAGE, which hides the launch button, opens the conversation immediately, and prevents closing it. That is what you want for a page whose only purpose is the conversation — a kiosk screen, or a link you send someone.

A hosted page, with nothing to embed

If a standalone conversation page is all you need, you do not have to build one. Every persona already has one, at an address made from two slugs — your organization's and the persona's:

https://widget.equilia.site/<org-slug>/<persona-slug>

It loads that persona's own configuration and opens the conversation straight away, so there is no script tag to paste and nothing to host. Send the link, or point a kiosk browser at it.

Both slugs come from your settings, and changing either one changes the link — so settle on them before you share it widely or print it.

Channels

A persona can offer several ways to talk, and the widget shows only the ones you have enabled: web chat, phone, video, SMS, WhatsApp, Telegram, Facebook Messenger and Instagram. Enable them per persona in the dashboard; the widget picks the change up on its next load.

Single-page applications

The tag is plain HTML and expects to be present when the page loads. In React, Vue or Angular, put it in the host HTML file — index.html, or the document template your framework renders into — rather than inside a component. Injecting it from a component after navigation means document.currentScript is no longer the widget's own tag, and the configuration will not be read.

Troubleshooting

  • Nothing appears. Check the browser console. The most common cause is the domain not matching a registered origin, which the public key is checked against.
  • The button looks wrong for a moment. That is the first paint using the inline configuration before your persona settings load. If the flash is on an icon-only button, re-copy the snippet — it should carry WIDGET_BUTTON_ICON_ONLY.
  • A blocked script on a strict CSP site. The widget avoids inline JavaScript, but the script's own origin still needs to be allowed by your script-src.

Collecting contact details

Whether the widget asks visitors for an email address or phone number, and whether it verifies them with a code, is a persona setting rather than a widget one — persona → Security → Require lead validation. Leave it off for anonymous chat; turn it on when you want leads you can contact afterwards.

For a walk-up screen with no contact details at all, see the QR code kiosks guide. To drive conversations from your own backend instead of the browser, see the SDKs.