Verifikasi identitas

Mengapa memverifikasi#

Secara default SDK bersifat anonim: ia menghasilkan visitor_id yang stabil dan menyimpannya di keystore platform. Itu cukup untuk satu percakapan di satu perangkat. Untuk mengenali pengguna tertentu, memulihkan riwayat saat masuk kembali atau di perangkat lain, dan mengikat percakapan ke profil kontak secara andal, backend membutuhkan bukti bahwa klien memang seperti yang diklaimnya. Jika SDK hanya mengirim "I am user 42", siapa pun dapat memalsukan id lain dan membaca chat orang lain — jadi Respondo mensyaratkan tanda tangan kriptografis, userHash, yang hanya dapat diproduksi backend Anda.

Mendapatkan identity secret#

identity_secret adalah string rahasia yang terikat pada agen Anda (pekerja AI yang terhubung dengan channel widget Anda). Hasilkan di dashboard pada Channels → Widget → Identity verification. Karena ia berada pada agen, setiap channel yang didukung agen tersebut — baik widget web maupun SDK mobile — memakai secret yang sama. Ia memberi hak untuk menandatangani identitas, jadi ia harus hanya berada di backend Anda dan tidak pernah dikirim di dalam aplikasi.

Formula userHash#

userHash adalah HMAC-SHA256 atas satu string identitas yang ditandatangani, dikodekan sebagai hex huruf kecil:

userHash = HMAC_SHA256( identity_secret, payload )

payload = userId          // jika userId disetel
        = email           // jika tidak, bila email disetel
        = (invalid)       // jika keduanya kosong, tidak ada yang bisa ditandatangani

• Secret adalah kunci HMAC; string identitas adalah pesan — bukan sebaliknya.
• Tandatangani tepat satu string — userId mentah (atau email), tanpa salt atau pembungkus JSON.
• Jika Anda meneruskan userId dan email sekaligus, tandatangani userId (ia diutamakan).
• Keluarannya hex (64 karakter untuk SHA-256), bukan base64.

Contoh backend#

Hitung tanda tangan di backend Anda dan serahkan userHash yang sudah jadi ke aplikasi.

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

// HMAC_SHA256(identity_secret, userId) sebagai hex huruf kecil.
func ComputeUserHash(identitySecret, userID string) string {
    mac := hmac.New(sha256.New, []byte(identitySecret))
    mac.Write([]byte(userID))
    return hex.EncodeToString(mac.Sum(nil))
}

const crypto = require("crypto");

// Mengembalikan userHash untuk diteruskan ke Respondo.identify pada klien mobile.
function computeUserHash(identitySecret, userId) {
  return crypto
    .createHmac("sha256", identitySecret)
    .update(userId, "utf8")
    .digest("hex");
}

import hmac
import hashlib

# Mengembalikan userHash untuk diteruskan ke Respondo.identify pada klien mobile.
def compute_user_hash(identity_secret: str, user_id: str) -> str:
    return hmac.new(
        identity_secret.encode(),
        user_id.encode(),
        hashlib.sha256,
    ).hexdigest()

<?php
// Mengembalikan userHash untuk diteruskan ke Respondo.identify pada klien mobile.
function computeUserHash(string $identitySecret, string $userId): string {
    return hash_hmac('sha256', $userId, $identitySecret);
}

Bagaimana hash sampai ke Respondo#

Dua lompatan, dan hanya yang pertama yang harus Anda bangun:

1. Backend Anda → aplikasi Anda. Anda mengirimkan hash dengan cara apa pun. Opsi termurah adalah menambahkan satu field pada respons login/bootstrap yang sudah Anda kembalikan — tanpa round trip tambahan. Endpoint khusus di backend Anda sendiri (misalnya POST /myapp/identity yang mengembalikan { userId, userHash }) sama baiknya. Respondo tidak meng-host endpoint itu — Anda yang mengimplementasikannya.
2. Aplikasi Anda → Respondo. Sudah ditangani untuk Anda. Setelah Anda memanggil identify, SDK melampirkan hash ke setiap request yang relevan dan backend memverifikasinya ulang setiap kali.

POST /api/v1/chat                      body   identity.userHash
GET  /api/v1/chat/resume               query  user_hash
GET  /api/v1/chat/history              query  user_hash
GET  /api/v1/chat/ws                   frames    user_hash (frame JSON subscribe/identify setelah tersambung — bukan di URL handshake)
GET  /api/v1/widget/tours              query  user_hash
GET  /api/v1/widget/checklists         query  user_hash
POST /api/v1/widget/push/register      body   user_hash

Hash diperiksa ulang pada setiap request, bukan ditukar sekali untuk satu sesi — itulah yang membuat userId yang dicuri tidak berguna dengan sendirinya.

Meneruskan identitas ke SDK#

Ambil identitas yang telah ditandatangani dari backend Anda, lalu teruskan userHash ke identify pada platform mana pun:

Respondo.identify(
    RespondoIdentity(userId = "42", email = "user@example.com", userHash = hash),
)

Respondo.identify(
    RespondoIdentity(userId: "42", email: "user@example.com", userHash: hash)
)

Respondo.identify(RespondoIdentity(
  userId: '42', email: 'user@example.com', userHash: hash,
));

Perilaku userHash tidak valid#

Ketika verifikasi diaktifkan pada agen dan tanda tangan hilang atau salah, backend melakukan penurunan diam-diam ke anonim: chat tetap berfungsi, visitor_id dipertahankan, dan percakapan terikat ke kontak anonim — tetapi tidak ada tautan ke profil dan tidak ada riwayat lintas perangkat. Jika seorang pengguna "tidak dikenali", hampir selalu penyebabnya adalah tanda tangan: pastikan Anda menandatangani userId (bukan email atau JSON), menggunakan identity_secret yang benar, dan menghasilkan hex huruf kecil. Jika identity_secret milik agen kosong, verifikasi mati dan userId / email diterima apa adanya.

Merotasi identity_secret pada dasarnya adalah peralihan tegas: setiap hash yang diproduksi dengan secret lama langsung berhenti terverifikasi, sehingga pengguna yang sudah masuk diam-diam turun ke anonim sampai backend Anda menghitung ulang dan memberikan kembali userHash mereka dengan secret baru. Rotasikan secret hanya bila Anda dapat memperbarui sisi penandatanganan dalam jendela yang sama.