Developer Guide

Visitor Identification API

Programmatically identify logged-in users so they never see the email prompt, and their conversations are automatically linked to a contact.

When to use this

If your website has logged-in users (SaaS apps, dashboards, member portals), you already know who they are. Use the identify command to pass their email to Sonny so they don't have to enter it again.

Skip the email prompt entirely for logged-in users
Automatically link chat conversations to their contact record
See the visitor's name and email in your inbox immediately

Code examples

The simplest call — just pass the user's email:

JavaScript

// Identify a logged-in user
sonny('identify', {
  email: 'jane@example.com'
});

Pass the user's name too, so agents see it in the inbox:

JavaScript

// Identify with full name
sonny('identify', {
  email: 'jane@example.com',
  name: 'Jane Smith'
});

Full example with the async snippet. Note that identify can be called before init — the identity is queued and sent as soon as the widget connects:

HTML

<!-- Sonny widget snippet -->
<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');

  // Identify before init — identity is queued and sent on connect
  sonny('identify', {
    email: 'jane@example.com',
    name: 'Jane Smith'
  });

  sonny('init', { siteId: 'YOUR_SITE_ID' });
</script>

Call reset when the user logs out to clear their identity and start a fresh session:

JavaScript

// Reset on logout — clears identity and starts a fresh session
sonny('reset');

How it works

Widget loads and connects

The widget connects to Sonny and sends any stored identity along when it joins.

Identity is sent to the server

Sonny looks for a contact with that email in your workspace, and creates one if it doesn't exist yet.

Conversations are linked

Any existing conversations from this visitor that don't yet have a contact are automatically linked to the identified contact.

Email prompt is skipped

Since the visitor is already identified, the in-widget email prompt is suppressed — no interruption for the user.

API reference

sonny('identify', { email, name?, attributes? })

Identifies the current visitor. Sets the email and optional name, skips the email prompt, and sends the identity to the server. Can be called before or after init.

emailstringVisitor's email address

namestring?Visitor's display name

attributesobject?Custom attributes to attach to the contact (see the widget setup guide for key and value rules)

sonny('setAttributes', { ... })

Updates custom attributes for the identified visitor. Only changed values are sent. If the visitor isn't identified yet, updates wait and are sent after identify runs.

attributesobjectKey-value pairs to set. Pass null as a value to clear an attribute.

sonny('watchAttributes', getter, { interval? })

Calls your getter function on a timer and syncs any changed attributes automatically. Useful when values like plan or usage change while the page is open.

getterfunctionA function that returns the current attributes object

intervalnumber?How often to check, in milliseconds. Default 10000, minimum 2000.

sonny('reset')

Clears all stored visitor data (ID, email, name, conversation history), disconnects, starts a fresh visitor session, and reconnects. Use this on logout.

Need help?

Check out the widget setup guide or get in touch with our team.

Widget setup guide