开发者API

终极开发者 API 指南

本文档是整个 Chirps AI 平台的官方详尽 API 参考。我们已经规划了整个系统中每个开发人员安全的端点。您可以通过编程方式无头复制 100% 的仪表板功能。

Developer API

1. 认证及核心原则

基本 URL： https://chirps.cc

所有 API 端点都需要“授权”标头中的 Chirps API 密钥。您可以从仪表板的开发人员部分中的 API 管理器生成 API 密钥。

http

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

请求示例：

bash

curl -X GET https://chirps.cc/api/billing/usage \
  -H "Authorization: Bearer <YOUR_CHIRPS_API_KEY>" \
  -H "Content-Type: application/json"

标准错误处理

状态码	描述
`200 好`	请求成功。
`400 错误请求`	JSON 负载验证失败。包括一个详细信息数组。
`401 未经授权`	令牌丢失或过期。
`402 需要付款`	工作区已达到计费限制。
《403 禁止》	用户没有所需的 RBAC 权限。
`404 未找到`	请求的资源不存在。
`500 服务器错误`	意外的平台错误。

Developer API

2. 助理生命周期（创建）

GET /api/assistants

列出助理

获取与 API 密钥工作区关联的所有助手的列表。

创建助理

POST /api/assistants

创建具有所有基本配置的新助手。

json

{

  "businessName": "Acme Corp",
  "businessUrl": "https://acme.com",
  "knowledgeBaseType": "both",
  "knowledgeBaseUrl": "https://acme.com/help",
  "knowledgeBaseText": "Raw text content of a document...",
  "knowledgeBaseFileName": "company_handbook.pdf",
  "language": "en",
  "isMultiLanguage": false,
  "tonePersonality": "professional",
  "isCustomPersonality": false,
  "supportEmail": "[email protected]",
  "maxPages": 5,
  "maxDepth": 2,
  "welcomeMessageDelay": 2
}

范围	类型	必需的	描述
`企业名称`	细绳	是的	公司名称（2-100 个字符）。
`businessUrl`	细绳	是的	企业网站的有效 URL（最多 500 个字符）。
`知识库类型`	枚举	是的	以下之一：“url”、“文档”、“两者”、“无”。
`知识库网址`	细绳	不	如果类型是“url”或“both”，则必须提供。
`知识库文本`	细绳	不	如果类型为“文档”或“两者”，则为原始文本。
`知识库文件名`	细绳	不	如果提供文本，则为上传文件的名称。
`语言`	细绳	是的	语言代码（例如“en”、“es”）。
`是多语言`	布尔值	不	启用自动翻译。默认为“假”。
`语气个性`	细绳	是的	例如，“专业”、“友好”。最多 100 个字符。
`isCustomPersonality`	布尔值	不	启用自定义音调。默认为“假”。
`自定义个性描述`	细绳	不	自定义提示音说明（如果启用）（最多 2000 个字符）。
`附加说明`	细绳	不	核心提示说明（最多 10000 个字符）。
`支持电子邮件`	细绳	是的	用于升级的有效电子邮件地址。
`最大页数`	数字	不	要抓取的页面。最小值 1，最大值 100。默认为“5”。
`最大深度`	数字	不	爬行深度。最小值 1，最大值 20。默认为“2”。
`欢迎消息延迟`	数字	不	问候前延迟几秒。最小值 0，最大值 6。默认为“2”。

删除助手

删除 /api/assistants/:id

永久删除助手并级联删除其所有知识节点和历史记录。无需有效负载。

Developer API

3. 助理分析与统计

创建和使用后，您可以立即以编程方式获取助手的性能指标。

GET /api/analytics/overview?assistantId=uuid&range=30

获取指定助理的使用情况统计信息、消息总数、捕获的潜在客户以及一般参与度指标。 range 参数是可选的（天数，最小值 7，最大值 365，默认 30）。

预期反应

json

{

  "totalConversations": 1245,
  "totalMessages": 8420,
  "totalLeads": 156,
  "totalBookings": 42,
  "satisfactionRate": 94,
  "avgMessagesPerSession": 6.7,
  "avgSessionsPerDay": 41.5,
  "liveNow": 3,
  "onlineNow": 12,
  "dailySeries": [
    {
      "date": "2026-07-15",
      "conversations": 45,
      "messages": 310,
      "leads": 5,
      "bookings": 2
    }
  ],
  "agentStats": [
    {
      "name": "Jane Doe",
      "messagesSent": 120,
      "csat": 98
    }
  ]
}

