Ontwikkelaarsgids

API vir besoekeridentifikasie

Identifiseer aangemelde gebruikers programmaties sodat hulle nooit die e-posvraag sien nie, en hul gesprekke outomaties aan 'n kontak gekoppel word.

Wanneer om dit te gebruik

As jou webwerf aangemelde gebruikers het (SaaS-apps, paneelborde, ledeportale), weet jy reeds wie hulle is. Gebruik die identify-opdrag om hul e-pos aan Sonny deur te gee sodat hulle dit nie weer hoef in te voer nie.

Slaan die e-posvraag heeltemal oor vir aangemelde gebruikers
Koppel kletsgesprekke outomaties aan hul kontakrekord
Sien die besoeker se naam en e-pos dadelik in jou inkassie
Gaan voort met geskiedenis oor blaaiers en toestelle heen met geverifieerde identiteit

Kontinuïteit oor toestelle heen

Geverifieerde besoekeridentiteit

Basiese e-posidentifikasie is gerieflik, maar die blaaier kan enige e-pos beweer. Geverifieerde identiteit voeg 'n kortstondige JWT by wat deur jou bediener onderteken is. Sonny kan dan die kliënt se kontak veilig as die eienaar van hul webwerf-kletsgeskiedenis gebruik, sodat dieselfde gesprekke op 'n ander blaaier of toestel verskyn.

Af

Die verstek. Niks verander vir bestaande inbeddings of besoekers nie; geskiedenis bly aan die blaaier se besoeker-ID gekoppel.

Opsionele verifikasie (aanbeveel)

Geldige JWT's kry geskiedenis oor toestelle heen. Besoekers sonder 'n JWT behou die bestaande anonieme of e-pos-identify-ervaring.

Vereis bewys om te identifiseer

Anonieme klets werk steeds, maar identify- en pasgemaakte-kenmerk-oproepe vereis 'n geldige ondertekende JWT.

Verifikasiemodus maak nie verpligte voorkletsvelde opsioneel nie. Sien hoe elke modus aan 'n verpligte e-pos voldoen onder verpligte voorklets-besonderhede.

1. Genereer 'n ondertekeningsgeheim

Maak Kanale → jou kanaal → Regstreekse klets oop, vind Veilige besoekeridentiteit, kies 'n modus en genereer 'n geheim. Die gewone teks word een keer gewys. Stoor dit in jou agterkant se geheimbestuurder as SONNY_IDENTITY_SECRET. Sit nooit die ondertekeningsgeheim in blaaierkode, 'n inbedbrokkie, 'n openbare omgewingsveranderlike of jou bronkodebewaarplek nie.

2. Skep 'n kortstondige JWT op jou agterkant

Onderteken met HS256. Sonny vereis user_id, email, iat en exp. Die user_id moet 'n stabiele ID uit jou eie databasis wees, nie 'n e-posadres nie. Tokens kan hoogstens 24 uur leef; 15 minute is 'n goeie verstek. Horlosies mag tot 60 sekondes verskil.

Jy kan ook 'n bediener-ondertekende traits-objek insluit vir betroubare ondersteuningskonteks soos merchantName, subdomain, plan, platform en role. Eienskapwaardes moet strings, eindige getalle, booleans of null wees. Sonny stoor hulle op die webwerfgebonde geverifieerde kontakidentiteit. Kenmerke wat die blaaier verskaf, bly ongeverifieer en word nooit tot hierdie ondertekende eienskappe bevorder nie.

Node.js

import { SignJWT } from 'jose';

export async function createSonnyIdentityToken(user) {
  const secret = new TextEncoder().encode(process.env.SONNY_IDENTITY_SECRET);

  return new SignJWT({
    user_id: String(user.id),
    email: user.email,
    traits: {
      merchantName: user.merchant.name,
      subdomain: user.merchant.subdomain,
      plan: user.merchant.plan,
      platform: user.merchant.platform,
      role: user.role
    }
  })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('15m')
    .sign(secret);
}

Ruby

require 'jwt'

