Getting started: install Svellyo on your sites

Svellyo gives you one inbox for every product you run. Each product gets its own workspace with its own widget, knowledge base and settings, and every chat lands in the same place. This guide takes you from a new account to a working chat widget in about ten minutes.

Updated September 8, 2026

1. Create a workspace per product

A workspace is one product or site. Create the first one during onboarding, and add more from the workspace switcher at the top of the sidebar (New workspace). Workspaces are unlimited on every plan.

When you create a workspace you set:

Name – what visitors see as the team name unless you change it later.
Primary domain – the site the widget will live on.
Timezone – used for business hours and reports.

2. Install the widget

Open Settings → Installation in the workspace. Your workspace id starts with ws_ and is shown on that page. Pick the install method that matches your stack.

Any website (HTML, Webflow, Framer, Shopify, PHP)

Paste this before the closing </body> tag on every page. It loads asynchronously and never blocks your page.

<script async src="https://cdn.svellyo.com/v1/widget.js" data-workspace="ws_xxxxxxxx"></script>

Next.js or React

Install the SDK and render the component once in your root layout. It renders nothing itself and only injects the script tag.

npm i @svellyo/sdk

// app/layout.tsx
import { SvellyoWidget } from "@svellyo/sdk/react";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <SvellyoWidget workspaceId="ws_xxxxxxxx" />
      </body>
    </html>
  );
}

WordPress

Add the HTML tag above to a "Custom HTML" footer block, or to your theme's functions.php:

add_action('wp_footer', function () {
  echo '<script async src="https://cdn.svellyo.com/v1/widget.js" data-workspace="ws_xxxxxxxx"></script>';
});

Let an AI coding agent do it

Using Cursor, Claude Code or Copilot? The AI agent tab on the Installation page has a ready-made prompt. Copy it, paste it into your agent, and it will add the widget to the right file and ask you which routes should not show it.

3. Allow your domains

The widget only works on domains you allow. Go to Settings → General → Allowed origins and add each site, one per line:

https://acme.com
https://*.acme.com
http://localhost:3000

Use * to allow every domain while you are testing, then tighten it before launch. The widget also works automatically on your Svellyo help center.

4. Check that it works

Load your site. The launcher bubble appears in the bottom corner within a second or two. Send yourself a message, then open Inbox in the dashboard: the conversation is there in real time.

If the widget says "Chat is not available on this site", the page's domain is not in your allowed origins.

5. Identify signed-in users (optional but recommended)

If your product has accounts, tell Svellyo who is chatting so the inbox shows a name, email and any attributes you pass, and so the same person keeps their chat history across devices.

// after login
window.Svellyo("identify", {
  userId: user.id,
  email: user.email,
  name: user.name,
  attributes: { plan: user.plan, company: user.company },
});

With the React component, pass the user prop instead. Setting it to null on logout resets the visitor so the next person does not see previous chats.

<SvellyoWidget
  workspaceId="ws_xxxxxxxx"
  user={
    session ? { userId: session.user.id, email: session.user.email, name: session.user.name } : null
  }
/>

To stop anyone from spoofing another user, turn on verified identity under Settings → Installation. You sign the user id with your workspace secret on your server and pass the result as hash.

6. Hide the widget on some pages

You usually do not want a chat bubble on admin screens, checkout flows or embedded pages. Keep the single install in your root layout and list the routes to skip. The widget re-checks the list on every client-side navigation.

<SvellyoWidget workspaceId="ws_xxxxxxxx" excludePaths={["/admin/*", "/checkout", "/embed/**"]} />

Script tag installs use a comma-separated attribute:

<script
  async
  src="https://cdn.svellyo.com/v1/widget.js"
  data-workspace="ws_xxxxxxxx"
  data-exclude="/admin/*,/checkout"
></script>

Pattern rules:

PatternMatches/checkoutexactly /checkout/admin/*/admin and everything under it/docs/*/editone path segment in place of */**/embedany depth

You can also set this without touching code under Settings → Widget → Hide on these pages. It applies to every install of that workspace immediately. For moments like a video call, window.Svellyo("hide") and window.Svellyo("show") toggle the widget from your own code.

7. Make it yours

Settings → Widget has a live preview while you edit:

Appearance – theme, accent colour, light or dark mode, position, launcher style (bubble, pill or hidden), logo and agent avatar.
Messages – team name, welcome title and message, reply-time text, away message, suggested questions.
Behaviour – pre-chat form fields, auto-open after a delay or on specific pages, file attachments, notification sound, satisfaction rating and the What's new tab.

"Powered by Svellyo" branding is removed automatically on the Pro and Scale plans.

Widget commands

Every install exposes window.Svellyo(command, argument). The SDK wraps the same commands as Svellyo.open() and so on.

CommandWhat it doesopen, close, toggleControl the chat panelidentify, setAttributesLink the visitor to a user and add attributeshide, showHide or show the whole widgetsetExcludePathsReplace the excluded routes at runtimeopenConversationJump to a specific conversationresetClear the visitor session (call on logout)

Next steps

Train your AI agent and publish a help center
Invite teammates under Settings → Team. Free workspaces include 2 seats, Pro 5, Scale unlimited.
Connect Slack or Discord under Settings → Integrations to get pinged on new or escalated chats.

Was this helpful?

Knowledge Base of Svellyo