Bắt đầu nhanh: gắn chat lên website

Hướng dẫn này đặt nút chat lên website của bạn, cho hộp thư biết người dùng đã đăng nhập là ai, và để bạn trả lời tin nhắn đầu tiên từ dashboard, từ ứng dụng Hạ Tầng trên điện thoại hoặc từ server của bạn. Cuối cùng, bạn thêm cùng khung chat đó vào ứng dụng iOS, Android, Flutter hoặc React Native.

Trước khi bắt đầu

Một tài khoản Hạ Tầng tại app.hatang.dev đã bật module Hỗ trợ (Doanh nghiệp và module).
Một website bạn sửa được, có quyền vào HTML chung của trang hoặc vào tag manager.
Để đổi cài đặt Hỗ trợ, bạn cần là chủ sở hữu, quản trị viên, hoặc thành viên có quyền Quản lý ở Hỗ trợ (Nhân viên và phân quyền).

1. Sao chép đoạn mã

Trong dashboard, mở Hỗ trợ → Kênh và chọn website của bạn. Muốn thêm website khác, bấm Thêm kênh rồi chọn ở nhóm Website.
Ở khung Cài đặt, bấm Sao chép mã.

Đoạn mã gồm hai dòng. Dòng đầu đặt site id (bắt đầu bằng site_), dòng sau tải widget từ chat gateway:

<script>window.$hatang=window.$hatang||[];window.HATANG_SITE_ID="site_123...";</script>
<script src="https://chat.hatang.dev/widget.js" async></script>

2. Gắn vào website

Dán đoạn mã ngay trước </body> ở mọi trang, hoặc ở layout dùng chung cho mọi trang. Script tải bất đồng bộ nên không làm chậm trang.

Tải lại website: nút chat hiện ở góc màn hình. Trong dashboard, khung Cài đặt chuyển sang Đã cài và hiện tên miền nơi widget được thấy.

Dùng WordPress, Shopify, Haravan, LadiPage, Sapo, Google Tag Manager, Webflow hay React? Hướng dẫn cài widget có các bước cho từng nền tảng, còn plugin WordPress không cần viết mã.

Widget chạy ở đâu

Widget chỉ khởi động trên tên miền của website và các tên miền phụ. Để thử trên http://localhost:3000 hoặc bản xem trước, thêm origin đó vào Origin được phép thêm trên trang website. Origin khác bị từ chối với origin_not_allowed.

3. Nhận diện người dùng đã đăng nhập

Nếu không viết thêm mã, mọi khách truy cập đều là khách ẩn danh. Khi người dùng đã đăng nhập trên website, hãy truyền thông tin của họ cho widget để nhân viên biết mình đang nói chuyện với ai:

<script>
  window.$hatang = window.$hatang || [];
  $hatang.push(["identify", {
    user_id: "42",
    email: "[email protected]",
    name: "Nguyễn Văn An",
    phone: "0901234567",
    hash: "<%= hatangHash %>"
  }]);
</script>

$hatang.push dùng được cả trước và sau khi widget tải xong, nên bạn đặt đoạn này ở đâu cũng được, miễn là sau dòng đầu của đoạn mã cài đặt.

hash chứng minh user id đến từ server của bạn chứ không phải do ai đó gõ trong console của trình duyệt. Không có hash, thông tin được hiển thị là Chưa xác minh và không bao giờ được gộp vào lịch sử của khách khác. Có hash hợp lệ, hộp thư coi user id là Đã xác minh và gộp mọi phiên của người đó, trên mọi thiết bị, vào một khách hàng.

Tính hash ở server bằng HMAC-SHA256 của user id, khoá là Mã bí mật định danh của site (trên trang website, bấm Tạo mới & hiển thị), dạng hex chữ thường:

Node.js
Python
PHP

import { createHmac } from "node:crypto";

export const hatangHash = (userId) =>
  createHmac("sha256", process.env.HATANG_IDENTITY_SECRET).update(String(userId)).digest("hex");

import os
from hatang import identity_hash  # pip install hatang

def hatang_hash(user_id) -> str:
    return identity_hash(str(user_id), os.environ["HATANG_IDENTITY_SECRET"])

$hash = hash_hmac('sha256', (string) $userId, getenv('HATANG_IDENTITY_SECRET'));

Giữ mã bí mật định danh ở server

Ai có mã bí mật định danh đều có thể vào chat dưới danh nghĩa bất kỳ người dùng nào của bạn. Không đặt nó vào JavaScript của trang, ứng dụng di động hay plugin công khai; chỉ gửi hash đã tính xuống trình duyệt.

Hướng dẫn nhận diện khách giải thích cách gộp phiên, xoay mã bí mật và cú pháp cho từng SDK. JavaScript API liệt kê các lệnh khác như open, setLocale và on.

4. Trả lời từ hộp thư

Mở website trong cửa sổ ẩn danh và gửi một tin nhắn từ widget. Tin nhắn hiện ngay trong Hỗ trợ → Hộp thư. Gõ câu trả lời, khách thấy ngay trong widget.

Nhân viên cũng trả lời được từ ứng dụng Hạ Tầng trên iPhone, Android và Mac, có thông báo đẩy khi có tin nhắn mới.

