API 参考文档

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

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

概述

The Asyntai API allows you to integrate AI-powered customer support into any application. Send messages and receive intelligent responses grounded in your website content and knowledge base.

身份验证

所有 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"

POST /websites/

Create a new AI agent. This does the same thing as adding a website in your dashboard: it makes the agent, reads your site, and writes the first draft of the AI instructions.

Use this to set up customers from your own software. You get back the widget ID and the code to put on the website.

请求体

字段	类型	描述
`domain`	string	Required. The website address, for example example.com
`name`	string	Optional. A display name for the agent. Useful when one website has several agents.
`crawl`	boolean	Optional, true by default. Set it to false to create the agent without reading the website. Nothing is crawled and no instructions are written.
`force`	boolean	Optional, false by default. Set it to true to add a website you already have. The copy is stored with a number after it.

响应

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "crawl_started": true,
    "instructions_status": "generating",
    "job_id": "8f2c1e90-..."
  },
  "embed_code": "<script>...</script>"
}

示例（cURL）

curl -X POST https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "name": "Support agent"}'

Reading a website takes a few minutes, so this call answers straight away. Check when the agent is ready with the next endpoint.

Errors

Code	Meaning
`403`	You have reached the number of websites your plan allows. The answer tells you the limit.
`409`	Your account already has this website. Send force as true to add it again.

GET /websites/{id}/

Get one website and see whether it is ready. Use this after you create an agent, to wait until the website has been read and the AI instructions are written.

响应

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "created_at": "2026-08-11T09:12:00+00:00",
    "ready": true,
    "instructions": {
      "status": "completed",
      "has_instructions": true,
      "characters": 3421
    },
    "crawl": {
      "job_id": "8f2c1e90-...",
      "status": "completed",
      "pages_crawled": 47,
      "pages_found": 50,
      "max_pages": 50,
      "completed_at": "2026-08-11T09:15:31+00:00",
      "error": ""
    },
    "knowledge_items": 47
  },
  "embed_code": "<script>...</script>"
}

The ready field is true when nothing is still running. A crawl that failed also counts as ready, because it has finished. Look at the crawl status to see what happened.

示例（cURL）

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

GET PATCH /websites/{id}/settings/

Read or change the chat widget settings for one website. These are the same settings you see on the Customize page: colours, the name of the assistant, the first message, lead capture, and everything else.

Reading the settings

A GET request returns every setting with its current value, plus a locked list. Locked shows the settings your plan cannot change, and which plans they need.

{
  "success": true,
  "settings": {
    "ai_support_name": "AI Assistant",
    "widget_color": "#6366f1",
    "initial_message": "Hi, how can I help you?",
    "hide_branding": false,
    "...": "..."
  },
  "locked": {
    "hide_branding": ["pro", "enterprise"],
    "widget_style": ["pro", "enterprise"]
  }
}

Changing the settings

A PATCH request changes only the settings you send. Everything you leave out stays as it is.

curl -X PATCH https://asyntai.com/api/v1/websites/42/settings/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ai_support_name": "Ava", "widget_color": "#0f172a", "use_emoji": true}'

{
  "success": true,
  "updated": ["ai_support_name", "use_emoji", "widget_color"],
  "settings": { "...": "..." },
  "locked": { "...": "..." }
}

Plans

Each setting needs its own plan, the same as in the dashboard. For example, hiding the Asyntai branding needs the Pro plan, and voice input needs Standard.

Plan needed	设置	Examples
Any paid plan	25	`widget_color`, `ai_support_name`, `initial_message`
Starter 及以上	22	`profile_picture`, `conversation_starters_enabled`
Standard 及以上	25	`speech_to_text_enabled`, `image_vision_enabled`, `escalation_enabled`
Pro	6	`hide_branding`, `widget_style`

If you send a setting your plan does not allow, the whole request is refused with code 403 and nothing is saved. The same happens if any value is wrong, for example a colour that is not a hex code. Your settings never end up half changed.

GET PUT /websites/{id}/instructions/

Read or replace the AI instructions for one website. These are the rules that tell the assistant who it is, what it may say, and what it must not say. They are the same instructions you edit in the dashboard.

Reading

