快速开始 · PushMsg 文档

本页使用 CRM 专用接口发送“新客户跟进通知”。准备好业务 API Key、API Secret、已授权的接收人 OpenID 和一条实际业务通知后，即可完成接入。

1. 领取业务 Key 和 Secret

请管理员在管理控制台创建接入应用，并为该应用授权 xianbao 公众号通道。创建后复制一次性展示的 Key 和 Secret，保存到 CRM 服务端；管理员密钥用于后台管理。

请求同时携带 Key 和 Secret；Key 也可通过 Bearer 提供：

X-API-Key: YOUR_CRM_API_KEY
X-API-Secret: YOUR_CRM_API_SECRET

Authorization: Bearer YOUR_CRM_API_KEY
X-API-Secret: YOUR_CRM_API_SECRET

Key 和 Secret 代表当前调用系统身份。系统须同时具备 xianbao 通道权限和接收人 OpenID 授权，才可使用该渠道的 CRM 或通用消息接口；业务凭据没有管理员权限。

2. 获取接收人的 OpenID

让希望接收通知的人员，在本人微信内打开 OpenID 获取页面，点击“获取我的 OpenID”，返回页面后复制。

管理员进入对应调用系统的“接收人”管理，将该 OpenID 绑定到该系统及 xianbao 通道，并启用。再将其与 CRM 中的员工或负责人账号绑定。未在 PushMsg 后台授权的 OpenID 返回 403 RECIPIENT_FORBIDDEN；新系统未添加接收人时不能推送。请求中的 openId 是通知接收人；客户名称、电话等字段来自需要提醒的 CRM 客户记录。接收人需已关注目标公众号并满足微信的消息接收条件。

完整说明见 OpenID 获取。

3. 提交第一条通知

将以下 JSON 保存为 crm-message.json，替换 openId、业务请求标识和客户字段。每条新通知使用唯一 requestId；同一通知的网络重试保留原值及原内容。

{
  "requestId": "crm-customer-C0001-followup-001",
  "openId": "YOUR_OPENID",
  "customerName": "测试客户",
  "customerType": "潜在客户",
  "customerSource": "CRM录入",
  "customerPhone": "13800000000",
  "markedAt": "2026-10-26 11:00",
  "url": "https://crm.example.com/customers/C0001"
}

markedAt 必须是有效的北京时间，格式为 yyyy-MM-dd HH:mm。url 是可选的 CRM 详情链接，没有详情页时可省略该字段。

在业务系统服务端执行：

export CRM_PUSH_API_KEY='YOUR_CRM_API_KEY'
export CRM_PUSH_API_SECRET='YOUR_CRM_API_SECRET'

curl --fail-with-body \
  'https://openid.xianboss.com/api/v1/crm/push' \
  -H "X-API-Key: $CRM_PUSH_API_KEY" \
  -H "X-API-Secret: $CRM_PUSH_API_SECRET" \
  -H 'Content-Type: application/json' \
  --data-binary @crm-message.json

请求成功入队后返回 HTTP 202：

{
  "id": "11111111-2222-4333-8444-555555555555",
  "status": "PENDING",
  "duplicate": false
}

保存返回的 id，以便跟踪结果。

4. 查询发送结果

使用提交消息时的同一业务应用密钥查询：

curl --fail-with-body \
  'https://openid.xianboss.com/api/v1/crm/messages/11111111-2222-4333-8444-555555555555' \
  -H "X-API-Key: $CRM_PUSH_API_KEY" \
  -H "X-API-Secret: $CRM_PUSH_API_SECRET"

状态	接下来怎么做
PENDING / PROCESSING	稍后继续查询
RETRY	等待服务自动重试，保留原任务
SENT	微信已接受请求，可在接收人微信中确认展示
FAILED	查看 `lastError`，修正原因后由管理员处理
UNKNOWN	先核实实际发送情况，再决定是否人工重试

5. 把重试规则接入 CRM

提交前保存本次业务事件、requestId 和请求内容。
HTTP 超时或连接中断时，使用相同 requestId 和相同内容再次提交。
相同请求会返回 HTTP 200、原任务 ID 和 duplicate:true。
同一个 requestId 配上不同内容会返回 HTTP 409，错误码 IDEMPOTENCY_CONFLICT。
新业务通知生成新标识，队列中的旧任务继续通过原 ID 查询。

下一步可阅读 CRM 字段与错误码，或下载 OpenAPI 定义导入 API 工具。