开发者

Sonny MCP Beta

将兼容 MCP 的 AI 助手——Claude，以及任何支持 Model Context Protocol 的客户端——连接到你的工作区，享有与公开 API 相同的权限范围和边界。

快速入门

01
将 Sonny 添加到 Claude
在 Claude 或 Cowork 中添加一个自定义连接器，URL 为 https://www.usesonny.com/api/mcp。Sonny 支持客户端自动注册，因此无需复制客户端 ID 或密钥。
02
批准工作区访问
Claude 会在你的浏览器中打开 Sonny。登录，查看请求的权限，并选择要连接的工作区。采用 PKCE 的 OAuth 2.1 会将由此产生的访问令牌和刷新令牌限定在这次批准的范围内。
03
让你的助手使用 Sonny
工具会自我描述，所以像“列出我进行中的对话”这样的提示就足够了。助手能看出哪些工具是只读的、哪些是破坏性的，因此好的客户端在做出任何更改前都会先询问你。

Claude Code

claude mcp add --transport http sonny https://www.usesonny.com/api/mcp

JSON 客户端配置

{
  "mcpServers": {
    "sonny": {
      "url": "https://www.usesonny.com/api/mcp"
    }
  }
}

API 密钥兼容

如果某个客户端无法完成 OAuth，请在“设置 → 开发者”中创建一个限定权限的密钥，并将其作为 Authorization Bearer 请求头发送。API 密钥对服务器间调用和旧版客户端依然完全支持。

"Authorization": "Bearer sonny_your_key"

Sonny 如何确保工具调用安全

一个工作区，选定的权限范围: 每次调用都在 OAuth 授权时选择的工作区，或 API 密钥所属的工作区内运行。只有当凭据具备所需权限范围时，工具才能使用。
如实的工具标注: 只读工具标记为只读；更新和删除类工具标记为破坏性，让你的客户端在执行前先确认。
同样的业务规则: 工具运行的正是公开 API 所运行的工作流——审计历史、通知和 Webhook 的表现都与同事亲手操作时一样。

让助手只在一个收件箱内工作

API 密钥上设置的指定渠道会在每次工具调用中自动强制执行。API 密钥和 OAuth 连接也会遵循所连接同事当前的渠道访问权限。对于 OAuth 连接或拥有全部渠道访问权限的密钥，工作区通常包含多个来源——每个产品或品牌一个。让你的助手先调用一次 list_sources 查看它们，再把 sourceId 传给 list_conversations，这样关于某个产品的问题只会返回该产品的对话。每个对话也都带有自己的 sourceId，结果可以核对。

运行低成本的客服循环

发现变更：先用持久的 sync 变更流完成初始化，每处理完一页就保存 nextCursor，并对事件 ID 去重。挑选工作时，调用 list_conversations，传入 sourceId、awaitingReply: true、snoozed: "false" 和 compact: true。内部备注不会掩盖未回复的客户消息。
只读取新文字：对于每个有变更的对话，调用 list_messages，在 after 中传入你最后一条消息的 ID 或 ISO 时间戳，并设置 includeHtml: false，除非确实需要邮件的 HTML。
等待图片和视频：当 list_messages 返回 readsInProgress 时，执行其 nextStep 中给出的调用。其中的 waitSeconds 会让响应等到图片识别和视频文字稿就绪，因此无需自行等待。
加载客户信息：get_conversation 会返回 identityVerified、签名的 verifiedTraits，以及对话的来源页面和客户端上下文。当它包含 contact.id 时，把该 ID 传给 list_conversations 即可加载该客户之前的对话。
按需唤醒：为 message.created 设置按来源筛选的 Webhook 来立即唤醒智能体，然后通过 sync 追上进度。持久变更流独立于 Webhook 投递运行。使用拥有全部渠道权限的凭据创建 Webhook 并限定其来源 ID；智能体运行时则继续使用限定来源的凭据。

工具目录

每一项公开 API 操作都提供对应的工具。每个工具旁边都列出了所需的权限范围。