def sonny_identity_token(user)
  now = Time.now.to_i
  payload = {
    user_id: user.id.to_s,
    email: user.email,
    traits: {
      merchantName: user.merchant.name,
      subdomain: user.merchant.subdomain,
      plan: user.merchant.plan,
      platform: user.merchant.platform,
      role: user.role
    },
    iat: now,
    exp: now + 15 * 60
  }

  JWT.encode(payload, ENV.fetch('SONNY_IDENTITY_SECRET'), 'HS256')
end

Python

import os
from datetime import datetime, timedelta, timezone
import jwt

def sonny_identity_token(user):
    now = datetime.now(timezone.utc)
    return jwt.encode({
        "user_id": str(user.id),
        "email": user.email,
        "traits": {
            "merchantName": user.merchant.name,
            "subdomain": user.merchant.subdomain,
            "plan": user.merchant.plan,
            "platform": user.merchant.platform,
            "role": user.role,
        },
        "iat": now,
        "exp": now + timedelta(minutes=15),
    }, os.environ["SONNY_IDENTITY_SECRET"], algorithm="HS256")

PHP

use Firebase\JWT\JWT;

function sonnyIdentityToken($user): string {
    $now = time();
    return JWT::encode([
        'user_id' => (string) $user->id,
        'email' => $user->email,
        'traits' => [
            'merchantName' => $user->merchant->name,
            'subdomain' => $user->merchant->subdomain,
            'plan' => $user->merchant->plan,
            'platform' => $user->merchant->platform,
            'role' => $user->role,
        ],
        'iat' => $now,
        'exp' => $now + (15 * 60),
    ], $_ENV['SONNY_IDENTITY_SECRET'], 'HS256');
}

3. Gee net die JWT aan die widget

Gee die JWT terug vanaf 'n eindpunt wat deur jou gewone toepassingsessie beskerm word. Roep identify voor of ná init. Die widget hou die JWT net in geheue: dit word nooit in localStorage, koekies of 'n URL gestoor nie.

JavaScript

// Fetch a short-lived JWT from your authenticated backend.
// Your signing secret never reaches this code.
const { userJwt } = await fetch('/api/sonny-identity').then((res) => res.json());

sonny('identify', { userJwt });
sonny('init', { siteId: 'YOUR_SITE_ID' });

// Sonny asks for a fresh token after expiry or an emergency key change.
window.addEventListener('sonny:identity-required', async () => {
  const { userJwt } = await fetch('/api/sonny-identity').then((res) => res.json());
  sonny('identify', { userJwt });
});

Verfris, meld af en roteer veilig

Verfris: verfris die JWT voordat dit verval — omtrent 10 minute vir 'n token van 15 minute — en roep dan sonny('identify', { userJwt }). Luister ook vir sonny:identity-required as die terugval vir verstryking of 'n verandering van ondertekeningsleutel.
Afmelding: roep sonny('reset'). Dit laat die JWT in geheue val, maak die blaaier se widget-sessie skoon en begin 'n nuwe anonieme besoeker.
Wissel van rekening: roep sonny('reset') vir gebruiker A voordat jy gebruiker B se JWT haal en sonny('identify', { userJwt }) roep. Dra nooit een gebruiker se token oor na 'n ander aangemelde sessie nie.
Roetine-rotasie: Sonny aanvaar die vorige geheim vir 24 uur, wat jou tyd gee om elke agterkant-instansie by te werk. 'n Tweede roetine-rotasie word geblokkeer totdat daardie oorvleueling eindig.
Vermoedelik uitgelekte geheim: kies Vervang onmiddellik. Albei ou ondertekeningsleutels hou dadelik op om nuwe versoeke te verifieer; gekoppelde widgets vra die gasheerbladsy vir 'n vars JWT.
Skakel verifikasie af: Sonny gooi die huidige en vorige ondertekeningsgeheime weg en ontkoppel geverifieerde widgets. Genereer 'n nuwe geheim voordat jy verifikasie weer aanskakel.

