公开 API Beta

找出需要处理的对话

可按 awaitingReply、unread、unassigned、assigneeId、agentGroupId、snoozed、priority 或 tagIds 筛选。等待回复会忽略内部备注；未读针对的是已认证的同事本人。未分配表示没有个人负责人，即使已分配给某个团队。标签匹配所提供的任意 ID。

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

可按 waitingSince、lastMessageAt、createdAt 或业务优先级排序，方向为 asc 或 desc，ID 用于决定并列顺序。省略筛选条件时保持 compact=false 和 snoozed=any。REST 的 tagIds 接受逗号分隔的 ID；MCP 还接受数组。waitingSince 从上次回复之后的第一条收到的消息开始计算；后续消息和内部备注不会重置它。即使没有收到 Webhook，也请定期运行这种等待队列扫描，让旧会话重新浮现。

无需重读收件箱即可追上进度

使用 GET /api/v1/sync 并授予 conversations:read。持久变更流包含对话变更、标签、消息、联系人属性、记忆和删除记录。每种负载还需要各自的读取权限：消息正文需要 messages:read，记忆需要 contact-memory:read。受限的凭据只会收到其被允许的渠道。

1. 不带游标开始，沿着 nextCursor 一直读取到 hasMore 为 false，然后保存该游标。
2. 读取当前的对话和联系人列表，以及初始状态所需的任何历史记录。
3. 从保存的游标开始重放，捕获读取期间发生的变更。处理完每一页后，保存 nextCursor。

按事件 id 去重：重放至少投递一次，因此下游操作需要自己的防重复机制。不带游标的请求只覆盖最近一小时，并非完整快照。事件保留 30 天；HTTP 410 resync_required 表示需要重新初始化。扩大权限范围或渠道访问后也需要重新初始化。limit 最大为 100，maxBodyChars 最大为 10,000（默认 500）。设置 compact=true 可获得上限为 200 个字符的消息 textPreview/textTruncated 字段，而不是 body/bodyTruncated。Webhook 可以唤醒智能体；即使没有 Webhook 订阅或 Webhook 投递积压，变更流依然可用。

检查只做一次，结果共享

在重复调查之前，先读取 list_conversation_checks（GET /api/v1/conversations/{conversationId}/checks）。使用 record_conversation_check（PUT 到同一路径）保存结果，提供 key、result、checkedBy，以及可选的 reference（卡片 ID 或 URL）。例如：key=product-version、result=Shopstar Go verified、checkedBy=Engineer、reference=card-X。Sonny 会记录已认证的 actorId 和 checkedAt 时间戳。重复使用某个 key 只会替换该项检查；这是当前状态，而不是历史日志。读取需要 conversations:read，写入需要 conversations:write，二者都限定在对话所属的渠道。这些调用不会发送回复，也不会把卖家标记为已回复。

批量分配和更新工作

通过 GET /api/v1/members and /teams（members:read）查看活跃的、可分配的同事和团队。响应包含在线状态和实际的渠道访问权限，但不含邮箱地址。使用 conversations:write 更改 status、priority、assigneeId、agentGroupId、snoozedUntil、snoozedUntilReply、addTagIds 或 removeTagIds。

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

轮流分配会选择一位在线、且能访问该对话渠道的团队成员。没有符合条件的成员时，单个更新返回 409，批量中的对应项失败。每个批量最多接受 100 个不重复的 ID，并对每个对话原子地应用一次补丁。请检查每一个 { id, ok, error? } 结果；部分项可能会失败。批量操作按当前基于请求的频率限制计算，不按项目数量加权计费。

与 Sonny AI 共享客户信息

使用 contact-memory:read/write 列出、保存和删除联系人记忆。需同时提供 contactId 和一个可访问的 sourceId；该联系人必须在此来源上有对话。保存的事实与应用内使用相同的校验、去重处理和限制，并记录为手动记忆。

在 /api/v1/properties 读取属性定义，在 /api/v1/contacts/{contactId}/properties 读取或设置属性值。MCP 提供 list_properties、get_contact_properties 和 set_contact_property。这些操作需要 contacts:read/write 以及全部渠道的访问权限。只设置 propertyId 或 propertyName 其中之一，值为字符串，或用 null 清除。文本、数字、URL、日期和选项值都会根据字段定义进行校验。

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

属性筛选匹配精确存储的字符串；多个属性必须全部匹配。通过 API 写入的值会在 Co-Pilot 和自动回复中标注为 API 数据。现有的已验证客户和来源规则依然适用。普通的手动内部字段值仍不会纳入此 AI 上下文。

读取与团队相同的报表

授予 reporting:read 后调用 GET /api/v1/reporting/{kind}。报表类型有 overview、volume、response-times、agents、sources、tags、csat、ai、knowledge、leads 和 online-hours。overview 综合了数量、响应时间和满意度。筛选条件包括 period（1–365 天，默认 30）、成对的 from/to 日期（to 不包含在内）、granularity（day/month）、source、assigneeId 和 tagId。source 接受 all、all-chat、all-email、website:{id} 或 email:{id}。

报表使用与仪表板相同的查询和当前的访问检查。knowledge 报表按日期和被允许的渠道统计，不受所选来源、负责人或标签影响。online-hours 衡量可访问同事在工作区中的在线时长；其中的对话数量仍按渠道限定。现有的 /csat 端点保留单独的 csat:read 权限范围，统计对象可能不同。

在回复或内部备注中发送文件

授予 attachments:write，并为某个对话上传最大 25 MB 的文件。POST /api/v1/attachments 接受 multipart 格式的 file 和 conversationId 字段。响应包含 id 和 expiresAt。在一小时内，最多可将 10 个 attachmentIds 传给一条回复或备注。每次上传都绑定到你的用户和该对话，且只能使用一次。未使用的上传会在过期后清理。

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

回复需要 messages:send；内部备注需要 messages:write，且永远不会发给客户。支持只含附件的消息。邮件回复会在邮件大小限制内附上文件，其余文件则提供下载链接；离线聊天邮件会包含文件链接。只要附件还在，邮件中的链接就一直可用，收件人可以稍后打开。转发邮件会共享这些文件的访问权限。请检查 emailDeliveryStatus 了解投递失败情况。

经授权的消息读取包含 downloadUrl、downloadExpiresAt、aiStatus、aiDescription 和 aiExtractedText，链接视频（Loom、Vimeo 等）还包含 videoTranscripts。下载链接有效期为 15 分钟；需要新链接时请重新读取消息。新的 API/MCP 上传使用私有存储。较早的附件仍为公开，并标记为 access=legacy_public：其原始 URL 不会过期。当工作区开通了 Sonny AI 时，读取消息会触发读取其中的图片。图片识别和视频文字稿会在消息到达后不久完成：若仍有任务在运行，响应会以 readsInProgress 开头，其中的 nextStep 给出了应调用的确切操作。传入 waitSeconds（最多 30）可在一次请求中等待它们完成。面向客户的聊天组件和实时消息永远不会包含提取内容或文字稿。