财产	类型	描述
`总对话数`	数字	助理处理的聊天会话总数。
`总消息数`	数字	所有对话中发送的消息总数（用户 + AI）。
`总潜在客户`	数字	提取的唯一潜在客户（姓名、电子邮件、电话）总数。
`总预订量`	数字	成功预订的日历约会总数。
`满意度`	数字	正面反馈评分占总评分的百分比 (0-100)。
`每会话平均消息数`	数字	每次对话交换的平均消息数。
`平均每天会话数`	数字	在要求的范围内每天的平均会话数。
`现在直播`	数字	当前由人工代理接管的活动对话数量。
`现在在线`	数字	最近2分钟内主动与AI聊天的用户数量。
「每日系列」	大批	每日对象数组，包含每个日期的“对话”、“消息”、“潜在客户”和“预订”计数。
`代理统计`	大批	人工代理的性能指标，包括“messagesSent”和“csat”（客户满意度得分）。

Developer API

4. 知识与培训

创建助手后，您可以通过“知识节点”管理它的大脑。每个节点代表一块数据（爬行的 URL、上传的文档或手动文本片段）。

管理知识节点

GET /api/assistants/:id/nodes - 列出该助手的所有知识节点。

POST /api/assistants/:id/nodes - 手动注入新的知识块。

json

{

  "title": "Return Policy",
  "refined_content": "We offer a 30-day return policy for all unused items...",
  "type": "text",
  "metadata": {}
}

PATCH /api/assistants/:id/nodes/:nodeId - 修改现有节点的内容或切换其活动状态。

json

{

  "title": "Updated Return Policy",
  "refined_content": "We offer a 60-day return policy now...",
  "is_active": true
}

DELETE /api/assistants/:id/nodes/:nodeId - 完全删除知识块。

POST /api/assistants/:id/nodes/:nodeId/re-crawl - 强制抓取工具重新抓取与此节点关联的 URL 并更新其内容。有效负载：{}。

人工智能培训

POST /api/assistants/:id/train - 编译所有 is_active 知识节点并使用 AI 编排器动态合成新的主系统提示。有效负载：{}。

Developer API

5. 小部件外观和配置

自定义助手气泡和聊天窗口的前端 UI。

更新小部件外观

PATCH /api/assistants/:id/widget-config

json

{

  "primaryColor": "#000000",
  "position": "bottom-right",
  "language": "en",
  "welcomeMessage": "Hi! How can I help you today?",
  "title": "Acme Support",
  "theme": "light",
  "fontFamily": "default",
  "bubbleStyle": "circle",
  "bubbleText": "Chat with us",
  "headerSubtitle": "We typically reply instantly",
  "inputPlaceholder": "Type your message...",
  "privacyPolicyUrl": "https://acme.com/privacy",
  "voiceEnabled": true,
  "voiceName": "Fenrir",
  "welcomeMessageDelay": 2,
  "fileUploadEnabled": true,
  "dictationEnabled": true,
  "copilotEnabled": true,
  "welcomeSuggestions": ["Pricing plans", "Contact sales"],
  "pageVisibility": {
    "mode": "all",
    "paths": []
  }
}

