Hướng Dẫn Tích Hợp WebSocket API Chatbot

Tổng Quan

Tài liệu này cung cấp hướng dẫn toàn diện để tích hợp với WebSocket API Chatbot. API cho phép giao tiếp hai chiều theo thời gian thực với chatbot AI thông qua kết nối WebSocket.

Thông Tin Cơ Bản

WebSocket Endpoint: wss://devbotwaka.ovp.vn/chat
Giao thức: Secure WebSocket (wss://)
Xác thực: Dựa trên token query parameter

Xác Thực

Tham Số Token

Kết nối WebSocket yêu cầu xác thực thông qua query parameter:

wss://devbotwaka.ovp.vn/chat?token=YOUR_JWT_TOKEN

Lưu ý: Nếu không có token hợp lệ, hệ thống sẽ sử dụng user test mặc định với thông tin:

User ID: 000000
Username: Tester01
Token Limit: 1,000,000

Quy Trình Kết Nối

1. Thiết Lập Kết Nối

const socket = new WebSocket('ws://your-domain/chat?token=YOUR_JWT_TOKEN');

2. Xử Lý Phản Hồi Đầu Tiên

Sau khi kết nối thành công, server sẽ gửi thông báo thông tin ban đầu:

{
  "role": "bot",
  "content": "{\"username\":\"YourUsername\",\"token_limit\":1000}",
  "type": "info",
  "session": "acfa4509-8248-41bb-a528-fefea489a956",
  "trace_id": null,
  "error_code": 0
}

Định Dạng Tin Nhắn

Định Dạng Yêu Cầu (Client → Server)

Gửi tin nhắn dưới dạng JSON string với cấu trúc sau:

{
  "content": "Tin nhắn của bạn",
  "uuid": "session-uuid - tùy chọn",
  "question_id": "question id - tùy chọn"
}

Các Trường

content (string, bắt buộc): Tin nhắn/câu hỏi của người dùng
uuid (string, tùy chọn): Session UUID để duy trì cuộc hội thoại. Nếu không có, server sẽ tự tạo.
question_id: (string, tùy chọn): Question ID để so khớp câu hỏi với kết quả trả lời từ server. Nếu không có, bỏ qua.

Định Dạng Phản Hồi (Server → Client)

Tất cả phản hồi từ server đều tuân theo cấu trúc này:

{
  "role": "user|bot",
  "content": "Nội dung phản hồi",
  "type": "start|stream|end|error|info|suggest",
  "session": "session-uuid",
  "trace_id": "trace-uuid",
  "question_id": "question-id",
  "error_code": 0
}

Mô Tả Các Trường

Trường	Loại	Mô tả	Giá trị có thể
`role`	string	Người gửi tin nhắn	`"user"`, `"bot"`
`content`	string	Nội dung tin nhắn	Bất kỳ chuỗi nào
`type`	string	Loại tin nhắn	`"start"`, `"stream"`, `"end"`, `"error"`, `"info"`, `"suggest"`
`session`	string	Định danh session	Chuỗi UUID
`trace_id`	string	ID trace của yêu cầu	Chuỗi UUID hoặc null
`question_id`	string	ID của câu hỏi	Chuỗi UUID hoặc null
`error_code`	integer	Mã lỗi trạng thái	Xem bảng mã lỗi

Các Loại Tin Nhắn

1. info - Thông Tin Kết Nối Ban Đầu

Được gửi ngay sau khi thiết lập kết nối.

{
  "role": "bot",
  "content": "{\"username\":\"User\",\"token_limit\":1000}",
  "type": "info",
  "session": "session-uuid"
}

2. start - Bắt Đầu Phản Hồi

Cho biết bot bắt đầu phản hồi.

{
  "role": "bot",
  "content": "",
  "type": "start",
  "session": "session-uuid",
  "trace_id": "trace-uuid",
  "question_id": "question-id",
}

3. stream - Nội Dung Streaming

Chứa các phần của phản hồi bot (để streaming theo thời gian thực).

{
  "role": "bot",
  "content": "Phần phản hồi một phần",
  "type": "stream",
  "session": "session-uuid",
  "trace_id": "trace-uuid",
  "question_id": "question-id",
}

4. end - Hoàn Thành Phản Hồi

Cho biết bot đã hoàn thành phản hồi.

{
  "role": "bot",
  "content": "",
  "type": "end",
  "session": "session-uuid",
  "trace_id": "trace-uuid",
  "question_id": "question-id",
}

5. suggest - Câu Hỏi Gợi Ý

Cung cấp các câu hỏi tiếp theo gợi ý.

{
  "role": "bot",
  "content": "Nội dung câu hỏi gợi ý",
  "type": "suggest",
  "session": "session-uuid",
  "trace_id": "trace-uuid",
  "question_id": "question-id",
}

6. error - Phản Hồi Lỗi

Cho biết có lỗi xảy ra trong quá trình xử lý.

{
  "role": "bot",
  "content": "Thông báo lỗi",
  "type": "error",
  "session": "session-uuid",
  "trace_id": "trace-uuid",
  "question_id": "question-id",
  "error_code": 429
}

Mã Lỗi

Mã	HTTP Status	Mô tả	Hành động cần thiết
`0`	200	Không có lỗi	Không có
`400`	400	Yêu cầu không hợp lệ	Kiểm tra định dạng yêu cầu
`429`	429	Vượt quá giới hạn tốc độ	Chờ hoặc nâng cấp gói
`502`	502	Lỗi dịch vụ OpenAI	Thử lại sau
`503`	503	Lỗi server	Liên hệ hỗ trợ

Giới Hạn Tốc Độ

Mỗi người dùng có giới hạn sử dụng token dựa trên gói đăng ký
Khi vượt quá giới hạn, server phản hồi với mã lỗi 429
Giới hạn được reset hàng ngày

Ví Dụ Triển Khai

Ví Dụ JavaScript/TypeScript

websocket.js

class ChatbotClient {
  constructor(token, baseUrl = 'ws://localhost:8686') {
    this.token = token;
    this.baseUrl = baseUrl;
    this.socket = null;
    this.sessionId = null;
  }

  connect() {
    return new Promise((resolve, reject) => {
      this.socket = new WebSocket(`${this.baseUrl}/chat?token=${this.token}`);

      this.socket.onopen = () => {
        console.log('Đã kết nối với chatbot');
        resolve();
      };

      this.socket.onmessage = (event) => {
        const message = JSON.parse(event.data);
        this.handleMessage(message);
      };

      this.socket.onerror = (error) => {
        console.error('Lỗi WebSocket:', error);
        reject(error);
      };

      this.socket.onclose = () => {
        console.log('Kết nối đã đóng');
      };
    });
  }

  handleMessage(message) {
    switch (message.type) {
      case 'info':
        const userInfo = JSON.parse(message.content);
        console.log('Thông tin user:', userInfo);
        this.sessionId = message.session;
        break;

      case 'start':
        console.log('Bot bắt đầu phản hồi...');
        break;

      case 'stream':
        // Nối vào phản hồi hiện tại
        this.appendToResponse(message.content);
        break;

      case 'end':
        console.log('Bot đã hoàn thành phản hồi');
        break;

      case 'suggest':
        this.showSuggestion(message.content);
        break;

      case 'error':
        this.handleError(message);
        break;
    }
  }

  sendMessage(content) {
    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
      const message = {
        content: content,
        uuid: this.sessionId
      };
      this.socket.send(JSON.stringify(message));
    }
  }

  handleError(message) {
    switch (message.error_code) {
      case 429:
        alert('Vượt quá giới hạn tốc độ. Vui lòng thử lại sau.');
        break;
      case 503:
        alert('Dịch vụ tạm thời không khả dụng. Vui lòng thử lại.');
        break;
      default:
        alert('Đã xảy ra lỗi: ' + message.content);
    }
  }

  disconnect() {
    if (this.socket) {
      this.socket.close();
    }
  }
}

