开发者

Wisebird API:将客户聊天连接到您的系统

REST API、Webhook 和 MCP,用于对接您的系统

阅读完整说明

Wisebird 开发者 API 是一组 REST API 和 Webhook,用于拉取聊天、搜索、发送消息、管理企业的标签和成员,使用每家企业独立的 API key 和 Bearer 认证,支持 Idempotency-Key、带签名和 test event 的 Webhook、Try it 式 sandbox、MCP,以及用于管理多家企业的 partner API。

开始使用 API 需要什么

  1. 为每个商家创建 API key在应用的商家设置中创建,请立即复制保存,key 只完整显示一次
  2. 以 Bearer 方式发送 key每个请求都放在 Authorization header 中,不得放入 query string,并使用 HTTPS
  3. 先在 sandbox 测试应用内的 Try it 模式向测试商家发送请求,之后再使用真实商家的 key

示例 · 拉取聊天列表

curl https://wisebird.cloud/external/v1/conversations?status=open&limit=20 \
  -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx"

有哪些 endpoint

所有 endpoint 都在同一个 host 下并返回 JSON,含 schema 的完整文档在应用内

群组Method 与 path用来做什么
ConversationsGET /external/v1/conversations聊天列表,可按状态、渠道、标签或负责人筛选
GET /external/v1/conversations/{id}单条聊天详情,含消息和客户卡片
GET /external/v1/conversations/search按消息内容、客户姓名或电话搜索聊天
POST /external/v1/conversations/{id}/messages向客户发送消息,支持 text、image、video、audio、file
TagsGET, POST /external/v1/tags读取和创建标签,为聊天添加或移除标签
MembersGET /external/v1/members成员名单与角色,用于分配聊天
WebhooksGET, POST /external/v1/webhooks注册 endpoint,选择 event,发送 test event

示例 · 带 Idempotency-Key 发送消息

curl -X POST https://wisebird.cloud/external/v1/conversations/cnv_123/messages \
  -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 7f3c2a1e-order-4512-confirm" \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"已收到订单 #4512,将在 2 个工作日内发货。"}'

# 发送附件:将 type 改为 image | video | audio | file 并传入文件 url
# -d '{"type":"image","url":"https://example.com/receipt.png","caption":"这是您的收据"}'
  • Idempotency-Key每条消息的唯一值,用同一个 key 重发会得到相同结果,且不会重复发给客户
  • 渠道限制文件类型和大小取决于渠道
  • Messenger商家主动发起的消息有 24 小时限制

Webhook 会通知什么,如何验证签名?

注册 endpoint、选择 event,然后点击发送 test event 即可立即测试,无需等待真实聊天

Eventv1v2创建于
message.received有有客户通过任意渠道发送消息
message.sent有有AI 或团队发出消息,payload 中标明发送者
conversation.handoff有有AI 把聊天转交团队,附上原因和摘要
conversation.assigned没有有聊天已分配给成员
conversation.tagged没有有标签已添加到聊天或从聊天移除
lead.created没有有线索表单或 AI 将新线索加入管道
order.created没有有记录来自聊天的销售或订单

v2 在 payload 中增加了 event 和字段,v1 仍可使用,新 endpoint 建议用 v2

示例 · 您的 endpoint 将收到的 payload 和签名 header

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Wisebird-Event: conversation.handoff
X-Wisebird-Signature: t=1760600000,v1=5f1c…e2a9
X-Wisebird-Delivery: evt_01HZX…

{"id":"evt_01HZX…","version":"v2","type":"conversation.handoff",
 "business_id":"biz_42","created_at":"2026-10-16T09:30:00+07:00",
 "data":{"conversation_id":"cnv_123","channel":"line","reason":"customer_requested_human",
         "summary":"客户在疗程前询问炎症性痘痘,需医生评估"}}

# 校验签名: HMAC-SHA256(secret, t + "." + raw_body) 然后以 constant-time 方式与 v1 比较
# 若 t 与当前时间的差超过您设定的范围则拒绝,以防重放

MCP、sandbox 与 partner API

  • Try it 式 Sandbox应用内的开发者页面向测试商家发送请求并即时显示结果,不影响真实客户
  • MCP让外部 AI 工具在同一 API key 的权限下把 Wisebird 作为 tool 调用
  • partner API一个 key 管理多个商家,使用共享钱包的额度,适用于合作伙伴
  • 权限和 log每个请求都记录在 activity log 中,可在设置页立即撤销 key

示例 · partner API 指定要管理的企业

curl https://wisebird.cloud/external/v1/conversations?status=open \
  -H "Authorization: Bearer wb_partner_xxxxxxxxxxxxxxxx" \
  -H "X-Wisebird-Business: biz_42"

相关页面

合作伙伴计划

管理多家企业、共享额度钱包和中央套餐

查看详情

安全与 PDPA

数据存放在泰国、角色权限和 activity log

查看详情

CRM / 销售管道

通知规则推送到您的 LINE 群、Telegram、Discord 或 webhook

查看通知

常见问题

在哪里创建 Wisebird API key

在应用内商家设置页创建,key 仅在创建时完整显示一次,请立即复制保存。丢失后可撤销并重新创建

可以在 query string 中传 API key 吗

不可以。只能通过 HTTPS 在 Authorization header 中以 Bearer 方式传 key,query string 中的 key 会被拒绝,因为 URL 常被记录在 log 中

如果不小心重复发送消息会怎样?

在 Idempotency-Key header 中放入每条消息唯一的值,用相同 key 重发会得到相同结果且不会重复发给客户,适合 retry

如何验证 Webhook 确实来自 Wisebird?

每个 event 的 header 中都带有签名,由 endpoint 的 secret 计算得出。请用原始 body 计算并比对后再处理,可发送 test event 测试。

有不影响真实客户的 sandbox 可测试吗

有。应用开发者页面的 Try it 模式会向测试商家发请求,不会触达真实客户,还可发送带真实签名的 Webhook test event

MCP 在 Wisebird 中有什么用?

让外部 AI 工具在同一 API key 的权限下把 Wisebird 的能力作为 tool 调用,如搜索聊天、获取客户卡片、发送消息

免费套餐即可创建第一个 API key

注册、对接渠道,然后在 sandbox 中发出第一个请求