> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihive.global/llms.txt
> Use this file to discover all available pages before exploring further.
# Developers
> Developers - AI Hive Documentation
# Tài liệu cho Lập trình viên (Developers & API)
AIHive cung cấp bộ công cụ mạnh mẽ (API & SDK) giúp bạn tích hợp trí tuệ nhân tạo vào website, ứng dụng di động hoặc hệ thống quản trị nội bộ (ERP/CRM) một cách nhanh chóng.
***
## Tích hợp Chat Widget (Web SDK)
Đây là giải pháp "mì ăn liền" (No-code) giúp bạn đưa AIHive lên website chỉ với một đoạn mã HTML đơn giản.
Đầu tiên hãy vào giao diện **“Thiết lập AI”**, sau khi thiết lập hoàn tất. Nhấn **“Xuất bản”**
` của website:
```html theme={null}
```
### Cách 2: Nhúng toàn màn hình (Full Page)
Biến một trang web con thành giao diện chat AI chuyên biệt (giống giao diện ChatGPT).
Dán đoạn mã sau vào thẻ ``:
```html theme={null}
```
### Cách 3: Nhúng iFrame (Khung chat cố định)
Chèn khung chat vào một vị trí cố định trong bài viết hoặc giao diện dashboard quản trị.
```html theme={null}
```
## Chat API (Backend Integration)
Sử dụng API này để xây dựng giao diện chat tùy chỉnh (Custom UI) trên Mobile App hoặc gửi/nhận tin nhắn từ Server của bạn.
### 1. Thông tin kết nối
* **Base URL:** `https://api.aihive.global/v1`
* **Endpoint:** `/chat-messages`
* **Method:** `POST`
### 2. Xác thực (Authentication)
Vào giao diện thiết lập Agent nhấn “Xuất bản” và copy đoạn API Key ở đây
]()' \\
--header 'Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx' \\
--header 'Content-Type: application/json' \\
--data-raw '\{
"inputs": \{\},
"query": "Tư vấn cho tôi về sản phẩm",
"response_mode": "blocking",
"conversation_id": "",
"user": "khach-hang-01"
\}'
```
### 5. Ví dụ Response (Kết quả trả về)
Nếu gọi thành công, Server sẽ trả về JSON chứa câu trả lời của AI:
```json theme={null}
\{
"event": "message",
"message_id": "99f074xx-xxxx-xxxx",
"conversation_id": "88e912xx-xxxx-xxxx",
"mode": "chat",
"answer": "Chào bạn, AIHive có thể giúp gì cho bạn hôm nay?",
"metadata": \{
"usage": \{
"prompt_tokens": 50,
"completion_tokens": 20,
"total_tokens": 70
\}
\},
"created_at": 1705634000
\}
```
## Xử lý lỗi (Error Handling)
| **Mã lỗi (HTTP Code)** | **Nguyên nhân** | **Cách khắc phục** |
| ------------------------- | --------------------- | -------------------------------------------------------------------- |
| **401 Unauthorized** | Sai API Key. | Kiểm tra lại Header `Authorization` xem đã đúng key chưa. |
| **402 Payment Required** | Hết hạn mức gói cước. | Nạp tiền hoặc nâng cấp gói AIHive. |
| **404 Not Found** | Sai đường dẫn API. | Kiểm tra lại Base URL xem có đúng `https://api.aihive.global` không. |
| **429 Too Many Requests** | Gửi quá nhanh (Spam). | Giới hạn tốc độ gửi tin hoặc liên hệ nâng cấp. |
### Cách 1: Nút Chat nổi (Floating Bubble)
Hiển thị biểu tượng chat ở góc màn hình. Phù hợp cho Landing Page hoặc trang chủ.
Copy đoạn mã sau và dán vào thẻ `` hoặc `