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:
// Identify a logged-in user
sonny('identify', {
email: 'jane@example.com'
});Pass the user's name too, so agents see it in the inbox:
// 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 when the socket connects:
<!-- Sonny widget snippet -->
<script>
(function(){
var w=window,d=document,s=d.createElement('script');
w.sonny=w.sonny||function(){(w.sonny.q=w.sonny.q||[]).push(arguments)};
s.src='https://widget.usesonny.com/widget.js';
s.async=true;d.head.appendChild(s);
})();
// 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:
// Reset on logout — clears identity and starts a fresh session
sonny('reset');How it works
Widget loads and connects
The widget connects to Sonny via WebSocket, sending any stored identity along with the join event.
Identity is sent to the server
The server upserts a contact by email and workspace, creating a new contact record if one doesn't exist.
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? })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 addressnamestring?Visitor's display namesonny('reset')Clears all stored visitor data (ID, email, name, conversation history), disconnects the socket, generates a fresh visitor ID, and reconnects. Use this on logout.