合作伙伴计划
管理多家企业、共享额度钱包和中央套餐
查看详情示例 · 拉取聊天列表
curl https://wisebird.cloud/external/v1/conversations?status=open&limit=20 \ -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx"
所有 endpoint 都在同一个 host 下并返回 JSON,含 schema 的完整文档在应用内
| 群组 | Method 与 path | 用来做什么 |
|---|---|---|
| Conversations | GET /external/v1/conversations | 聊天列表,可按状态、渠道、标签或负责人筛选 |
| GET /external/v1/conversations/{id} | 单条聊天详情,含消息和客户卡片 | |
| GET /external/v1/conversations/search | 按消息内容、客户姓名或电话搜索聊天 | |
| POST /external/v1/conversations/{id}/messages | 向客户发送消息,支持 text、image、video、audio、file | |
| Tags | GET, POST /external/v1/tags | 读取和创建标签,为聊天添加或移除标签 |
| Members | GET /external/v1/members | 成员名单与角色,用于分配聊天 |
| Webhooks | GET, 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":"这是您的收据"}'
注册 endpoint、选择 event,然后点击发送 test event 即可立即测试,无需等待真实聊天
| Event | v1 | v2 | 创建于 |
|---|---|---|---|
| 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 与当前时间的差超过您设定的范围则拒绝,以防重放
示例 · partner API 指定要管理的企业
curl https://wisebird.cloud/external/v1/conversations?status=open \ -H "Authorization: Bearer wb_partner_xxxxxxxxxxxxxxxx" \ -H "X-Wisebird-Business: biz_42"
在应用内商家设置页创建,key 仅在创建时完整显示一次,请立即复制保存。丢失后可撤销并重新创建
不可以。只能通过 HTTPS 在 Authorization header 中以 Bearer 方式传 key,query string 中的 key 会被拒绝,因为 URL 常被记录在 log 中
在 Idempotency-Key header 中放入每条消息唯一的值,用相同 key 重发会得到相同结果且不会重复发给客户,适合 retry
每个 event 的 header 中都带有签名,由 endpoint 的 secret 计算得出。请用原始 body 计算并比对后再处理,可发送 test event 测试。
有。应用开发者页面的 Try it 模式会向测试商家发请求,不会触达真实客户,还可发送带真实签名的 Webhook test event
让外部 AI 工具在同一 API key 的权限下把 Wisebird 的能力作为 tool 调用,如搜索聊天、获取客户卡片、发送消息
注册、对接渠道,然后在 sandbox 中发出第一个请求