范围	类型	必需的	描述
`原色`	细绳	不	十六进制颜色代码（例如“#000000”）。
`位置`	枚举	不	“右下”、“左下”、“右上”、“左上”。
`语言`	细绳	不	小部件语言代码（例如“en”、“fr”）。
`欢迎消息`	细绳	不	最初的问候语。
`标题`	细绳	不	小部件标题中的标题。
`主题`	枚举	不	“亮”或“暗”。
`字体家族`	枚举	不	“默认”（国际）或“继承”。
`气泡样式`	枚举	不	`“圆形”`、`“吧台”`、`“抽屉”`、“品牌圆”、“品牌吧台”、“品牌抽屉”`。
`气泡文本`	细绳	不	显示在气泡旁边的文本（对于栏/抽屉样式）。
`标题副标题`	细绳	不	小部件标题中的副标题。
`输入占位符`	细绳	不	消息输入的占位符文本。
`隐私策略Url`	细绳	不	您的隐私政策的 URL。
`头像网址`	细绳	不	自定义头像图像的 URL。
`自定义徽标网址`	细绳	不	自定义标题徽标图像的 URL。
`语音已启用`	布尔值	不	启用语音通话。
`语音名称`	细绳	不	音频响应的语音标识。请参阅下面的可用声音。
`欢迎消息延迟`	数字	不	问候前延迟几秒。
`文件上传已启用`	布尔值	不	允许用户上传附件。
`听写已启用`	布尔值	不	启用语音听写（语音转文本）。
`副驾驶已启用`	布尔值	不	启用副驾驶建议芯片。
`欢迎建议`	大批	不	用于初始快速回复芯片的字符串数组。
`页面可见性`	目的	不	确定小部件出现在哪些页面上（“mode”、“paths”）。
`rateLimitEnabled`	布尔值	不	启用聊天速率限制。默认为真。
`rateLimitMaxMessages`	数字	不	窗口中的最大消息数。默认 30。
`速率限制时间窗口`	数字	不	时间窗口以分钟为单位。默认 60。
`gdprDataMaskingEnabled`	布尔值	不	保存前屏蔽 PII。默认为 false。

可用的语音名称

女性： Zephyr、Aoede、Core、Leda、Callirrhoe、Despina、Erinome、Laomedeia、Achernar、Pulcherrima、Gacrux、Algenib、Sulfat
男性： Puck、Charon、Fenrir、Orus、Enceladus、Iapetus、Umbriel、Algieba、Autonoe、Rasalgethi、Alnilam

定制标志

POST /api/assistants/:id/widget-logo

格式： multipart/form-data 与 file 字段。

Developer API

6. 集成与部署

配置并培训您的助手后，您可以通过两种主要方式来部署它：

选项 A：Web 嵌入（前端）

将助手集成到标准网站（WordPress、Shopify、React 等）的最简单方法。嵌入代码纯粹是确定性的。您不需要端点来获取它。只需将其放入站点的“<head>”即可：

json

<script src="https://chirps.cc/widget.js" data-assistant-id="YOUR_ASSISTANT_ID_HERE"></script>

选项 B：无头集成（后端/CRM/机器人）

如果您正在构建自定义客户端（例如 Discord 机器人、Telegram 集成或本机 iOS 应用程序），您将不会使用 Web Embed。相反，您将直接与“/api/chat”端点交互。

POST /api/chat 或 /api/chat?stream=true

注意： 该端点是公共的，并且*不需要*需要“Authorization: Bearer” API 密钥标头。身份验证通过“assistantId”隐式处理。

json

{

  "assistantId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "unique-session-id-for-user",
  "conversationId": "optional-uuid",
  "message": "Hello, I need help with my billing."
}

*（如果“fileUploadEnabled”为 true，还支持带有“file”附件字段的“multipart/form-data”）。*

范围	类型	必需的	描述
`助理ID`	细绳	是的	助手的UUID。
`会话ID`	细绳	是的	您生成此。来自您自己的系统的唯一标识符，用于对聊天历史记录进行分组（例如，Discord 用户 ID、Telegram 聊天 ID 或随机 UUID）。
`消息`	细绳	是的	消息的文本内容（最多 5000 个字符）。
`对话 ID`	细绳	不	对话的 UUID（在您的第一个请求中返回）。
`id`	细绳	不	可选的客户端消息 ID 以防止重复数据删除。

模式 1：标准 JSON 响应（默认）

通过向“/api/chat”发送 POST 请求（不带流参数），您可以等待完整的 AI 响应并接收标准 JSON 对象。

json

{

  "message": "Here is the information you requested...",
  "conversationId": "uuid-of-conversation",
  "messageId": "uuid-of-message"
}

*（如果返回“is_active_agent: true”，则表示有人接管了聊天，并且“message”将为“null”。）*

模式 2：服务器发送的事件流式传输 (?stream=true)

通过将“?stream=true”附加到 URL，您将收到实时服务器发送事件 (SSE) 流。您的代码应该侦听这些特定的事件类型：

`事件：令牌`：包含{"text": "chunk"}。针对 AI 响应文本的每个块触发。
`事件：状态`：包含{"text": "搜索知识库..."}。表示后端工具执行状态。
`事件：完成`：包含{"messageId": "uuid", "conversationId": "uuid", "message": "full text"}。当生成完全完成时触发。
`事件：错误`：包含{"error": "错误消息"}。如果发生速率限制或错误则触发。

实时接管端点

GET /api/chat/sessions

检索历史会话。

POST /api/chat/toggle-agent

暂停人工智能让人类接管。有效负载：{“sessionId”：“...”}

POST /api/chat/agent-message

发送人类消息。负载：{ "sessionId": "...", "message": "..." }

Developer API

7. 高级助手设置

PATCH /api/assistants/:id

更新核心配置

修改助手的核心设置、角色和抓取范围。

json

{

  "business_name": "Acme Corp",
  "business_url": "acme.com",
  "business_description": "We sell anvils.",
  "system_prompt": "You are a helpful assistant.",
  "language": "en",
  "tone_personality": "Friendly",
  "support_email": "[email protected]",
  "additional_instructions": "Never mention the Roadrunner.",
  "is_multi_language": true,
  "is_dev_mode": false,
  "is_active": true,
  "max_pages": 15,
  "max_depth": 2,
  "widget_config_merge": {
    "rateLimitEnabled": true
  }
}

*注意：所有字段都是可选的。仅发送您要更新的字段。*

删除助手

删除 /api/assistants/:id

永久删除助手，并级联删除所有知识节点、对话、消息。如果助手从未完全设置，则会退还每月创建配额。

Developer API

8. 电话和语音

GET /api/phone-numbers - 列出可用号码。

POST /api/phone-numbers/:id/assign - 提供号码。有效负载：{}

POST /api/assistants/:id/outbound - 触发出站呼叫。有效负载：{“to”：“+123...”，“message”：“...”}

Developer API

9. 线索提取

GET /api/leads?assistantId=uuid&page=1&limit=50&status=new - 获取对话期间人工智能提取的分页、结构化线索。

GET /api/leads?id=leadId - 获取单个潜在客户的详细信息，包括完整的对话记录。

Developer API

10. 预订和日历

GET /api/bookings?assistantId=uuid&start=ISO-8601&end=ISO-8601 - 检索助理安排的日历约会，可以选择按日期过滤。

GET /api/bookings?id=bookingId - 获取单个预订的详细信息，包括对话记录。

POST /api/bookings/cancel - 取消有效预订。有效负载：{“bookingId”：“uuid”}

POST /api/bookings/reschedule - 调整预订。有效负载：{“bookingId”：“uuid”，“newTime”：“ISO-8601”}

Developer API

11. 账户和账单使用

GET /api/billing/usage

检索工作区的计费周期使用情况、订阅计划限制和助理总数。 注意： 使用 API 密钥时，请求的范围将自动限定在 API 密钥的工作区；您不需要提供“teamId”。

响应（`200 OK`）：

json

{

  "planName": "Pro",
  "periodStr": "2023-10-01",
  "assistantCount": 3,
  "usage": {
    "message_count": 1450,
    "harvest_count": 12,
    "recrawl_count": 5,
    "train_count": 2,
    "assistants_created_count": 1,
    "voice_minutes_used": 0,
    "sms_count": 0,
    "email_count": 0,
    "whatsapp_count": 0
  },
  "limits": {
    "messages": 5000,
    "assistants": 5,
    "training": 50,
    "recrawls": 20
  },
  "workspaceOwnerId": "uuid"
}

准备好开始了吗？

启动你的助手
10 分钟后。

创建您的免费助手查看定价

终极开发者 API 指南

1. 认证及核心原则

标准错误处理

2. 助理生命周期（创建）

列出助理

创建助理

删除助手

3. 助理分析与统计

预期反应

4. 知识与培训

管理知识节点

人工智能培训

5. 小部件外观和配置

更新小部件外观

可用的语音名称

定制标志

6. 集成与部署

选项 A：Web 嵌入（前端）

选项 B：无头集成（后端/CRM/机器人）

模式 1：标准 JSON 响应（默认）

模式 2：服务器发送的事件流式传输 (?stream=true)

实时接管端点

7. 高级助手设置

更新核心配置

删除助手

8. 电话和语音

9. 线索提取

10. 预订和日历

11. 账户和账单使用

启动你的助手10 分钟后。

启动你的助手
10 分钟后。