Identiteitskonflikte word nie outomaties saamgevoeg nie

As 'n stabiele gebruikers-ID en e-pos na verskillende Sonny-kontakte wys, gee verifikasie 'n konflik terug in plaas daarvan om kliëntrekords stilweg te kombineer. Korrigeer die token of voeg die kontakte in Sonny saam, en probeer dan weer.

'n Klets wat net deur 'n vroeëre ongetekende e-pos gekoppel is, word nie outomaties as geverifieerde geskiedenis behandel nie. Dit verhoed dat 'n e-pos wat die blaaier verskaf 'n ander kliënt se gesprekke ontsluit.

Hulpsentrum-aanmelding

Koppel jou bestaande kliëntaanmelding aan gehoste of pasgemaakte-domein-hulpbladsye. Gebruik dieselfde webwerf-ondertekeningsgeheim en kortstondige JWT as die widget. Basiese e-posidentifikasie en Sonny-personeelaanmelding gee nie geverifieerde lesertoegang nie.

Voltooi die opstelling van geverifieerde besoekeridentiteit hierbo vir hierdie kanaal. Skakel Opsionele verifikasie of Vereis bewys om te identifiseer aan onder Kanale → jou kanaal → Regstreekse klets.
Implementeer 'n geverifieerde eindpunt in jou app wat { "userJwt": "SIGNED_TOKEN" } teruggee. Skep die token op jou bediener uit die aangemelde kliënt en betroubare eienskappe; aanvaar nooit 'n versoekte plan of rol vanaf die blaaier nie.
Kies in Kanale → jou kanaal → Hulpsentrum → Hulpsentrumtoegang die opsie Geverifieerde kliënte en 'n opsionele Kliëntgehoor. Voer jou app se aanmeldbladsy as Kliëntaanmeld-URL in en kies Stoor toegang.
Nadat die kliënt aangemeld het, voer die uitruil hieronder uit en vervang YOUR_SLUG met die hulpsentrum se Adres. Die aanmeld-URL alleen is nie genoeg nie: jou app moet hierdie uitruil voltooi.

JavaScript

// Run after your application authenticates the customer.
// This endpoint must use the server's session and trusted customer traits.
const response = await fetch('/api/sonny-identity');
if (!response.ok) throw new Error('Unable to sign in to the help center');
const { userJwt } = await response.json();
const signIn = new URL('https://www.usesonny.com/help/YOUR_SLUG/auth');
signIn.searchParams.set('token', userJwt);
signIn.searchParams.set('return', '/help/YOUR_SLUG');
window.location.assign(signIn);

Vir 'n pasgemaakte domein stel jy signIn op https://help.example.com/auth en keer terug na / of /articles/getting-started. Gehoste terugkeerpaaie begin met /help/YOUR_SLUG. Terugkeerbestemmings moet op dieselfde gasheer bly.

Die uitruil stel 'n veilige, HTTP-only koekie en herlei om die token uit die URL te verwyder. Die lesersessie verval saam met die JWT, tot 24 uur. Gebruik kortstondige tokens en vermy om die uitruil-URL te log. Die JWT hoort in hierdie een aanmelduitruil, nie in gedeelde artikelskakels nie.

Toets aanmelding en toegang

Besoek 'n privaat sentrum terwyl jy afgemeld is. Volg sy aanmeldknoppie, meld by jou app aan en bevestig dat jy terugkeer na die hulpsentrum op dieselfde gehoste of pasgemaakte domein.
Gaan een toegelate en een geweierde artikel na in blaai, soek en per direkte URL. 'n Kliënt buite die sentrum se gehoor sien 'n toegangsboodskap; 'n geweierde artikel gee nie gevind nie.
Gebruik Meld af in die hulpsentrum en verifieer dat privaat inhoud verdwyn. Herhaal met 'n kliënt wat ander eienskappe het.

Verfris en meld af