{
  "success": true,
  "instructions": "You are the support agent for Acme Tools...",
  "characters": 1979,
  "version": 7,
  "mode": "instructions",
  "ask_questions": true,
  "generation_status": "completed",
  "being_edited_by": null
}

Replacing

A PUT request replaces the whole text, the same as saving in the dashboard. There is no append mode. To add a paragraph, read the instructions, add your text, then write it back.

curl -X PUT https://asyntai.com/api/v1/websites/42/instructions/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "You are the support agent for Acme Tools...", "version": 7}'

请求体

字段	类型	描述
`instructions`	string	Required. The complete new text. It replaces everything that was there.
`version`	number	Optional but recommended. The version you read. If somebody changed the instructions since then, your write is refused instead of overwriting their work.
`mode`	string	Optional. Either instructions or general.
`ask_questions`	boolean	Optional. Whether the assistant asks a follow-up question at the end of its answers.
`force`	boolean	Optional, false by default. Needed only when your new text is less than half the length of the current text.

How your instructions are protected

Instructions can take hours to write, so a write can be refused to protect them:

Code	Meaning
`400`	Your new text is less than half the length of the current text. This catches a script that sends empty or cut-off text over instructions somebody spent hours on. Send force as true if you meant it.
`409`	The instructions changed after you read them. Read them again, apply your change, then write.
`423`	Somebody is editing the instructions in the dashboard right now. The answer tells you who. Try again in a couple of minutes.

Every change also saves a copy of the previous text, so an earlier version can always be restored from the dashboard.

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",
      "sender_type": "ai",
      "agent_name": null,
      "response_time_ms": 1840.5
    }
  ]
}

问题和它的回答保存在同一条记录中，因此两者带有相同的 timestamp。不要用一个减去另一个来衡量回复速度，因为结果始终为零。请使用 response_time_ms，它是回答实际花费的时间，单位为毫秒。

当聊天机器人回答时，sender_type 为 ai；当您的某位客服接管对话时，为 human。agent_name 保存该客服的显示名称。

示例（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",
      "first_response_time_ms": 1840.5,
      "first_human_response_at": null,
      "started_at": "2024-01-15T10:29:58Z",
      "ended_at": "2024-01-15T10:41:12Z",
      "taken_over_at": null,
      "website_domain": "example.com"
    }
  ]
}

用于报表的时间戳字段

字段	描述
`started_at`	访客打开对话的时间。仅适用于挂件会话，因为通过 API 创建的会话从不打开挂件。
`first_message_at`	对话的第一条消息保存的时间。
`first_response_time_ms`	第一次回答花费的时间，单位为毫秒。请用它来计算首次响应时间。
`first_human_response_at`	您的某位客服发出第一条回复的时间。当聊天机器人处理了整个对话时，该值为 `null`。
`taken_over_at`	客服从聊天机器人手中接管对话的时间。
`last_message_at`	对话的最后一条消息保存的时间。
`ended_at`	访客离开对话的时间。对话没有已解决或已关闭状态，因为访客随时可以回来再问一个问题。

所有时间戳均为 UTC，使用 ISO 8601 格式。您无法更改时区。请在您自己的报表工具中转换这些值。

示例（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": "[email protected]",
      "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": "[email protected]",
    "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	300,000
Standard	1,500,000
Pro	6,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 "[email protected]"

GET /knowledge/{id}/

读取知识库中的一个条目，包括为其保存的文本。id 的值来自 GET /knowledge/ 的响应。

系统会返回您自己添加的条目的内容：文本、文件、电子表格、单个网址和视频。网站抓取仍会列出，但不会返回其页面，因为来源是您自己的公开网站。此时 content 为 null，并由 reason 字段说明原因。

响应

{
  "success": true,
  "id": "abc-123-def",
  "type": "text",
  "title": "Business Hours",
  "description": "Manual text content (150 words)",
  "created_at": "2024-01-15T10:30:00Z",
  "chunks_count": 3,
  "content": "We are open Monday to Friday, 9am to 5pm...",
  "content_available": true,
  "char_count": 43
}

示例（cURL）

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

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条消息

需要帮助？

如果您有任何问题或遇到困难，请通过 [email protected] 联系我们。