เมนูคู่มือ

การระบุตัวตนผู้ใช้

โดยค่าเริ่มต้น ผู้เข้าชมทุกคนจะเป็นผู้เยี่ยมชม เมื่อผู้ใช้เข้าสู่ระบบเว็บไซต์หรือแอปของคุณแล้ว เซิร์ฟเวอร์สามารถลงลายเซ็นโทเค็นระบุตัวตนสั้น ๆ ให้ผู้ใช้ เพื่อให้ Kavchat รู้ว่าเป็นใคร

ทำไมต้องระบุตัวตนผู้ใช้

  • มีรหัสผู้ใช้ของคุณในทุกคำร้อง การสนทนาและคำร้องจะมีรหัสผู้ใช้จากระบบของคุณกำกับไว้ (userId ในคำร้อง) ทีมงานจึงทราบว่าเป็นของบัญชีใด
  • ไม่ต้องกรอกข้อมูลติดต่อ ผู้เยี่ยมชมต้องระบุอีเมลหรือเบอร์โทรศัพท์ในแบบฟอร์มติดต่อ แต่ผู้ใช้ที่ระบุตัวตนแล้วไม่จำเป็นต้องระบุ
  • ผู้ใช้ทดสอบ เมื่อกำหนดกลุ่มเป้าหมายเป็น "ผู้ใช้ทดสอบ" บอตจะแสดงเฉพาะกับผู้ใช้ที่มีเบอร์โทรศัพท์อยู่ในรายชื่อผู้ใช้ทดสอบเท่านั้น 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
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
)

แต่ละ SDK ยังมีเวอร์ชันที่ใช้งานแยกได้ โดยรับคีย์ลับเป็นอาร์กิวเมนต์แรก เช่น createUserToken(secretKey, options) ใน Node.js หากรหัสผู้ใช้ว่างหรือยาวเกินไป หรืออายุโทเค็นไม่อยู่ในช่วงหนึ่งวินาทีถึง 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 วันนับจากปัจจุบัน