Benutzer identifizieren

Standardmäßig ist jeder Besucher ein Gast. Wenn ein Benutzer auf Ihrer Website oder in Ihrer App angemeldet ist, kann Ihr Server für ihn ein kurzes Identitätstoken signieren. So weiß Kavchat, wer er ist.

Warum Benutzer identifizieren?

Ihre Benutzer-ID in jedem Ticket. Gespräche und Tickets werden mit der Benutzer-ID aus Ihrem System gekennzeichnet (userId im Ticket). So weiß Ihr Team, zu welchem Konto sie gehören.
Keine Kontaktdaten eingeben. Gäste müssen im Kontaktformular eine E-Mail-Adresse oder Telefonnummer angeben. Identifizierte Benutzer müssen das nicht.
Testbenutzer. Wenn als Zielgruppe „Testbenutzer“ ausgewählt ist, wird der Bot nur Benutzern angezeigt, deren Telefonnummer in Ihrer Testbenutzerliste steht. Kavchat erkennt sie anhand der Telefonnummer im Token.
Persönliche Begrüßung. {name} in einem Schritt des Skripts wird durch den Vornamen des Benutzers ersetzt.

Das Token

Das Identitätstoken ist ein gewöhnliches JWT, das auf Ihrem Server erstellt wird:

Algorithmus: HS256. Als Schlüssel dient Ihr geheimer Schlüssel: die gesamte Zeichenfolge sk_live_... als UTF-8-Bytes.
Die Seite oder App sendet das Token bei jedem Aufruf an Kavchat im Header Authorization: Bearer <token>.
Signieren Sie Tokens niemals im Browser oder in der App. Der geheime Schlüssel bleibt auf Ihrem Server.

Feld	Erforderlich	Beschreibung
`sub`	Ja	Die Benutzer-ID in Ihrem System, 1 bis 128 Zeichen.
`exp`	Ja	Ablaufzeitpunkt, höchstens 30 Tage in der Zukunft. In den SDKs beträgt die Gültigkeitsdauer standardmäßig 7 Tage.
`phone`	Nein	Im E.164-Format (`+972501234567`) oder als lokale Nummer. Dient zur Erkennung von Testbenutzern.
`name`	Nein	Wird in der Begrüßung angezeigt und im Kontaktformular vorausgefüllt.
`email`	Nein	Wird im Kontaktformular vorausgefüllt.

Erstellen Sie ein neues Token, wenn sich der Benutzer anmeldet, und erneut, bevor das bisherige abläuft. Eine kurze Gültigkeitsdauer von wenigen Tagen ist ein guter Standardwert.

Server-SDK installieren

Die Server-SDKs erstellen das Token für Sie, prüfen Webhooks und rufen die Server-API auf. Sie benötigen keine Abhängigkeiten außer der Standardbibliothek der jeweiligen Sprache (Java benötigt Jackson).

Node.js

yarn add @kavchat/node
# or: npm install @kavchat/node

Python

pip install kavchat

PHP

composer require kavchat/kavchat-php

Java

<!-- Maven, served by JitPack. Gradle: maven("https://jitpack.io") and implementation("com.kavchat:kavchat-java:0.0.11") -->
<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.kavchat</groupId>
  <artifactId>kavchat-java</artifactId>
  <version>0.0.11</version>
</dependency>

.NET

dotnet add package Kavchat

go get kavchat.com/kavchat-go

Ruby

# Gemfile
gem "kavchat"

Token erstellen

Node.js

import { Kavchat } from '@kavchat/node';

const kavchat = new Kavchat(process.env.KAVCHAT_SECRET_KEY!);

const token = kavchat.createUserToken({
  userId: 'user_123',          // required, 1 to 128 characters
  phone: '+972501234567',      // optional
  name: 'Dana',                // optional
  email: 'dana@example.com',   // optional
  expiresIn: 7 * 24 * 3600,    // seconds, default 7 days, at most 30 days
});
// Send the token to your page or app and pass it to the Kavchat widget or SDK.

Python

import os
from kavchat import Kavchat

kavchat = Kavchat(os.environ["KAVCHAT_SECRET_KEY"])

token = kavchat.create_user_token(
    "user_123",                 # required, 1 to 128 characters
    phone="+972501234567",
    name="Dana",
    email="dana@example.com",
    expires_in=7 * 24 * 3600,   # seconds, default 7 days, at most 30 days
)

PHP

use Kavchat\Kavchat;

$kavchat = new Kavchat(getenv('KAVCHAT_SECRET_KEY'));

$token = $kavchat->createUserToken(
    'user_123',              // required, 1 to 128 characters
    phone: '+972501234567',
    name: 'Dana',
    email: 'dana@example.com',
    expiresIn: 7 * 24 * 3600 // seconds, default 7 days, at most 30 days
);

Java