get_connection_info: Read connection access; conversations:read
get_conversation_context: Read support context; conversations:read
list_conversation_checks: Read conversation checks; conversations:read
record_conversation_check: Record a conversation check; conversations:write
get_status: Check Sonny status; conversations:read
create_conversation: Create a conversation from a form; conversations:write
upload_attachment: Upload a message attachment; attachments:write
list_properties: List custom properties; contacts:read
get_contact_properties: Read contact properties; contacts:read
set_contact_property: Set a contact property; contacts:write
list_contact_memories: Read customer memories; contact-memory:read
create_contact_memory: Save a customer memory; contact-memory:write
delete_contact_memory: Remove a customer memory; contact-memory:write
get_report: Read a support report; reporting:read
sync: Read workspace changes; conversations:read
batch_update_conversations: Update conversations in a batch; conversations:write
list_members: List members; members:read
list_teams: List teams; members:read
list_tags: List tags; tags:read
create_tag: Create a tag; tags:write
get_tag: Get a tag; tags:read
update_tag: Update a tag; tags:write
delete_tag: Delete a tag; tags:write
add_conversation_tag: Add a conversation tag; conversations:write
remove_conversation_tag: Remove a conversation tag; conversations:write
list_contacts: List contacts; contacts:read
create_contact: Create a contact; contacts:write
get_contact: Get a contact; contacts:read
update_contact: Update a contact; contacts:write
archive_contact: Archive a contact; contacts:write
erase_contact: Permanently erase a contact; contacts:write
list_channels: List conversation channels; conversations:read
list_sources: List sources; conversations:read
list_conversations: List conversations; conversations:read
get_conversation: Get a conversation; conversations:read
update_conversation: Update a conversation; conversations:write
list_messages: List messages; messages:read
create_internal_note: Create an internal note; messages:write
edit_message: Edit a sent reply; messages:send
send_message: Send a reply to the customer; messages:send
list_webhooks: List webhook endpoints; webhooks:read
create_webhook: Create a webhook endpoint; webhooks:write
list_webhook_events: List webhook event types; webhooks:read
update_webhook: Update a webhook endpoint; webhooks:write
delete_webhook: Delete a webhook endpoint; webhooks:write
test_webhook: Queue a test event; webhooks:write
list_webhook_deliveries: List webhook deliveries; webhooks:read
retry_webhook_delivery: Retry a failed delivery; webhooks:write
list_kb_articles: List knowledge base articles; kb:read
create_kb_article: Create a knowledge base article; kb:write
get_kb_article: Get a knowledge base article; kb:read
update_kb_article: Update a knowledge base article; kb:write
delete_kb_article: Delete a knowledge base article; kb:write
list_kb_categories: List knowledge base categories; kb:read
create_kb_category: Create a knowledge base category; kb:write
update_kb_category: Update a knowledge base category; kb:write
delete_kb_category: Delete a knowledge base category; kb:write
get_csat_summary: Get CSAT scores; csat:read
list_csat_ratings: List CSAT ratings; csat:read
get_conversation_csat: Get a conversation's CSAT rating; csat:read
reorder_kb_articles: Reorder knowledge base articles; kb:write
upsert_kb_article: Sync a knowledge base article; kb:write
reorder_kb_categories: Reorder knowledge base categories; kb:write
upsert_kb_category: Sync a knowledge base category; kb:write
get_kb_category: Get a knowledge base category; kb:read
get_help_center: Get help center settings; kb:read
update_help_center: Update help center settings; kb:write
upload_kb_media: Upload a help center image; kb:write
list_kb_audiences: List audiences; kb:read
create_kb_audience: Create audience; kb:write
update_kb_audience: Update audience; kb:write
delete_kb_audience: Delete audience; kb:write

智能体工作流

分拣、处理，并保持同步

REST 和 MCP 共用相同的权限和工作流。凭据只能缩小你当前的渠道访问范围；从你的成员身份中移除某个渠道，也会把它从你的集成中移除。

找出需要处理的对话

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

list_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，也请定期运行这种等待队列扫描，让旧会话重新浮现。

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

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

不带游标开始，沿着 nextCursor 一直读取到 hasMore 为 false，然后保存该游标。
读取当前的对话和联系人列表，以及初始状态所需的任何历史记录。
从保存的游标开始重放，捕获读取期间发生的变更。处理完每一页后，保存 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，二者都限定在对话所属的渠道。这些调用不会发送回复，也不会把卖家标记为已回复。

批量分配和更新工作

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

batch_update_conversations({
  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、日期和选项值都会根据字段定义进行校验。

set_contact_property({ contactId: "contact_1", propertyName: "Plan", value: "Pro" })
list_contacts({ property: { Plan: "Pro" } })

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

读取与团队相同的报表

授予 reporting:read 后调用 get_report({ kind, filters })。报表类型有 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 的文件。upload_attachment 接受 conversationId、fileName、contentType 和 dataBase64。响应包含 id 和 expiresAt。在一小时内，最多可将 10 个 attachmentIds 传给一条回复或备注。每次上传都绑定到你的用户和该对话，且只能使用一次。未使用的上传会在过期后清理。

send_message({ conversationId: "conversation_1", 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）可在一次请求中等待它们完成。面向客户的聊天组件和实时消息永远不会包含提取内容或文字稿。

查看完整的请求与响应约定

知识库

从外部来源同步

使用稳定的外部 ID 同步文章和分类，导入 Markdown 或 HTML，上传图片，设置排序，并管理读者受众。重复执行 upsert 会更新已有内容。

选择你渠道的 sourceId，并授予 kb:read 和 kb:write。如需可选的来源查询，list_sources 还需要 conversations:read。
先创建分类，再将文章作为草稿同步。发布前检查其格式和访问权限。
配置帮助中心访问权限、发布，并测试读者视图。之后的更新请使用分页和稳定的外部 ID。

按照完整的 MCP 同步教程操作

管理客户受众

根据已验证的客户特征创建群组，并应用到帮助中心、分类或文章。所有继承的限制都必须满足。API 和 MCP 凭据在其权限范围内以员工身份操作；请预览并测试真实的客户会话，以检查读者访问权限。

设置并测试帮助中心受众