API 参考文档

使用 Asyntai REST API 构建自定义集成

获取 API 密钥

需要付费套餐： API 访问适用于 Starter、Standard 和 Pro 套餐。查看定价

概述

Asyntai API 允许您将 AI 驱动的客户支持集成到任何应用程序中。发送消息并接收基于您的网站内容和知识库训练的智能回复。

身份验证

所有 API 请求都需要使用您的 API 密钥进行身份验证。您可以从 API 设置页面获取 API 密钥。

使用以下方法之一在请求中包含您的 API 密钥：

Authorization header (recommended): Authorization: Bearer YOUR_API_KEY
X-API-Key header: X-API-Key: YOUR_API_KEY

请妥善保管您的 API 密钥。 任何拥有您密钥的人都可以通过 API 访问您的账户。切勿在客户端代码中暴露密钥。

基础 URL

https://asyntai.com/api/v1/

端点

POST /chat/

发送消息并接收 AI 生成的回复。

请求体

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}

参数	类型	必填	描述
`message`	string	是	发送给 AI 的用户消息
`session_id`	string	否	对话的唯一标识符。使用相同的 session_id 以保持对话历史记录。
`website_id`	integer	否	指定网站 ID。如果未提供，则使用您的主要网站。

响应

{
  "success": true,
  "response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
  "session_id": "user_123"
}

示例（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"}'

示例（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"])

示例（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/

列出与您账户关联的所有网站。

响应

{
  "success": true,
  "websites": [
    {
      "id": 1,
      "name": "My Website",
      "domain": "example.com",
      "is_primary": true
    }
  ]
}

示例（cURL）

curl https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /conversations/

检索特定会话的对话历史记录。

查询参数

参数	类型	必填	描述
`session_id`	string	是	要检索历史记录的会话 ID
`limit`	integer	否	返回的最大消息数（默认：50，最大：100）

响应

{
  "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"
    }
  ]
}

示例（cURL）

curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /sessions/

列出您最近的聊天会话。用于获取会话 ID，然后传递给 /conversations/ 以检索完整的消息历史记录。

查询参数

参数	类型	必填	描述
`limit`	integer	否	返回的最近会话数（默认：20，最大：100）
`website_id`	string	否	按指定网站 ID 筛选会话
`source`	string	否	按会话来源筛选：`widget`、`api`、`whatsapp`、`instagram`、`messenger`、`gorgias`、`freshchat`、`zapier`

响应

{
  "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"
    }
  ]
}

示例（cURL）

curl "https://asyntai.com/api/v1/sessions/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /leads/

获取收集的潜在客户 — 访客在聊天对话中提交的电子邮件地址和电话号码。

查询参数

参数	类型	必填	描述
`limit`	integer	否	要返回的潜在客户数量（默认：50，最大：100）
`website_id`	string	否	按特定网站ID筛选潜在客户

响应

{
  "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"
    }
  ]
}

字段	类型	描述
`session_id`	string	聊天会话ID。将其传递给`/conversations/`以查看完整的聊天记录。
`email`	字符串或null	访客提供的电子邮件地址，如果未收集则为null
`phone`	字符串或null	访客提供的电话号码，如果未收集则为null
`page_url`	字符串或null	访客聊天所在的页面URL
`started_at`	string	聊天会话开始的ISO 8601时间戳

示例（cURL）

curl "https://asyntai.com/api/v1/leads/?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

示例（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/

获取您的账户信息和使用统计数据。

响应

{
  "success": true,
  "account": {
    "email": "you@example.com",
    "plan": "starter",
    "messages_used": 150,
    "messages_limit": 2500
  }
}

示例（cURL）

curl https://asyntai.com/api/v1/account/ \
  -H "Authorization: Bearer YOUR_API_KEY"

有多个网站？ 知识库端点默认使用您的主要网站。如果您有多个网站，请传递 website_id 以指定特定网站。您可以使用以下方式查找网站 ID GET /websites/.

每日上传限制： 知识库上传（文本、URL、电子表格）受每日字符数限制，限额取决于您的 Plan。此限制适用于每天所有知识库端点上传的总内容。

套餐	字符数/天
Starter	100,000
Standard	500,000
Pro	2,000,000

GET /knowledge/

