Идентификация пользователей

По умолчанию каждый посетитель считается гостем. Когда пользователь входит в аккаунт на вашем сайте или в приложении, сервер может подписать для него короткий токен идентификации, чтобы Kavchat знал, кто это.

Зачем идентифицировать пользователей

Ваш идентификатор пользователя в каждом обращении. Диалоги и обращения помечаются идентификатором пользователя из вашей системы (userId в обращении), чтобы команда знала, к какому аккаунту они относятся.
Без ввода контактных данных. Гость должен оставить email или телефон в форме обращения. Идентифицированному пользователю это не обязательно.
Тестовые пользователи. Если выбрана аудитория «Тестовые пользователи», бот отображается только пользователям, чей номер телефона есть в списке тестовых пользователей. Kavchat распознаёт их по телефону в токене.
Личное приветствие. {name} в шаге сценария заменяется именем пользователя.

Токен

Токен идентификации — это обычный JWT, который создаётся на вашем сервере:

Алгоритм HS256. Для подписи используется ваш секретный ключ: вся строка sk_live_... в виде байтов UTF-8.
Страница или приложение передаёт его в заголовке Authorization: Bearer <token> при каждом запросе к Kavchat.
Никогда не подписывайте токены в браузере или приложении. Секретный ключ должен оставаться на вашем сервере.

Поле	Обязательное	Описание
`sub`	Да	Идентификатор пользователя в вашей системе, от 1 до 128 символов.
`exp`	Да	Время истечения срока действия, не более чем через 30 дней. В SDK по умолчанию используется срок 7 дней.
`phone`	Нет	В формате E.164 (`+972501234567`) или местный номер. Используется для идентификации тестовых пользователей.
`name`	Нет	Отображается в приветствии и автоматически подставляется в форму обращения.
`email`	Нет	Автоматически подставляется в форму обращения.

Создавайте новый токен при входе пользователя в аккаунт и затем до истечения срока действия предыдущего. Короткий срок действия, несколько дней, хорошо подходит в качестве значения по умолчанию.

Установка серверного SDK

Серверные SDK создают токены, проверяют webhook и вызывают Server API. У них нет зависимостей, кроме стандартной библиотеки соответствующего языка (в Java есть зависимость от 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"

Создание токена

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
)

В каждом SDK есть и отдельная версия функции, которая принимает секретный ключ первым аргументом, например createUserToken(secretKey, options) в Node.js. Пустой или слишком длинный идентификатор пользователя, а также срок действия вне диапазона от 1 секунды до 30 дней вызывают ошибку аргумента.

Без SDK

Подойдёт любая библиотека JWT. Эти же примеры доступны в панели управления на странице Установка:

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

Передача токена в чат

Отправьте токен на страницу или в приложение, например вместе с ответом на запрос входа в аккаунт, и передайте его виджету или SDK. При смене пользователя бот перезагружается и начинается новый диалог.

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

Подробнее в руководствах: сайт, React Native, Flutter, iOS, Android.

Если токен отклонён

Токен с истёкшим сроком действия, подписанный другим ключом или без поля sub, отклоняется с HTTP 401 и кодом ошибки identity_invalid. Проверьте время на сервере, ключ и убедитесь, что exp указывает на момент не более чем через 30 дней.