sóley

Sóley docs

Widget install & troubleshooting

How to add the Sóley booking widget to your website, and what to do when something looks off. For the product overview, see the widget marketing page.

On this page

Before you start

You need three things:

  1. A live Sóley operator profile. If you have not onboarded yet, start here.
  2. Your widget ID. Generate it from your operator dashboard under Settings → Embed on your site.
  3. Your website’s domain on the operator allowlist. The widget only loads on domains you have explicitly added. You add them on the same Settings page above.

The snippet

One <script> tag, anywhere before the closing </body>. Replace your-widget-id with the widget ID from your dashboard.

<script type="module"
  src="https://widget.soley.travel/v1.0.0/loader.js"
  data-soley-operator-id="your-widget-id"
  data-soley-modes="book,chat"
  data-soley-primary-color="#0066cc"></script>

Attribute reference:

  • data-soley-operator-id (required): your widget ID. UUID.
  • data-soley-modes (optional): any of book, chat. Defaults to both.
  • data-soley-primary-color (optional): hex like #0066cc. Defaults to Sóley gold.
  • data-soley-service-id (optional): if set, the Book-now flow opens with this service pre-selected. Otherwise the guest picks from a list.

WordPress

Three ways depending on your setup:

  1. Theme editor (most themes). Appearance → Theme File Editor → open footer.php. Paste the snippet just before </body>. Save.
  2. Custom HTML widget (no theme editor access). Appearance → Widgets → add a “Custom HTML” block to the Footer area. Paste the snippet.
  3. Insert-headers-and-footers plugin. Install “Insert Headers and Footers” or any equivalent. Paste the snippet into the “Scripts in Footer” box.

On a multisite, install per-site rather than network-wide so each site keeps its own widget ID.

Wix

  1. Open the editor. Click Settings → Custom Code.
  2. Click Add Custom Code.
  3. Paste the snippet. Set Add Code to Pages to All pages. Place code in Body - end.
  4. Click Apply. Re-publish the site.

Wix Premium plan required for custom code. Free plans cannot embed third-party scripts.

Squarespace

  1. Open the dashboard. Go to Settings → Developer Tools → Code Injection.
  2. Paste the snippet into the Footer box.
  3. Click Save.

Code Injection requires the Business plan or higher. Personal plans cannot embed third-party scripts.

Static HTML

Paste the snippet directly before </body> in your HTML template. If your site is split across many pages, put it in the shared footer include.

Next.js, React, or any framework

The loader is a plain <script> tag. Most frameworks accept it in the root layout’s <body> as long as it runs client-side.

For Next.js App Router specifically, drop the snippet into the root app/layout.tsx <body> using the next/script component with strategy=“afterInteractive”. The widget mounts itself in a Shadow DOM, so it will not interfere with React hydration.

Domain verification

Three ways to prove the operator controls a domain. Pick whichever fits your setup; each is sufficient.

  1. Loader heartbeat. The default. As soon as the widget loads on your site for the first time, Sóley records a heartbeat and the domain shows as verified in the dashboard. No operator action needed.
  2. HTML meta tag. Use this to verify before installing the loader. Paste a <meta name="soley-widget-verification" content="<token>"> tag inside your page’s <head>. The token comes from the verification panel in your dashboard. Works on any platform that lets you edit the page head.
  3. DNS TXT record. Escape hatch for JavaScript-rendered SPAs that do not serve a static <head>. Add a TXT record soley-verify=<token> at your domain root. DNS propagation can take a few minutes after the change.

Troubleshooting

The Book-now button does not appear.
Check three things, in order: (1) the widget ID in the snippet matches the one in your dashboard; (2) the page’s domain is on your widget_allowed_origins list; (3) the snippet sits inside <body>, not <head>. Open the browser devtools console; the loader logs a clear error for each of these.
The widget loads on staging but not on production.
Add the production domain to your allowlist on the dashboard Settings page. The allowlist is exact-match on the origin (scheme + host + port). If you serve from both https://example.com and https://www.example.com, add both.
The chat bubble loads but typing nothing happens.
Likely a Content Security Policy blocking EventSource / fetch to api.soley.travel. See the CSP section below.
Colours look wrong.
The data-soley-primary-color attribute must be a 6-character hex like #0066cc. The widget derives a WCAG-AA contrast ramp from this colour; very-light or very-dark inputs may give a low-contrast result. Adjust toward a mid-luminance brand colour.
Booking redirects to the payment processor and back, but the booking does not appear in my dashboard.
The payment processor webhook may be misconfigured. Check the processor’s webhook log for delivery failures, then contact Sóley support and we will reconcile manually.

Content Security Policy

If your site uses a strict CSP, add these directives:

script-src    'self' https://widget.soley.travel;
connect-src   'self' https://api.soley.travel;
img-src       'self' data: https://*.soley.travel;
style-src     'self' 'unsafe-inline';

The style-src ‘unsafe-inline’ is needed for the widget’s Shadow DOM stylesheet. The widget never loads external CSS, only its own bundled styles, isolated inside the Shadow DOM so they cannot leak into your site.

Theming

The data-soley-primary-color attribute drives a WCAG-AA contrast ramp: hover, active, focus, and text-on-primary are all derived so the colour you set is the colour guests see, and the result still meets accessibility contrast thresholds.

Live preview is on the dashboard Settings page so you can test a colour before publishing.

Beyond colour: removing the “Powered by Sóley” footer, custom fonts, or replacing the bubble icon are roadmap items, not v1 features. If you need them, tell us.

FAQ

Does the widget work without JavaScript?
No. The widget is a JavaScript loader; on no-JS browsers the Book-now button and chat bubble simply do not render. Your site’s existing booking path remains the no-JS fallback.
Can I run multiple widget IDs on the same page?
Not in v1. The loader expects exactly one operator per page. If you need multi-operator embeds, tell us. The underlying shadow-DOM isolation supports it, but the loader currently hard-binds to one operator.
How do I uninstall?
Remove the <script> tag from your site. The widget disappears. The widget ID stays valid in your dashboard so you can reinstall later.
Where do I see widget bookings?
Your normal bookings dashboard. Widget bookings carry a source: widget attribution so you can filter if you want to track widget vs directory vs WhatsApp.

Still stuck? Message us from your dashboard and we will dig in.