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.

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.

Customization options

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