列出您的知识库条目。这些是 AI 聊天机器人用来回答问题的内容来源。

查询参数

参数	类型	必填	描述
`limit`	integer	否	返回的条目数（默认：50，最大：100）
`website_id`	string	否	按网站 ID 筛选（默认为您的主要网站）

响应

{
  "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"
    }
  ]
}

示例（cURL）

curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /knowledge/text/

向知识库添加自定义文本内容。AI 将使用这些内容回答访客的问题。

请求体

{
  "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"
}

参数	类型	必填	描述
`title`	string	是	此知识库条目的标题
`content`	string	是	文本内容（最少10个字符）
`website_id`	string	否	目标网站（默认为您的主要网站）

响应

{
  "success": true,
  "id": "abc-123-def",
  "title": "Return Policy",
  "chunks_created": 1
}

示例（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/

将网页添加到您的知识库。内容将被自动抓取和提取。

请求体

{
  "url": "https://example.com/faq",
  "website_id": "123"
}

参数	类型	必填	描述
`url`	string	是	要抓取内容的 URL
`website_id`	string	否	目标网站（默认为您的主要网站）

响应

{
  "success": true,
  "id": "abc-123-def",
  "title": "FAQ - Example",
  "url": "https://example.com/faq",
  "chunks_created": 5
}

示例（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/

将 CSV 或 Excel（.xlsx）电子表格上传到您的知识库。每行将成为一个独立的知识库条目，非常适合产品目录、常见问题列表、价格表和通讯录。

请求

以 multipart/form-data（文件上传）格式发送，而非 JSON。

参数	类型	必填	描述
`file`	file	是	.csv 或 .xlsx 文件。第一行必须为列标题。每次上传最大行数：Starter 500 行，Standard 2,000 行，Pro 10,000 行。超出的行将被截断。
`website_id`	string	否	目标网站（默认为您的主要网站）

响应

{
  "success": true,
  "id": "abc-123-def",
  "title": "products.csv",
  "rows_processed": 15,
  "chunks_created": 15
}

示例（cURL）

curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@products.csv"

DELETE /knowledge/{id}/

删除知识库条目。id 可从 GET /knowledge/ 的响应中获取。

响应

{
  "success": true,
  "message": "Knowledge base entry deleted"
}

示例（cURL）

curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

提示： 您也可以通过以下页面管理 webhooks API 设置页面进行管理，无需编写任何代码。

GET /webhooks/

列出您已注册的 webhooks。

响应

{
  "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"
    }
  ]
}

示例（cURL）

curl "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /webhooks/

注册新的 webhook 以接收实时事件通知。

可用事件

事件	描述
`message.received`	访客发送了一条消息并收到了回复
`conversation.started`	新的聊天会话已开始
`escalation.requested`	AI 触发了转接至人工客服
`takeover.started`	人工客服接管了聊天会话

请求体

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}

参数	类型	必填	描述
`url`	string	是	接收 webhook POST 请求的 HTTPS URL
`events`	array	是	要订阅的事件列表（参见上表）
`website_id`	string	否	目标网站（默认为您的主要网站）

响应

{
  "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"
  }
}

验证 webhooks： 每个 webhook 包含一个 secret （仅在创建时显示）。每次 POST 到您的 URL 都包含一个 X-Webhook-Signature 头部 — 使用您的密钥对请求体进行 HMAC-SHA256 签名。

示例（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}/

删除 webhook。id 可从 GET /webhooks/ 的响应中获取。

响应

{
  "success": true,
  "message": "Webhook deleted"
}

示例（cURL）

curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

错误响应

所有错误响应遵循以下格式：

{
  "success": false,
  "error": "Error message describing what went wrong"
}

状态码	描述
`400`	错误请求 - 无效参数或缺少必填字段
`401`	未授权 - 无效或缺少 API 密钥
`429`	请求过多 - 已达到您套餐的消息上限
`503`	服务不可用 - AI 服务暂时不可用

速率限制

API 使用量受您的订阅套餐限制：

Free: 每月 100 条消息
Starter（$39/月）： 每月2,500条消息
Standard（$139/月）： 每月15,000条消息
Pro（$449/月）： 每月50,000条消息

需要帮助？

如果您有任何问题或遇到困难，请通过 hello@asyntai.com 联系我们。