Identificação de usuários

Por padrão, todo visitante é um convidado. Quando um usuário está conectado ao seu site ou aplicativo, o servidor pode assinar um token de identidade curto para que o Kavchat saiba quem ele é.

Por que identificar usuários

O ID do seu usuário em cada chamado. As conversas e os chamados recebem o ID do usuário no seu sistema (userId no chamado), para que a equipe saiba a qual conta pertencem.
Sem precisar digitar dados de contato. Convidados precisam informar um e-mail ou telefone no formulário de contato. Usuários identificados não precisam.
Usuários de teste. Quando o público-alvo é "Usuários de teste", o bot aparece apenas para usuários cujo telefone está na lista de usuários de teste. O Kavchat os identifica pelo telefone no token.
Saudação personalizada. {name} em uma etapa do roteiro é substituído pelo primeiro nome do usuário.

O token

O token de identidade é um JWT padrão criado no seu servidor:

Algoritmo HS256. A chave é sua chave secreta: a string completa sk_live_..., em bytes UTF-8.
A página ou o aplicativo envia o token no cabeçalho Authorization: Bearer <token> em cada chamada ao Kavchat.
Nunca assine tokens no navegador ou no aplicativo. A chave secreta fica no seu servidor.

Campo	Obrigatório	Descrição
`sub`	Sim	ID do usuário no seu sistema, de 1 a 128 caracteres.
`exp`	Sim	Data e hora de expiração, no máximo 30 dias à frente. Nos SDKs, o padrão é 7 dias.
`phone`	Não	No formato E.164 (`+972501234567`) ou um número local. Usado para identificar usuários de teste.
`name`	Não	Exibido na saudação e preenchido automaticamente no formulário de contato.
`email`	Não	Preenchido automaticamente no formulário de contato.

Crie um novo token quando o usuário fizer login e novamente antes que o anterior expire. Uma validade curta, de alguns dias, é um bom padrão.

Instalação de um SDK para servidor

Os SDKs para servidor criam o token para você, validam webhooks e fazem chamadas à Server API. Não têm dependências além da biblioteca padrão de cada linguagem (em Java, há uma dependência do 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"

Criação de um 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
)

Cada SDK também tem uma versão independente que recebe a chave secreta como primeiro argumento, por exemplo, createUserToken(secretKey, options) em Node.js. Um ID de usuário vazio ou longo demais, ou uma validade fora do intervalo de um segundo a 30 dias, gera um erro de argumento.

Sem SDK

Qualquer biblioteca JWT serve. Estes são os mesmos exemplos exibidos no painel, na página Instalação:

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

Envio do token ao chat

Envie o token à página ou ao aplicativo, por exemplo, junto com a resposta à chamada de login, e passe-o ao widget ou ao SDK. Trocar de usuário recarrega o bot e inicia uma nova conversa.

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

Mais detalhes em cada guia: Site, React Native, Flutter, iOS, Android.

Quando o token é rejeitado

Um token expirado, assinado com outra chave ou sem sub é rejeitado com HTTP 401 e o código de erro identity_invalid. Verifique o relógio do servidor, a chave e se exp não está mais de 30 dias à frente.