Identification des utilisateurs

Par défaut, chaque visiteur est un invité. Lorsqu’un utilisateur est connecté à votre site ou à votre application, votre serveur peut signer un jeton d’identité court pour permettre à Kavchat de savoir qui il est.

Pourquoi identifier les utilisateurs

Votre identifiant utilisateur dans chaque ticket. Les conversations et les tickets portent l’identifiant utilisateur de votre système (userId dans le ticket), pour que votre équipe sache à quel compte ils appartiennent.
Aucune coordonnée à saisir. Un invité doit laisser une adresse e-mail ou un numéro de téléphone dans le formulaire de contact. Un utilisateur identifié n’y est pas obligé.
Utilisateurs de test. Lorsque le public cible est « Utilisateurs de test », le bot s’affiche uniquement pour les utilisateurs dont le numéro de téléphone figure dans votre liste de test. Kavchat les reconnaît grâce au numéro de téléphone contenu dans le jeton.
Un accueil personnalisé. Dans une étape du script, {name} est remplacé par le prénom de l’utilisateur.

Le jeton

Le jeton d’identité est un JWT standard, créé sur votre serveur :

Algorithme HS256. La clé utilisée est votre clé secrète : la chaîne sk_live_... complète, sous forme d’octets UTF-8.
La page ou l’application l’envoie dans l’en-tête Authorization: Bearer <token> à chaque appel à Kavchat.
Ne signez jamais de jetons dans le navigateur ou dans l’application. La clé secrète reste sur votre serveur.

Champ	Obligatoire	Description
`sub`	Oui	L’identifiant de l’utilisateur dans votre système, de 1 à 128 caractères.
`exp`	Oui	Date d’expiration, au maximum dans 30 jours. Les SDK utilisent par défaut une durée de 7 jours.
`phone`	Non	Au format E.164 (`+972501234567`) ou au format local. Sert à reconnaître les utilisateurs de test.
`name`	Non	Affiché dans le message d’accueil et prérempli dans le formulaire de contact.
`email`	Non	Prérempli dans le formulaire de contact.

Créez un nouveau jeton lorsque l’utilisateur se connecte, puis avant l’expiration du précédent. Une durée de validité courte, de quelques jours, est un bon choix par défaut.

Installer un SDK serveur

Les SDK serveur créent le jeton pour vous, vérifient les webhooks et appellent l’API serveur. Ils n’ont aucune dépendance en dehors de la bibliothèque standard de chaque langage (Java dépend de 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"

Créer un jeton

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
)

Chaque SDK propose aussi une version autonome qui reçoit la clé secrète comme premier argument, par exemple createUserToken(secretKey, options) en Node.js. Un identifiant utilisateur vide ou trop long, ou une durée de validité qui n’est pas comprise entre une seconde et 30 jours, provoque une erreur d’argument.

Sans SDK

Toute bibliothèque JWT convient. Ce sont les mêmes exemples que ceux affichés dans le tableau de bord, sur la page Installation :

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_...

Transmettre le jeton au chat

Envoyez le jeton à votre page ou à votre application, par exemple avec la réponse à la requête de connexion, puis transmettez-le au widget ou au SDK. Un changement d’utilisateur recharge le bot et démarre une nouvelle conversation.

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

Plus de détails dans chaque guide : site web, React Native, Flutter, iOS, Android.

Lorsque le jeton est refusé

Un jeton expiré, signé avec une autre clé ou sans champ sub est refusé avec un statut HTTP 401 et le code d’erreur identity_invalid. Vérifiez l’horloge de votre serveur, la clé utilisée et que exp ne se situe pas à plus de 30 jours dans le futur.