Muốn trả lời từ hệ thống của bạn, dùng REST API với key có scope chat:write. Lấy danh sách hội thoại đang mở, rồi gửi tin nhắn dưới tên đội ngũ:

cURL
Node.js
Python
PHP

curl "https://api.hatang.dev/chat/conversations?status=open&limit=20" \
  -H "Authorization: Bearer $HATANG_API_KEY"

curl -X POST https://api.hatang.dev/chat/conversations/cnv_123.../messages \
  -H "Authorization: Bearer $HATANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-cnv_123-1" \
  -d '{ "content": "Chào anh An, đơn của anh được giao trong hôm nay ạ." }'

import { Hatang } from "@hatang/sdk";

const hatang = new Hatang(process.env.HATANG_API_KEY, { baseUrl: "https://api.hatang.dev" });

const { data: open } = await hatang.chat.conversations.list({ status: "open", limit: 20 });
const conversation = open.data[0];

const { data, error } = await hatang.chat.conversations.send(
  conversation.id,
  { content: "Chào anh An, đơn của anh được giao trong hôm nay ạ." },
  { idempotencyKey: `reply-${conversation.id}-1` },
);

from hatang import Hatang

hatang = Hatang()  # đọc HATANG_API_KEY

open_ = hatang.chat.conversations.list(status="open", limit=20)
conversation_id = open_["data"][0]["id"]

message = hatang.chat.conversations.send(
    conversation_id,
    {"content": "Chào anh An, đơn của anh được giao trong hôm nay ạ."},
    idempotency_key=f"reply-{conversation_id}-1",
)
print(message)

<?php
$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.hatang.dev',
    'headers' => ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')],
]);

$open = json_decode((string) $client->get('/chat/conversations', ['query' => ['status' => 'open', 'limit' => 20]])->getBody(), true);
$conversationId = $open['data'][0]['id'];

$res = $client->post("/chat/conversations/{$conversationId}/messages", [
    'headers' => ['Idempotency-Key' => "reply-{$conversationId}-1"],
    'json' => ['content' => 'Chào anh An, đơn của anh được giao trong hôm nay ạ.'],
]);

Lệnh gửi tin nhắn trả 201:

{ "object": "chat_message", "id": "msg_123...", "seq": 7, "conversation_id": "cnv_123...", "duplicate": false }

Để phản hồi tin nhắn mới của khách mà không phải hỏi liên tục, đăng ký webhook cho sự kiện chat.message.created. Hướng dẫn REST API Hỗ trợ có thêm cách giao hội thoại, gắn tag, ghi chú nội bộ, khách hàng và đơn hàng.

5. Thêm chat vào ứng dụng di động

SDK gốc nói chuyện với cùng gateway như widget, nên tin nhắn từ ứng dụng về cùng hộp thư, và người dùng đã xác minh giữ một lịch sử chung giữa web và di động.

Ở Hỗ trợ → Kênh, bấm Thêm kênh, chọn Ứng dụng di động, rồi Tạo khoá ứng dụng. Khoá bắt đầu bằng hak_ và chỉ hiện một lần.
Cài SDK cho nền tảng của bạn và cấu hình bằng site id và khoá ứng dụng.
Gọi identify với cùng user id và hash như trên web.
Nếu cần, tải thông tin Firebase lên để ứng dụng nhận thông báo đẩy.

Nền tảng	Hướng dẫn
Flutter	SDK Flutter
iOS (Swift)	SDK iOS
Android (Kotlin)	SDK Android
React Native / Expo	SDK React Native
React / Next.js (web)	Component React

Khoá ứng dụng không bí mật như API key (nó nằm trong bản build), nhưng bạn thu hồi và cấp khoá mới được bất cứ lúc nào. Đừng bao giờ đưa API key ht_ hay mã bí mật định danh vào ứng dụng.

Lỗi thường gặp

Hiện tượng	Nguyên nhân	Cách xử lý
Không thấy nút chat, console báo `origin_not_allowed`	Trang không nằm trên tên miền của website	Thêm origin vào Origin được phép thêm
Không thấy nút chat, báo `product_disabled`	Module Hỗ trợ đang tắt	Nhờ chủ sở hữu hoặc quản trị viên bật lại
Không thấy nút chat ở một số trang	Quy tắc hiển thị trên trang website đang ẩn widget ở đó	Kiểm tra cài đặt nơi hiện widget
Người dùng hiện Chưa xác minh	Thiếu `hash` hoặc `hash` không khớp	Tính từ đúng chuỗi user id, với mã bí mật định danh hiện tại
Ứng dụng báo `invalid_app_key`	Khoá sai, hoặc khoá của site khác	Sao chép lại khoá ứng dụng của đúng website

Bước tiếp theo

Tổng quan Hỗ trợ: kênh, phân chia hội thoại, phiếu hỗ trợ và trợ lý AI
JavaScript API của widget
Nhận diện khách
Tổng quan SDK

Xem trang này dạng Markdown

Trước khi bắt đầu​

1. Sao chép đoạn mã​

2. Gắn vào website​

3. Nhận diện người dùng đã đăng nhập​

4. Trả lời từ hộp thư​

5. Thêm chat vào ứng dụng di động​

Lỗi thường gặp​

Bước tiếp theo​