终极开发者 API 指南

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

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

请求示例：

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

标准错误处理

作用域与最小权限

每个密钥仅限于所选作用域。尽可能使用只读密钥，并为每个集成创建单独的密钥。写入作用域不会自动授予对应的读取作用域。

assistants:read
assistants:write
analytics:read
artifacts:read
artifacts:write
billing:read
bookings:read
bookings:write
chat:write
connectors:read
connectors:write
conversations:read
conversations:write
knowledge:read
knowledge:write
leads:read
leads:write
telephony:read
telephony:write
widget:write

API-key rate limit

Each developer key is limited to 300 requests per rolling minute by default. The limit is atomic across all application instances and can be changed by the platform with API_KEY_RATE_LIMIT_PER_MINUTE. A rejected request returns 429; retry only after the window resets.

列出助理

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

创建助理

POST /api/assistants

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

{

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

删除助手

DELETE /api/assistants/:id

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

Creation validation and quota safety

Creation allowance is reserved atomically before insertion, so concurrent requests cannot exceed the monthly quota. Database insertion failures refund that reservation. A created assistant starts inactive in developer mode; call the setup endpoint and wait for its successful terminal event before publishing it.

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

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

预期反应

{

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

管理知识节点

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

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

{

  "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 - 修改现有节点的内容或切换其活动状态。

{

  "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 编排器动态合成新的主系统提示。有效负载：{}。

Upload, crawl, and index consistency

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

Send only the fields you want to change. The API rejects unknown keys and invalid nested data instead of silently storing configuration the widget cannot use.

{
  "designPreset": "corporate-soft",
  "primaryColor": "#1972F5",
  "theme": "dark",
  "bubbleStyle": "branded-drawer",
  "bubbleText": "Talk to our team",
  "welcomeMessages": [
    {
      "text": "Hello! How can I help?",
      "delay": 1.5
    }
  ],
  "welcomeSuggestions": [
    "View pricing",
    "Book a demo"
  ],
  "pageVisibility": {
    "mode": "exclude",
    "paths": [
      "/checkout/*"
    ]
  },
  "voiceEnabled": true,
  "voiceName": "Aoede",
  "copilotEnabled": true,
  "gdprConsentEnabled": true,
  "privacyPolicyUrl": "https://example.com/privacy"
}

Page visibility matching

Use exact paths such as /pricing, or append /* to include descendants such as /docs/*. include shows only matches; exclude hides matches; all ignores paths. Full URLs are normalized to their pathname by the widget.

Available voice names

Zephyr, Aoede, Kore, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulafat, Puck, Charon, Fenrir, Orus, Enceladus, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam, Schedar, Sadachbia, Achird, Zubenelgenubi, Sadaltager

GET /api/assistants/:id/artifacts · PUT /api/assistants/:id/artifacts · PATCH /api/assistants/:id/artifacts

Artifacts are tool-driven UI. The model calls the enabled tool and Chirps renders it; integrations must send configuration JSON, never {{ARTIFACT: ...}} strings.

{
  "form": {
    "enabled": true,
    "title": "Request a quote",
    "description": "Collect the details needed for a quote.",
    "triggerRules": "When a visitor explicitly asks for a quote.",
    "fields": [
      {
        "key": "name",
        "label": "Full name",
        "type": "text",
        "required": true,
        "placeholder": "Jane Doe"
      },
      {
        "key": "email",
        "label": "Work email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Request quote"
  },
  "booking": {
    "enabled": true,
    "title": "Book a consultation",
    "description": "Choose an available time.",
    "triggerRules": "When a visitor asks to book a meeting.",
    "services_enabled": false,
    "meetings_enabled": true,
    "requiresScheduling": true,
    "timezone": "Europe/Paris",
    "slotDuration": 30,
    "bufferMinutes": 10,
    "workingHours": {
      "monday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "tuesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "wednesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "thursday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "friday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "saturday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      },
      "sunday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      }
    },
    "blockedDates": [
      "2026-12-25"
    ],
    "meeting_intake_fields": [
      {
        "key": "email",
        "label": "Email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Book meeting"
  },
  "card": {
    "enabled": false,
    "ctaLabel": "View details",
    "ctaUrl": "",
    "description": "",
    "triggerRules": ""
  },
  "csat_survey": {
    "enabled": true,
    "title": "How was your experience?",
    "description": "One-click feedback.",
    "triggerRules": "Only after the request is resolved."
  },
  "custom": []
}

Field schema

Booking service schema

Validation limits and scheduling rules

Tool-call prefill behavior

Start with GET /api/marketplace/connectors. Its provider definitions are the source of truth for credential fields, configuration fields, available tools, defaults, and required values; this keeps custom and future providers discoverable without a documentation release.

{
  "provider": "shopify",
  "name": "Shopify",
  "credentials": {}
}

1. Install the workspace connector record with POST /api/assistants/:id/connectors; credentials must be omitted or {}.
2. Read its exact field schema from GET /api/marketplace/connectors and activate it with POST /api/assistants/:id/connectors/:connectorId/activate.
3. Send configValues, optional enabledTools, and optional instructions. Chirps verifies non-custom connectors and discovers the tools before saving the integration.
4. Rotate secrets by calling the activation endpoint again. PUT only renames a named Custom API.
5. Use DELETE /api/assistants/:id/connectors with { connectorId } to disable it for one assistant. Use the nested DELETE .../:connectorId only to permanently remove it from the workspace and every assistant.

选项 A：Web 嵌入（前端）

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

<script>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></script>

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

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

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

重要： 无头及服务器到服务器调用必须包含 Authorization: Bearer <YOUR_CHIRPS_API_KEY>。只有已安装的浏览器小组件使用与来源绑定的公开流程。切勿把 API 密钥放入前端 JavaScript。

{

  "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”）。*

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

通过向“/api/chat”发送 POST 请求（不带流参数），您可以等待完整的 AI 响应并接收标准 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) 流。您的代码应该侦听这些特定的事件类型：

• `event: token`：包含{"text": "chunk"}。针对 AI 响应文本的每个块触发。
• `event: status`：包含{"text": "Searching knowledge base..."}。表示后端工具执行状态。
• `event: done`：包含{"messageId": "uuid", "conversationId": "uuid", "message": "full text"}。当生成完全完成时触发。
• `event: error`：包含{"error": "Error message"}。如果发生速率限制或错误则触发。

实时接管端点

GET /api/chat/sessions

检索历史会话。

POST /api/chat/toggle-agent

暂停人工智能让人类接管。有效负载：{ "sessionId": "...", "isActive": true }

POST /api/chat/agent-message

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

Complete chat response contract

{
  "message": "I've opened the booking calendar for you.",
  "messageId": "uuid",
  "conversationId": "uuid",
  "artifacts": [
    {
      "type": "booking",
      "title": "Book a consultation"
    }
  ],
  "sources": []
}

A human takeover returns { message: null, conversationId, is_active_agent: true }. A streaming request can therefore return JSON before an SSE stream begins; check the response Content-Type.

Complete SSE event reference

更新核心配置

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

{

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

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

删除助手

DELETE /api/assistants/:id

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

POST /api/phone-numbers/:subscriptionId/assign assigns an already-purchased Chirps phone subscription to an assistant. Send { "assistantId": "uuid" }; send { "assistantId": null } to unassign it. This endpoint does not purchase or provision a new number.

POST /api/assistants/:id/outbound - 触发出站呼叫。有效负载：{ "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

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

Public lead response

Lead objects contain id, assistant_id, conversation_id, session_id, name, email, phone, status, notes, artifact_id, ai_score, ai_summary, form_data, created_at, and the assistant business name. Internal voice-confirmation/idempotency identifiers are never returned.

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

DELETE /api/bookings/cancel?id=bookingId - 取消有效预约。仅当您的集成确实要阻止 Chirps 发送备用取消邮件时，才添加 &silent=true。

POST /api/bookings/reschedule - 调整预订。有效负载：{ "bookingId": "uuid", "newStartTime": "ISO-8601", "newEndTime": "ISO-8601" }

Public booking response and time zones

Booking objects contain the public appointment, guest, status, notes, and timestamp fields plus business_timezone. Times are ISO-8601 instants; format them in the viewer's time zone while preserving the returned business zone for schedule context. Internal confirmation IDs, provider calendar-event IDs, and database range columns are omitted.

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

响应（`200 OK`）：

{

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

What belongs in the public developer API

These routes accept a scoped Chirps API key and enforce its workspace boundary. Dashboard-only billing/OAuth routes, browser widget callbacks, provider webhooks, cron jobs, and internal MCP routes are intentionally excluded.

Assistants

Knowledge and training

Widget, artifacts and connectors

Conversations, leads and bookings

Telephony and account