// Cách sử dụng
const client = new ChatbotClient('your-jwt-token');
client.connect().then(() => {
  client.sendMessage('Xin chào, Waka bán gì?');
});

Ví Dụ Python Client

websocket.py

import asyncio
import websockets
import json

class ChatbotClient:
    def __init__(self, token, base_url="ws://localhost:8686"):
        self.token = token
        self.base_url = base_url
        self.session_id = None

    async def connect(self):
        uri = f"{self.base_url}/chat?token={self.token}"
        async with websockets.connect(uri) as websocket:
            self.websocket = websocket

            # Xử lý tin nhắn đến
            async for message in websocket:
                data = json.loads(message)
                await self.handle_message(data)

    async def handle_message(self, message):
        msg_type = message['type']

        if msg_type == 'info':
            user_info = json.loads(message['content'])
            print(f"Đã kết nối với tư cách: {user_info['username']}")
            self.session_id = message['session']

        elif msg_type == 'stream':
            print(message['content'], end='', flush=True)

        elif msg_type == 'error':
            print(f"Lỗi {message['error_code']}: {message['content']}")

    async def send_message(self, content):
        message = {
            "content": content,
            "uuid": self.session_id
        }
        await self.websocket.send(json.dumps(message))

# Cách sử dụng
async def main():
    client = ChatbotClient('your-jwt-token')
    await client.connect()

asyncio.run(main())

Lưu ý khi triển khai

1. Quản Lý Kết Nối

Xử lý khi lỗi kết nối nếu có
Triển khai logic kết nối lại cho môi trường production
Đóng kết nối đúng cách khi hoàn thành

2. Xử Lý Tin Nhắn

Parse JSON responses một cách an toàn
Xử lý tất cả các loại tin nhắn một cách thích hợp
Triển khai xử lý lỗi phù hợp cho từng mã lỗi

3. Trải Nghiệm Người Dùng

Hiển thị loading indicators trong quá trình start đến end
Hiển thị streaming responses theo thời gian thực
Cung cấp thông báo lỗi rõ ràng cho người dùng
Triển khai thông báo giới hạn tốc độ

4. Bảo Mật

Không bao giờ expose JWT tokens trong client-side logs
Sử dụng secure WebSocket (wss://) trong production
Validate tất cả incoming messages

Khắc Phục Sự Cố

Các Vấn Đề Thường Gặp

Kết Nối Bị Từ Chối
Kiểm tra xem server có đang chạy không
Xác minh URL và port chính xác
Xác Thực Thất Bại
Đảm bảo JWT token hợp lệ và chưa hết hạn
Kiểm tra định dạng token trong query parameter
Vượt Quá Giới Hạn Tốc Độ
Chờ giới hạn được reset (thường là hàng ngày)
Cân nhắc nâng cấp gói sử dụng
Vấn Đề Streaming
Đảm bảo xử lý đúng các tin nhắn loại stream
Nối các stream chunks theo đúng thứ tự

Debug

Sử dụng WebSocket debugging trong browser developer tools
Log tất cả incoming và outgoing messages trong quá trình phát triển
Theo dõi network tab để biết trạng thái kết nối
Kiểm tra server logs để có thông tin lỗi chi tiết

Hỗ Trợ

Để được hỗ trợ thêm hoặc có câu hỏi về tích hợp, vui lòng liên hệ đội ngũ phát triển hoặc tham khảo tài liệu API.