תפריט המדריכים

זיהוי משתמשים

כברירת מחדל כל מבקר הוא אורח. כשמשתמש מחובר לאתר או לאפליקציה שלכם, השרת יכול לחתום עבורו טוקן זהות קצר, וכך Kavchat יודע מי הוא.

למה לזהות משתמשים

  • מזהה המשתמש שלכם בכל פנייה. השיחות והפניות מסומנות במזהה המשתמש שלכם (userId בפנייה), כך שהצוות יודע לאיזה חשבון הן שייכות.
  • בלי להקליד פרטי קשר. אורח חייב להשאיר מייל או טלפון בטופס הפנייה. משתמש מזוהה לא חייב.
  • בודקים. כשקהל היעד הוא "בודקים", הבוט מוצג רק למשתמשים שמספר הטלפון שלהם ברשימת הבודקים. Kavchat מזהה אותם לפי הטלפון שבטוקן.
  • ברכה אישית. {name} בשלב של התסריט מוחלף בשם הפרטי של המשתמש.

הטוקן

טוקן הזהות הוא JWT רגיל שנוצר בשרת שלכם:

  • אלגוריתם HS256. המפתח הוא המפתח הסודי שלכם: כל המחרוזת sk_live_..., כבייטים של UTF-8.
  • העמוד או האפליקציה שולחים אותו בכותרת Authorization: Bearer <token> בכל קריאה ל-Kavchat.
  • אף פעם לא חותמים טוקנים בדפדפן או באפליקציה. המפתח הסודי נשאר בשרת שלכם.
שדהחובהתיאור
subכןמזהה המשתמש אצלכם, 1 עד 128 תווים.
expכןמועד התפוגה, עד 30 יום קדימה לכל היותר. בערכות הפיתוח ברירת המחדל היא 7 ימים.
phoneלאבפורמט E.164 (+972501234567) או מספר מקומי. משמש לזיהוי בודקים.
nameלאמוצג בברכה וממולא מראש בטופס הפנייה.
emailלאממולא מראש בטופס הפנייה.

יוצרים טוקן חדש כשהמשתמש מתחבר, ושוב לפני שהקודם פג. תוקף קצר, של כמה ימים, הוא ברירת מחדל טובה.

התקנת ערכת פיתוח לשרת

ערכות הפיתוח לשרת יוצרות בשבילכם את הטוקן, מאמתות 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
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
});
Go
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
)

בכל ערכה יש גם גרסה עצמאית שמקבלת את המפתח הסודי כארגומנט הראשון, למשל createUserToken(secretKey, options) ב-Node.js. מזהה משתמש ריק או ארוך מדי, או תוקף שאינו בין שנייה אחת ל-30 יום, גורמים לשגיאת ארגומנט.

בלי ערכת פיתוח

כל ספריית 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_...

העברת הטוקן לצ'אט

שולחים את הטוקן לעמוד או לאפליקציה, למשל יחד עם התשובה לקריאת ההתחברות, ומעבירים אותו לווידג'ט או לערכת הפיתוח. החלפת משתמש טוענת את הבוט מחדש ומתחילה שיחה חדשה.

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 יום קדימה.