Widget installation

Basic installation

Add this script tag to your website, just before the closing </body> tag:

<script>
  (function(w,d,s,o,f,js,fjs){
    w['Sonny']=o;w[o]=w[o]||function(){
    (w[o].q=w[o].q||[]).push(arguments)};
    js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
    js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
  })(window,document,'script','sonny','https://www.usesonny.com/widget.js');
  sonny('init', { siteId: 'YOUR_SITE_ID' });
</script>

Auto-init snippet

You can also use a single script tag if you do not need to queue commands before the widget loads:

<script
  src="https://www.usesonny.com/widget.js"
  data-site-id="YOUR_SITE_ID"
  async
></script>

Identify visitors & send custom attributes

Once a user logs in to your site, call sonny('identify') with their email and any extra data you want your support team to see. Pass extra fields under attributes — new keys are created as Custom Fields automatically and shown on the right-hand side of the conversation. Subsequent calls overwrite the previous value.

<script>
  // Identify the visitor and pass any custom attributes you want
  // surfaced in the agent sidebar. Unknown keys are auto-created
  // as Custom Fields in your workspace settings.
  sonny('identify', {
    email: 'jane@acme.com',
    name: 'Jane Doe',
    attributes: {
      plan: 'pro',
      mrr: 499,
      signedUpAt: '2025-08-01T00:00:00Z',
      website: 'https://acme.com'
    }
  });
</script>

Supported value types: string, number, boolean, ISO-8601 date, URL. Pass null to clear an attribute. Keys must start with a letter, use only letters, numbers, or underscores, and be at most 64 characters. The keys email, name, id, phone, createdAt and updatedAt are reserved. Text values are capped at 1,000 characters. Limit: 50 attributes per call.

Open the widget from your own button

Want to launch chat from your own button instead of the floating bubble? Pass hideLauncher: true to sonny('init') to hide the built-in launcher, then call sonny('open') from any element on your page.

<!-- 1. Boot Sonny with its built-in launcher hidden -->
<script>
  (function(w,d,s,o,f,js,fjs){
    w['Sonny']=o;w[o]=w[o]||function(){
    (w[o].q=w[o].q||[]).push(arguments)};
    js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
    js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
  })(window,document,'script','sonny','https://www.usesonny.com/widget.js');
  sonny('init', { siteId: 'YOUR_SITE_ID', hideLauncher: true });
</script>

<!-- 2. Open the chat from your own button, anywhere on the page -->
<button onclick="sonny('open')">Chat with us</button>

Three commands control the panel from anywhere on your page:

• sonny('open') — open the chat panel.
• sonny('close') — close it.
• sonny('toggle') — flip it open or closed, ideal for a single toggle button.
• sonny('getUnreadCount', callback) — read the current unread count at any time.

Prefer the single script-tag install? Add data-hide-launcher to the script tag to hide the launcher, then wire your button to the same commands.

Show unread replies on your own button

Hiding the launcher also hides its unread badge, so Sonny tells your page instead. The widget dispatches a sonny:unread event on window with detail.count — the same number the built-in launcher would show. Perfect for a badge on your own mobile navigation.

<button id="chat-button" onclick="sonny('open')">
  Chat with us
  <span id="chat-unread" hidden></span>
</button>

<script>
  function showUnread(count) {
    var badge = document.getElementById('chat-unread');
    badge.textContent = count > 9 ? '9+' : count;
    badge.hidden = count === 0;
  }

  // Fires once after the widget loads, then on every change.
  window.addEventListener('sonny:unread', function (event) {
    showUnread(event.detail.count);
  });

  // Optional: read the count on demand (e.g. after your own nav re-renders).
  sonny('getUnreadCount', showUnread);
</script>

The count covers unread agent replies across the visitor's conversations. It fires once shortly after the widget loads — so a listener added on page load always gets the current state — then again whenever it changes, including back to 0 once the visitor opens the chat.

Customization options

Customize the widget from your channel's "Live Chat" tab in Sonny.

Next steps

Now that your widget is installed, set up email forwarding too.

Related docs

• Widget customization

  Match the widget to your brand with colors, logos, messages, and behavior.

• Visitor identification

  Identify logged-in users and send custom attributes from your website.

• Email setup

  Forward your support email into Sonny and manage email alongside live chat.

• Channels

  Create and manage the places where customers reach you by live chat and email.