KavchatClient kavchat = KavchatClient.builder(System.getenv("KAVCHAT_SECRET_KEY")).build();

String token = kavchat.createUserToken(UserTokenOptions.builder("user_123")
        .phone("+972501234567")
        .name("Dana")
        .email("dana@example.com")
        .expiresIn(Duration.ofDays(7))   // default 7 days, at most 30 days
        .build());

.NET

using Kavchat;

using var kavchat = new KavchatClient(Environment.GetEnvironmentVariable("KAVCHAT_SECRET_KEY")!);

var token = kavchat.CreateUserToken(new UserTokenOptions
{
    UserId = "user_123",                 // required, 1 to 128 characters
    Phone = "+972501234567",
    Name = "Dana",
    Email = "dana@example.com",
    ExpiresIn = TimeSpan.FromDays(7),    // default 7 days, at most 30 days
});

import kavchat "kavchat.com/kavchat-go"

client := kavchat.New(os.Getenv("KAVCHAT_SECRET_KEY"))

token, err := client.CreateUserToken(kavchat.UserToken{
	UserID:    "user_123", // required, 1 to 128 characters
	Phone:     "+972501234567",
	Name:      "Dana",
	Email:     "dana@example.com",
	ExpiresIn: 7 * 24 * time.Hour, // zero means 7 days; at most 30 days
})

Ruby

require "kavchat"

kavchat = Kavchat::Client.new(ENV.fetch("KAVCHAT_SECRET_KEY"))

token = kavchat.create_user_token(
  user_id: "user_123",        # required, 1 to 128 characters
  phone: "+972501234567",
  name: "Dana",
  email: "dana@example.com",
  expires_in: 7 * 24 * 3600   # seconds, default 7 days, at most 30 days
)

Jedes SDK enthält auch eine eigenständige Variante, die den geheimen Schlüssel als erstes Argument entgegennimmt, zum Beispiel createUserToken(secretKey, options) in Node.js. Eine leere oder zu lange Benutzer-ID oder eine Gültigkeitsdauer außerhalb des Bereichs von einer Sekunde bis 30 Tagen führt zu einem Argumentfehler.

Ohne SDK

Jede JWT-Bibliothek ist geeignet. Dies sind dieselben Beispiele, die das Dashboard auf der Seite Installation anzeigt:

Node.js

import jwt from 'jsonwebtoken';

// On your server only. Never send the secret key to the browser.
const token = jwt.sign(
  { sub: user.id, phone: user.phone, name: user.firstName, email: user.email },
  process.env.KAVCHAT_SECRET_KEY, // sk_live_...
  { algorithm: 'HS256', expiresIn: '7d' },
);

Python

import jwt, time, os

token = jwt.encode(
    {"sub": user.id, "phone": user.phone, "name": user.first_name,
     "exp": int(time.time()) + 7 * 24 * 3600},
    os.environ["KAVCHAT_SECRET_KEY"],  # sk_live_...
    algorithm="HS256",
)

PHP

use Firebase\JWT\JWT;

$token = JWT::encode([
    'sub'   => $user->id,
    'phone' => $user->phone,
    'name'  => $user->first_name,
    'exp'   => time() + 7 * 24 * 3600,
], getenv('KAVCHAT_SECRET_KEY'), 'HS256'); // sk_live_...

Token an den Chat übergeben

Senden Sie das Token an Ihre Seite oder App, zum Beispiel zusammen mit der Antwort auf die Anmeldeanfrage, und übergeben Sie es an das Widget oder SDK. Bei einem Benutzerwechsel wird der Bot neu geladen und ein neues Gespräch gestartet.

Website

// at page load, with a token your server created for the signed-in user
Kavchat.init({ publicKey: 'pk_live_...', userToken: token, userName: 'Dana' });
// later, after login or logout
Kavchat.setUser({ token, name: 'Dana' });
Kavchat.setUser(null);

React Native

<KavchatProvider publicKey="pk_live_..." userToken={session?.kavchatToken} userName={session?.firstName}>

Flutter

await kavchat.setUser(token: jwt, name: 'Dana'); // after login
await kavchat.setUser(token: null);              // after logout

iOS

Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // after logout

Android

Kavchat.setUser(token = identityToken, name = "Dana")   // after login
Kavchat.setUser(token = null)                           // after logout

Weitere Details finden Sie in der jeweiligen Anleitung: Website, React Native, Flutter, iOS, Android.

Wenn das Token abgelehnt wird

Ein Token, das abgelaufen ist, mit einem anderen Schlüssel signiert wurde oder kein sub enthält, wird mit HTTP 401 und dem Fehlercode identity_invalid abgelehnt. Prüfen Sie die Uhrzeit auf Ihrem Server und den Schlüssel. Stellen Sie außerdem sicher, dass exp nicht mehr als 30 Tage in der Zukunft liegt.