Identificar usuarios

De forma predeterminada, todos los visitantes son invitados. Cuando un usuario inicia sesión en tu sitio o aplicación, tu servidor puede firmar un token de identidad breve para que Kavchat sepa quién es.

Por qué identificar a los usuarios

Tu identificador de usuario en cada ticket. Las conversaciones y los tickets llevan el identificador de usuario de tu sistema (userId en el ticket), para que tu equipo sepa a qué cuenta pertenecen.
Sin tener que escribir datos de contacto. Los invitados deben dejar un correo electrónico o un teléfono en el formulario de contacto. Los usuarios identificados no tienen que hacerlo.
Usuarios de prueba. Cuando el público seleccionado es "usuarios de prueba", el bot solo se muestra a los usuarios cuyo teléfono está en la lista de usuarios de prueba. Kavchat los reconoce por el teléfono incluido en el token.
Un saludo personalizado. {name} en un paso del guion se sustituye por el nombre de pila del usuario.

El token

El token de identidad es un JWT estándar que se crea en tu servidor:

Algoritmo HS256. La clave es tu clave secreta: la cadena completa sk_live_..., como bytes UTF-8.
La página o la aplicación lo envían en el encabezado Authorization: Bearer <token> en cada llamada a Kavchat.
Nunca firmes tokens en el navegador ni en la aplicación. La clave secreta se queda en tu servidor.

Campo	Obligatorio	Descripción
`sub`	Sí	El identificador del usuario en tu sistema, de 1 a 128 caracteres.
`exp`	Sí	Fecha de caducidad, como máximo dentro de 30 días. En los SDK, el valor predeterminado es de 7 días.
`phone`	No	En formato E.164 (`+972501234567`) o un número local. Se usa para identificar a los usuarios de prueba.
`name`	No	Se muestra en el saludo y se rellena automáticamente en el formulario de contacto.
`email`	No	Se rellena automáticamente en el formulario de contacto.

Crea un token nuevo cuando el usuario inicie sesión y de nuevo antes de que caduque el anterior. Una duración corta, de unos pocos días, es una buena opción predeterminada.

Instalar un SDK para el servidor

Los SDK para el servidor crean el token por ti, verifican webhooks y hacen llamadas a la API del servidor. No tienen dependencias más allá de la biblioteca estándar de cada lenguaje (en Java hay una dependencia 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"

Crear un 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 también incluye una versión independiente que recibe la clave secreta como primer argumento, por ejemplo createUserToken(secretKey, options) en Node.js. Un identificador de usuario vacío o demasiado largo, o una duración que no esté entre un segundo y 30 días, provocan un error de argumento.

Sin SDK

Cualquier biblioteca JWT sirve. Estos son los mismos ejemplos que aparecen en la página Instalación del panel de administración:

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

Pasar el token al chat

Envía el token a la página o a la aplicación, por ejemplo junto con la respuesta a la llamada de inicio de sesión, y pásalo al widget o al SDK. Al cambiar de usuario, el bot se vuelve a cargar y se inicia una conversación nueva.

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

Más detalles en cada guía: sitio web, React Native, Flutter, iOS, Android.

Cuando se rechaza el token

Un token caducado, firmado con otra clave o sin sub se rechaza con HTTP 401 y el código de error identity_invalid. Revisa el reloj del servidor, la clave y que exp no esté a más de 30 días en el futuro.