Quay lại bảng điều khiển

Tài liệu

Tìm hiểu cách sử dụng Asyntai

Tham chiếu API

Xây dựng tích hợp tùy chỉnh với Asyntai REST API

Lấy Khóa 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 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 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
Starter100.000
Standard500.000
Pro2.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 Tiêu đề cho mục tri thức này
content string 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 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 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 URL HTTPS để nhận yêu cầu POST webhook
events array 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.