Identify users

By default every visitor is a guest. When a user is signed in to your site or app, your server can sign a short identity token so Kavchat knows who they are.

Why identify users

Your user id on every request. Conversations and requests are tagged with your own user id (userId on the request), so your team can match them to the account.
No contact details to type. Guests must leave an email or a phone in the contact form. Identified users may leave neither.
Testers. When the audience is "testers", the bot is shown only to users whose phone number is on your testers list. The phone in the token is how Kavchat recognizes them.
A personal greeting. {name} in a step is replaced with the user's first name.

The token

The identity token is a standard JWT, created on your server:

Algorithm HS256. The key is your secret key: the full sk_live_... string, as UTF-8 bytes.
The page or app sends it as Authorization: Bearer <token> on every call to Kavchat.
Never sign tokens in the browser or in the app. The secret key stays on your backend.

Claim	Required	Description
`sub`	yes	Your user id, 1 to 128 characters.
`exp`	yes	Expiry time, at most 30 days ahead. The SDKs default to 7 days.
`phone`	no	E.164 (`+972501234567`) or a local number. Used to recognize testers.
`name`	no	Shown in the greeting and prefilled in the contact form.
`email`	no	Prefilled in the contact form.

Create a new token when the user signs in, and before the old one expires. A short lifetime (a few days) is a good default.

Install a server SDK

The server SDKs create the token for you, verify webhooks and call the Server API. They have no dependencies beyond each language's standard library (Java uses 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"

Create a token

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
)

Each SDK also has a standalone version that takes the secret key as its first argument, for example createUserToken(secretKey, options) in Node.js. An empty or too long user id, or a lifetime outside 1 second to 30 days, throws an argument error.

Without an SDK

Any JWT library works. These are the same examples the dashboard shows on the Install page:

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

Pass the token to the chat

Send the token to your page or app, for example with the response of your login call, and hand it to the widget or SDK. Changing the user reloads the bot and starts a new 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

More details in each guide: website, React Native, Flutter, iOS, Android.

When the token is rejected

A token that is expired, signed with another key, or missing sub is rejected with HTTP 401 and the error code identity_invalid. Check the clock on your server, the key, and that exp is no more than 30 days ahead.