Die widget stuur sy huidige JWT outomaties. Verfris dit wanneer Sonny een versoek, en roep sonny('reset') wanneer jou kliënt afmeld. Die widget-identiteit en hulpsentrum-koekie is apart: om die widget terug te stel, meld nie 'n gehoste hulpsentrum-sessie af nie.

Om van gehoste bladsye af te meld, gaan na /help/YOUR_SLUG/auth/logout; op jou pasgemaakte domein gebruik jy /auth/logout. Koppel daardie aksie aan jou app se afmeldvloei as jy albei sessies moet beëindig. Ongeldige of verstreke geloofsbriewe het besoekertoegang. Met identiteitsverifikasie af het elke leser besoekertoegang.

Wanneer kliënteienskappe verander, skep 'n vars JWT en identifiseer weer in die widget; herhaal die aanmelduitruil vir gehoste bladsye. Bestaande leserkoekies behou die vorige ondertekende eienskappe totdat hulle verval. Gehoorreëlveranderinge geld by die volgende versoek.

Skep gehore, kyk na toegang en los beperkings op

E-posidentifikasie is nie verifikasie nie

Die e-posvorm wat die blaaier verskaf, verbeter ondersteuningskonteks, maar dit verifieer nie die besoeker nie. 'n Besoeker kan JavaScript op hul eie bladsy ondersoek en uitvoer, so e-pos, naam en pasgemaakte kenmerke ontsluit nooit 'n ander kliënt se Sonny-geskiedenis nie. Geverifieerde identiteit vereis die bediener-ondertekende JWT wat hierbo beskryf word. Hou magtiging vir aksies in jou eie produk binne jou aangemelde toepassing.

Wanneer besoekerverifikasie aangeskakel is, beteken 'n Geverifieer-kenteken in die inkassie dat die gesprek met 'n bediener-ondertekende JWT gekoppel is. 'n Ongeverifieer-kenteken beteken geen bediener-ondertekende identiteit het die gesprek geverifieer nie. Enige naam of e-pos wat gewys word, is ondersteuningskonteks wat die besoeker verskaf het, nie bewys van identiteit nie.

Kodevoorbeelde

Die eenvoudigste oproep — gee net die gebruiker se e-pos deur:

JavaScript

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

Gee ook die gebruiker se naam deur, sodat agente dit in die inkassie sien:

JavaScript

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

Voeg nuttige ondersteuningskonteks tydens identifikasie by, werk dit later by, of hou 'n waarde dop wat verander terwyl die bladsy oop is:

JavaScript

// Identify with support context
sonny('identify', {
  email: 'jane@example.com',
  name: 'Jane Smith',
  attributes: {
    plan: 'starter',
    seats: 5,
    trial: true
  }
});

// Update only the values that changed
sonny('setAttributes', {
  plan: 'growth',
  seats: 8,
  trial: null // Clears this property
});

// Keep a changing value in sync (checks every 10 seconds)
sonny('watchAttributes', () => ({
  monthly_usage: window.currentUsage
}), { interval: 10000 });

Volledige voorbeeld met die asinchrone brokkie. Let op dat identify voor init geroep kan word — die identiteit word in 'n tou geplaas en gestuur sodra die widget koppel:

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>

Roep reset wanneer die gebruiker afmeld om hul identiteit skoon te maak en 'n nuwe sessie te begin:

JavaScript

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

Hoe dit werk

01
Widget laai en koppel
Die widget koppel aan Sonny en stuur enige gestoorde identiteit saam wanneer dit aansluit.
02
Identiteit word na die bediener gestuur
Sonny soek 'n kontak met daardie e-pos in jou werkspasie, en skep een as dit nog nie bestaan nie.
03
Gesprekke word gekoppel
Enige ongekoppelde gesprekke in die huidige blaaier se besoekersessie word aan die geïdentifiseerde kontak gekoppel. Identifikasie voeg nie geskiedenis tussen blaaiers of toestelle saam nie.
04
E-posvraag word oorgeslaan
Omdat die besoeker reeds geïdentifiseer is, word die e-posvraag in die widget onderdruk — geen onderbreking vir die gebruiker nie.

