Tham chiếu API
Xây dựng tích hợp tùy chỉnh với Asyntai REST API
Yêu cầu Gói Trả phí: Truy cập API có sẵn trên gói Starter, Standard và Pro. Xem bảng giá
Tổng quan
API Asyntai cho phép bạn tích hợp hỗ trợ khách hàng được hỗ trợ bởi AI vào bất kỳ ứng dụng nào. Gửi tin nhắn và nhận phản hồi thông minh được huấn luyện trên nội dung website và cơ sở tri thức của bạn.
Xác thực
Tất cả yêu cầu API cần xác thực bằng khóa API của bạn. Bạn có thể lấy khóa API từ trang Cài đặt API.
Bao gồm khóa API của bạn trong yêu cầu bằng một trong các phương thức sau:
- Header Authorization (khuyến nghị):
Authorization: Bearer YOUR_API_KEY - Header X-API-Key:
X-API-Key: YOUR_API_KEY
Giữ bí mật khóa API của bạn. Bất kỳ ai có khóa của bạn đều có thể truy cập tài khoản qua API. Không bao giờ để lộ nó trong mã phía client.
URL Cơ sở
https://asyntai.com/api/v1/
Điểm cuối
POST /chat/
Gửi tin nhắn và nhận phản hồi do AI tạo.
Nội dung Yêu cầu
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
message |
string | Có | Tin nhắn của người dùng gửi đến AI |
session_id |
string | Không | Mã định danh duy nhất cho cuộc trò chuyện. Sử dụng cùng session_id để duy trì lịch sử cuộc trò chuyện. |
website_id |
integer | Không | ID website cụ thể. Nếu không được cung cấp, sẽ sử dụng website chính của bạn. |
Phản hồi
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Ví dụ (cURL)
curl -X POST https://asyntai.com/api/v1/chat/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What are your business hours?", "session_id": "user_123"}'
Ví dụ (Python)
import requests
response = requests.post(
"https://asyntai.com/api/v1/chat/",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"message": "What are your business hours?",
"session_id": "user_123"
}
)
data = response.json()
print(data["response"])
Ví dụ (JavaScript)
const response = await fetch("https://asyntai.com/api/v1/chat/", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
message: "What are your business hours?",
session_id: "user_123"
})
});
const data = await response.json();
console.log(data.response);
GET /websites/
Liệt kê tất cả website liên kết với tài khoản của bạn.
Phản hồi
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Ví dụ (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET /conversations/
Truy xuất lịch sử cuộc trò chuyện cho một phiên cụ thể.
Tham số Truy vấn
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
session_id |
string | Có | ID phiên để truy xuất lịch sử |
limit |
integer | Không | Số tin nhắn tối đa trả về (mặc định: 50, tối đa: 100) |
Phản hồi
{
"success": true,
"session_id": "user_123",
"messages": [
{
"role": "user",
"content": "What are your business hours?",
"timestamp": "2024-01-15T10:30:00Z"
},
{
"role": "assistant",
"content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"timestamp": "2024-01-15T10:30:01Z"
}
]
}
Ví dụ (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Liệt kê các phiên chat gần đây của bạn. Sử dụng để tìm ID phiên, sau đó bạn có thể truyền vào /conversations/ để truy xuất toàn bộ lịch sử tin nhắn.
Tham số Truy vấn
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
limit |
integer | Không | Số phiên gần đây trả về (mặc định: 20, tối đa: 100) |
website_id |
string | Không | Lọc phiên theo ID website cụ thể |
source |
string | Không | Lọc theo nguồn phiên: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Phản hồi
{
"success": true,
"sessions": [
{
"session_id": "session_abc123def",
"source": "widget",
"message_count": 5,
"first_message": "What are your business hours?",
"first_message_at": "2024-01-15T10:30:00Z",
"last_message_at": "2024-01-15T10:35:00Z",
"website_domain": "example.com"
}
]
}
Ví dụ (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Lấy danh sách khách hàng tiềm năng đã thu thập — địa chỉ email và số điện thoại được khách truy cập gửi trong các cuộc trò chuyện.
Tham số Truy vấn
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
limit |
integer | Không | Số lượng khách hàng tiềm năng cần trả về (mặc định: 50, tối đa: 100) |
website_id |
string | Không | Lọc khách hàng tiềm năng theo ID trang web cụ thể |
Phản hồi
{
"success": true,
"leads": [
{
"session_id": "session_abc123def",
"email": "visitor@example.com",
"phone": "+1234567890",
"page_url": "https://example.com/pricing",
"started_at": "2024-01-15T10:30:00Z"
}
]
}
| Trường | Loại | Mô tả |
|---|---|---|
session_id |
string | ID phiên trò chuyện. Truyền giá trị này cho /conversations/ để xem toàn bộ lịch sử trò chuyện. |
email |
chuỗi hoặc null | Địa chỉ email do khách truy cập cung cấp, hoặc null nếu không được thu thập |
phone |
chuỗi hoặc null | Số điện thoại do khách truy cập cung cấp, hoặc null nếu không được thu thập |
page_url |
chuỗi hoặc null | URL trang mà khách truy cập đang trò chuyện |
started_at |
string | Dấu thời gian ISO 8601 khi phiên trò chuyện bắt đầu |
Ví dụ (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Ví dụ (Python)
import requests
response = requests.get(
"https://asyntai.com/api/v1/leads/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"limit": 20}
)
leads = response.json()["leads"]
for lead in leads:
print(f"{lead['email'] or ''} | {lead['phone'] or ''}")
GET /account/
Lấy thông tin tài khoản và thống kê sử dụng của bạn.
Phản hồi
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Ví dụ (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Nhiều website? Điểm cuối cơ sở tri thức mặc định là website chính của bạn. Nếu bạn có nhiều website, truyền website_id để nhắm mục tiêu một website cụ thể. Bạn có thể tìm ID website bằng cách sử dụng GET /websites/.
Giới hạn tải lên hàng ngày: Việc tải lên cơ sở tri thức (văn bản, URL, bảng tính) bị giới hạn ký tự hàng ngày dựa trên gói của bạn. Điều này áp dụng cho tổng nội dung được tải lên trên tất cả điểm cuối cơ sở tri thức mỗi ngày.
| Gói | Ký tự/ngày |
|---|---|
| Starter | 100.000 |
| Standard | 500.000 |
| Pro | 2.000.000 |
GET /knowledge/
Liệt kê các mục cơ sở tri thức của bạn. Đây là các nguồn nội dung mà chatbot AI của bạn sử dụng để trả lời câu hỏi.
Tham số Truy vấn
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
limit |
integer | Không | Số mục trả về (mặc định: 50, tối đa: 100) |
website_id |
string | Không | Lọc theo ID website (mặc định là website chính của bạn) |
Phản hồi
{
"success": true,
"entries": [
{
"id": "abc-123-def",
"type": "text",
"title": "Business Hours",
"description": "Manual text content (150 words)",
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "ghi-456-jkl",
"type": "url",
"title": "About Us - Example",
"description": "Content from https://example.com/about",
"created_at": "2024-01-14T09:00:00Z"
}
]
}
Ví dụ (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Thêm nội dung văn bản tùy chỉnh vào cơ sở tri thức của bạn. AI sẽ sử dụng nội dung này để trả lời câu hỏi của khách truy cập.
Nội dung Yêu cầu
{
"title": "Return Policy",
"content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
"website_id": "123"
}
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
title |
string | Có | Tiêu đề cho mục tri thức này |
content |
string | Có | Nội dung văn bản (tối thiểu 10 ký tự) |
website_id |
string | Không | Website mục tiêu (mặc định là website chính của bạn) |
Phản hồi
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Ví dụ (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'
POST /knowledge/url/
Thêm trang web vào cơ sở tri thức của bạn. Nội dung sẽ được tải và trích xuất tự động.
Nội dung Yêu cầu
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
url |
string | Có | URL để tải nội dung từ |
website_id |
string | Không | Website mục tiêu (mặc định là website chính của bạn) |
Phản hồi
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Ví dụ (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/faq"}'
POST /knowledge/spreadsheet/
Tải lên bảng tính CSV hoặc Excel (.xlsx) vào cơ sở tri thức của bạn. Mỗi hàng trở thành một mục tri thức riêng biệt, lý tưởng cho danh mục sản phẩm, danh sách câu hỏi thường gặp, bảng giá và danh bạ.
Yêu cầu
Gửi dưới dạng multipart/form-data (tải lên tệp), không phải JSON.
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
file |
file | Có | Tệp .csv hoặc .xlsx. Hàng đầu tiên phải là tiêu đề cột. Số hàng tối đa mỗi lần tải: Starter 500, Standard 2.000, Pro 10.000. Các hàng thừa sẽ bị cắt bớt. |
website_id |
string | Không | Website mục tiêu (mặc định là website chính của bạn) |
Phản hồi
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Ví dụ (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@products.csv"
DELETE /knowledge/{id}/
Xóa một mục cơ sở tri thức. id có thể tìm thấy từ phản hồi GET /knowledge/.
Phản hồi
{
"success": true,
"message": "Knowledge base entry deleted"
}
Ví dụ (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Mẹo: Bạn cũng có thể quản lý webhooks từ Cài đặt API trang mà không cần viết bất kỳ mã nào.
GET /webhooks/
Liệt kê các webhook đã đăng ký của bạn.
Phản hồi
{
"success": true,
"webhooks": [
{
"id": "abc-123-def",
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"is_active": true,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
Ví dụ (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Đăng ký webhook mới để nhận thông báo sự kiện theo thời gian thực.
Sự kiện Có sẵn
| Sự kiện | Mô tả |
|---|---|
message.received |
Khách truy cập đã gửi tin nhắn và nhận được phản hồi |
conversation.started |
Một phiên chat mới đã được bắt đầu |
escalation.requested |
AI đã kích hoạt chuyển tiếp cho nhân viên hỗ trợ |
takeover.started |
Nhân viên hỗ trợ đã tiếp quản phiên chat |
Nội dung Yêu cầu
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
url |
string | Có | URL HTTPS để nhận yêu cầu POST webhook |
events |
array | Có | Danh sách sự kiện để đăng ký (xem bảng trên) |
website_id |
string | Không | Website mục tiêu (mặc định là website chính của bạn) |
Phản hồi
{
"success": true,
"webhook": {
"id": "abc-123-def",
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"secret": "whsec_abc123...",
"created_at": "2024-01-15T10:30:00Z"
}
}
Xác minh webhooks: Mỗi webhook bao gồm một secret (chỉ hiển thị khi tạo). Mỗi POST đến URL của bạn bao gồm một X-Webhook-Signature header — HMAC-SHA256 của nội dung yêu cầu được ký bằng khóa bí mật của bạn.
Ví dụ (cURL)
curl -X POST "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webhook", "events": ["message.received"]}'
DELETE /webhooks/{id}/
Xóa một webhook. id có thể tìm thấy từ phản hồi GET /webhooks/.
Phản hồi
{
"success": true,
"message": "Webhook deleted"
}
Ví dụ (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Phản hồi Lỗi
Tất cả phản hồi lỗi theo định dạng này:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Mã Trạng thái | Mô tả |
|---|---|
400 |
Yêu cầu không hợp lệ - Tham số không hợp lệ hoặc thiếu các trường bắt buộc |
401 |
Không được phép - Khóa API không hợp lệ hoặc bị thiếu |
429 |
Quá nhiều yêu cầu - Đã đạt giới hạn tin nhắn cho gói của bạn |
503 |
Dịch vụ Không khả dụng - Dịch vụ AI tạm thời không khả dụng |
Giới hạn Tốc độ
Việc sử dụng API bị giới hạn theo gói đăng ký của bạn:
- Free: 100 tin nhắn/tháng
- Starter ($39/tháng): 2.500 tin nhắn/tháng
- Standard ($139/tháng): 15.000 tin nhắn/tháng
- Pro ($449/tháng): 50.000 tin nhắn/tháng
Cần Trợ giúp?
Nếu bạn có bất kỳ câu hỏi nào hoặc gặp vấn đề, hãy liên hệ chúng tôi tại hello@asyntai.com.