Reëls vir pasgemaakte kenmerke

Stuur hoogstens 50 kenmerke per oproep.
'n Waarde kan 'n string, getal, boolean of null wees. Strings is beperk tot 1000 karakters. Gee null of 'n leë string deur om 'n gestoorde waarde skoon te maak.
Sleutels moet met 'n letter begin en net letters, syfers en onderstrepe bevat, met 'n maksimum van 64 karakters.
Hierdie sleutels is gereserveer en word geïgnoreer: email, name, id, phone, createdAt, updatedAt.

API-verwysing

sonny('identify', { email, name?, attributes? }): Identifiseer die huidige besoeker. Stel die e-pos en opsionele naam, slaan die e-posvraag oor en stuur die identiteit na die bediener. Kan voor of ná init geroep word.; emailstringBesoeker se e-posadres
namestring?Besoeker se vertoonnaam
attributesobject?Pasgemaakte kenmerke om aan die kontak te heg (sien die gids tot widget-opstelling vir sleutel- en waardereëls)
sonny('identify', { userJwt, name?, attributes? }): Identifiseer die huidige aangemelde kliënt veilig vanaf 'n JWT wat deur die bediener gegenereer is. Die token bly in geheue en word net in geverifieerde versoek- of socket-vragte gestuur.; userJwtstring'n Vars HS256-JWT wat deur jou geverifieerde agterkant geskep is
namestring?Besoeker se vertoonnaam
attributesobject?Pasgemaakte kenmerke om aan die geverifieerde kontak te heg
sonny('setAttributes', { ... }): Werk pasgemaakte kenmerke vir die geïdentifiseerde besoeker by. Net veranderde waardes word gestuur. As die besoeker nog nie geïdentifiseer is nie, wag opdaterings en word gestuur nadat identify geloop het.; attributesobjectSleutel-waarde-pare om te stel. Gee null as waarde deur om 'n kenmerk skoon te maak.
sonny('watchAttributes', getter, { interval? }): Roep jou getter-funksie op 'n tydhouer en sinkroniseer enige veranderde kenmerke outomaties. Nuttig wanneer waardes soos plan of gebruik verander terwyl die bladsy oop is.; getterfunction'n Funksie wat die huidige kenmerke-objek teruggee
intervalnumber?Hoe gereeld om na te gaan, in millisekondes. Verstek 10000, minimum 2000.
sonny('reset'): Maak die huidige blaaier se widget-ID, e-pos, naam en plaaslike gespreksgeskiedenis skoon, en begin dan 'n nuwe besoekersessie. Dit skrap nie die kontak of hul gestoorde eienskappe in Sonny nie. Gebruik dit by afmelding.

Het jy hulp nodig?

Kyk na die gids tot widget-opstelling of kontak ons span.

Gids tot widget-opstelling Kontak ons

Verwante dokumentasie

Sien hoe Sonny help

Regstreekse kletssagteware
Regstreekse kletssagteware met 'n aanpasbare webwerfwidget, besoekeridentifikasie, spantoewysing, gespreksgeskiedenis, mobiele apps en opsionele KI.

Wanneer om dit te gebruik

Geverifieerde besoekeridentiteit

Af

Opsionele verifikasie (aanbeveel)

Vereis bewys om te identifiseer

1. Genereer 'n ondertekeningsgeheim

2. Skep 'n kortstondige JWT op jou agterkant

3. Gee net die JWT aan die widget

Verfris, meld af en roteer veilig

Identiteitskonflikte word nie outomaties saamgevoeg nie

Hulpsentrum-aanmelding

Toets aanmelding en toegang

Verfris en meld af

E-posidentifikasie is nie verifikasie nie

Kodevoorbeelde

Hoe dit werk

Widget laai en koppel

Identiteit word na die bediener gestuur

Gesprekke word gekoppel

E-posvraag word oorgeslaan

Reëls vir pasgemaakte kenmerke

API-verwysing

Het jy hulp nodig?

Verwante dokumentasie

Sien hoe Sonny help