探马OpenAPI
  1. 消息推送
探马OpenAPI
  • 开发指南
    • 开发前必读
    • 对接地址说明
    • 调用说明
    • 接口鉴权说明
    • 对接测试
      POST
  • 基础接口
    • 获取客户id
      POST
    • 获取员工id
      POST
    • 自动开启探马账号及绑定互通账号
      POST
    • 代开发应用id明文转密文
      POST
  • 客户设置
    • 查询企业字段
      POST
    • 查询客户字段
      POST
    • 按时间段消除积分(已废弃)
      POST
  • 消息推送
    • 概述
    • 消息推送数据格式
    • 消息推送类型
      • 推送地址注册回调推送
      • 企微客户新增推送
      • 企微客户修改推送
      • 企微客户删除消息推送
      • 企微客户跟进数据变更推送
      • 积分/评分变更消息推送
      • 客户
        • 新增探马客户推送
        • 修改探马客户推送
        • 删除探马客户推送
        • 新增客户联系人消息推送
        • 编辑客户联系人消息推送
        • 删除客户联系人消息推送
      • 订单
        • 新增探马订单推送
        • 修改探马订单推送
      • 标签
        • 客户标签变更推送
        • 企微标签变更推送
        • 内容标签变更推送
        • 企微个人标签变更推送
      • 合同
        • 合同变更推送
      • 商机
        • 客户商机变更推送
      • 企业
        • 企业信息变更推送
        • 推送字段映射
        • 查询已映射的推送字段
      • 通话记录
        • 通话记录推送
      • 跟进记录
        • 写跟进记录推送
    • 推送注册接口
      POST
  • 客户&线索&待分配
    • 客户查询
      • 高级筛选接口(新版)
      • 查询没有群聊的客户
      • 客户高级筛选接口
    • 客户导入
      • 对接前必读
      • 字段映射
        • 客户字段映射
      • 个人线索导入
      • 个人待分配客户导入
      • 个人客户导入
      • 企业线索导入
      • 企业待分配客户导入
      • 企业客户导入
    • 客户
      • 客户数据
        • 必读说明
        • 字段映射
          • 列出客户数据字段列表
          • 映射外部CRM客户数据字段
        • 客户详情
          • 按企微客户id获取详情
          • 按新增时间查询企微客户数据
          • 按详情字段更新时间查询企微客户数据
        • 客户标签
          • 列出企微客户企业标签树
          • 按企微客户id列出客户企业标签(批量)
          • 更新企微客户企业标签
        • 客户跟进
          • 获取指定企微客户的跟进数据
          • 创建企微客户的跟进
          • 删除企微客户的跟进
          • 查询客户跟进记录
        • 客户通话
          • 查询电销手机通话记录
        • 客户文件
          • 客户文件查询接口
          • 客户文件上传
      • 客户聊天
        • 基于时间段内聊天数统计
      • 已跟进客户数据
        • 列出销售跟进的客户
        • 按跟进关系创建时间升序列出已跟进的客户
        • 按跟进关系字段更新时间升序列出已跟进的客户
        • 更新已跟进客户昵称
        • 更新已跟进客户头像
        • 更新已跟进客户备注名
        • 更新已跟进客户字段
        • 更新已跟进客户标签
        • 列出指定客户跟进内容
        • 写客户跟进
        • 跟进记录批量导入
    • 线索&待分配
      • 按创建时间列出线索&待分配客户
      • 按更新时间列出线索&待分配客户
      • 获取线索&待分配客户详情
      • 更新线索&待分配客户字段
      • 编辑 线索&待分配客户 标签
      • 列出指定线索&待分配客户跟进内容
      • 写线索&待分配客户跟进
    • 商机
      • 查询商机配置
      • 获取商机列表
      • 创建客户商机
      • 修改客户商机
      • 查询客户商机
      • 获取客户商机详情
      • 获取探马商品列表
    • 个人客户转企业客户
      • 个人客户转企业客户
    • 企业客户联系人
      • 接口须知
      • 查询联系人
      • 创建联系人
      • 修改联系人
      • 删除联系人
    • 客户旅程
      • 查询旅程
    • 客户操作
      • 修改客户
      • 合并客户
      • 转移客户
      • 变更跟进人
      • 更新企微客户详情(批量)
      • 修改客户积分
      • 添加协作人
    • 按企微员工id列出企微好友客户详情
      POST
  • 公海
    • 接口调用须知
    • 公海客户高级筛选列表
    • 公海-转出记录列表
    • 列出客户数据字段列表
    • 列出企业字段列表
    • 查询公海客户库
    • 公海-个人客户批量导入
    • 公海-企业客户批量导入
    • 公海-个人客户批量更新
    • 公海-企业客户批量更新
    • 查询公海销售对应客户的联系人信息
    • 查询错误信息
  • 企微组织架构
    • 对接前必读
    • 员工
      • 创建员工
      • 更新员工
      • 读取员工
      • 启用/禁用员工
      • 探马后台登录权限
      • 删除员工
    • 部门
      • 创建部门
      • 编辑部门
      • 获取部门信息
    • 获取组织架构信息
  • 企微标签库
    • 标签树
    • 编辑标签组
    • 删除标签组
    • 添加标签
    • 编辑标签
    • 删除标签
  • 企业
    • 获取企业信息
    • 创建企业
  • 合同
    • 必读说明
    • 保存合同字段映射
    • 获取合同和回款单自定义字段
    • 查询配置的合同映射字段
    • 查询回款单列表
    • 合同扩展字段
    • 新建合同
    • 修改合同
    • 查询销售所有部门
    • 查询客户合同关联订单
    • 查询指定客户合同信息
    • 作废/删除合同
    • 查询合同列表
    • 获取合同详情
  • 电商平台
    • 商城
      • H5商城
        • 概述
        • 注册商城
        • 导入商城商品类别
        • 导入商城商品
    • 订单
      • 概述
      • 第三方订单
        • 获取订单自定义字段
        • 自定义字段映射
        • 查询订单列表
        • 查询订单详情
        • 创建/更新订单
        • 批量创建/更新订单
        • 批量创建/更新订单结果查询接口
      • 探马订单
        • 查询探马商城订单详情
        • 查询探马商城订单列表
        • 获取探马商城订单自定义字段
        • 修改探马商城订单状态
  • 营销
    • 营销内容
      • 表单
        • 获取表单收集明细
      • 自定义
        • 创建自定义内容
        • 更新自定义内容
        • 删除自定义内容
        • 获取自定义内容详情
        • 营销内容标签查询
      • 获取营销内容分类
      • 获取营销内容及明细
      • 获取营销内容-内容标签
      • 获取营销内容-员工分享明细
    • 企微获客
      • 获取企微获客所有表单
      • 获取兑换码手机号
    • 渠道活码
      • 获取渠道活码分组-按部门查询
      • 渠道活码创建接口
      • 渠道活码更新接口
      • 获取渠道活码详情
      • 获取渠道活码分组
      • 获取渠道活码列表
      • 获取渠道活码分析数据
    • 渠道活码 Copy
      • 获取渠道活码分组-按部门查询
      • 渠道活码创建接口
      • 渠道活码更新接口
      • 获取渠道活码详情
      • 获取渠道活码分组
      • 获取渠道活码列表
      • 获取渠道活码分析数据
    • 一客一码
      • 批量删除
      • 查询/创建接口
    • 问答库
      • 层级展示分组
      • 创建问答库分组
      • 编辑分组
      • 删除分组
      • 新建问答
      • 删除问答
      • 编辑问答
      • 问答详情
      • 编辑关键词
      • 删除关键词
      • 新建关键词
      • 查询公司下所有关键词
      • 文件上传
    • 获客活动
      • 获取获客活动参与记录
  • 数据统计
    • 获取微信跟进统计数据明细
    • 获取内容营销员工统计数据明细
  • 内容访客
    • 按内容访问时间列出访客事件信息
  • 电销手机
    • 一键拨号
  • SOP任务
    • 接口说明
    • 客户SOP
      • 客户SOP-群发活动SOP
      • 客户SOP-定期提醒SOP
      • 客户SOP-新增好友SOP
      • 客户SOP-群发助手SOP
      • 创建添加客户任务(分配线索/待分配客户)
    • 群SOP
      • 创建手动发送SOP
      • 创建群发助手SOP
      • 创建群群发任务
      • 创建客户群发任务
    • 跟进客户SOP
      • 跟进客户任务-客户跟进
    • 朋友圈运营
      • 朋友圈任务执行详情
      • 创建朋友圈任务
      • 删除/中止朋友圈任务
      • 查询朋友圈列表
      • 查询朋友圈列表(边城体育)
    • 客户群群发
      • 客户群群发任务执行详情
      • 客户群群发任务列表
    • 客户群发
      • 群发任务执行详情
      • 客户群发任务列表
    • 分页查询员工信息
    • SOP任务-查询销售跟进客户关系
    • 查询标签树
    • 查询营销内容明细数据
    • 查询SOP任务中所需客户字段
    • 查询群列表
    • 查询群标签列表
    • SOP素材上传接口
    • 获取群成员列表
  • 群发消息
    • 创建客户群发消息
    • 上传文件
  • 管控
    • 敏感动作
      • 敏感动作列表接口
  • 工单
    • 工单列表
    • 工单详情
    • 模板列表
    • 创建工单
  • 素材
    • 文件上传
  • 应用通知
    • 应用通知
  • 附录
    • 全局参考文档
    • 前端SDK文档
  • 群数据
    • 群画像
    • 更新群字段
  • 店主活码
    • 店主活码state转换活码名接口
  • 通话列表
    • 语音和通话转文本api
  1. 消息推送

消息推送数据格式

推送格式约定#

推送数据格式#

因无法保证各公司推送接收端口使用加密,为防止数据泄漏。推送的消息体将使用完全加密。加密方式为AES加密(AES/CTR/PKCS5Padding),加密KEY使用 appKey 生成,CTR分组模式初始向量IV由corpid(appid中包含corpid,例如appid=ww51046ddc4f4df510_NjaEnW,corpid=ww51046ddc4f4df510)生成。
为保证消息可以正常解密,消息头中将包含appId信息。接收方可以通过appId确认是否自己持有对应appKey
为方便后续推送功能调整升级,数据格式将进行版本化。消息头中将添加version头。当前版本为第1版,version: 1
与平台接口类似,消息头中同样包含timestamp信息和sign值,但与平台接口不同的是,sign值的计算由 appId+version+timestamp+appKey计算得到,消息体不参与sign计算。接收方可以通过这个sign值确定是否由我平台推送的消息,而不必花费算力进行消息体解密。
消息体解密后为 JSON格式。该JSON具有统一的外层构架结构
{
  "noise": 123,
  "msgId": 999,
  "type": "verify",
  "content": {}
}
字段类型可空说明
noise数字否随机数。接收方成功接收处理消息后需要在响应中回复此值。
msgId数字否消息id。
type字符串否消息推送类型
content不定由具体推送内容确定消息内容。各推送接口分别说明
推送消息使用UTF-8编码

以 appId: zc_test 、appKey: zc_test 、corpid: zc_test为例。假设加密前消息体为:
{"type":"register","noise":4970601478527096155,"msgId":999,"content":"hello"}
以下分别说明加解密流程

AES 密钥生成流程#

1.
取appKey按UTF-8编码字节数据
2.
使用SHA256方式对第1步得到数据计算摘要值(字节数据)
3.
取第2步结果字节数据前16字节作为AES key的字节数据恢复出AES密钥

CTR分组模式初始向量IV生成流程#

1.
取corpid按UTF-8编码字节数据
2.
使用SHA256方式对第1步得到数据计算摘要值(字节数据)
3.
取第2步结果字节数据前16字节作为IV字节数据恢复出IV

消息加密和推送消息组装流程#

1.
取当前系统时间戳 timestamp。本示例假设时间戳为1596681164807
2.
联接appId、version、timestamp、appKey,并对结果做SHA256计算摘要值,以16进制编码表示,作为sign值。本例结果为317672b4685d9b8bafe1794390e31209aed5cef912683292fed94a69085919d3
3.
按照AES密钥生成流程恢复出AES密钥
4.
按照CTR分组模式IV生成流程恢复出IV
5.
取消息体(结尾无换行)按UTF-8编码字节数据
6.
使用第3步得到的密钥和第4步得到的IV对第5步中得到的字节数据做AES/CTR/PKCS5Padding加密,得到加密后字节数据
7.
将第6步得到的字节数据按Base64编码,得到Base64编码字符串,即加密后用于传输的数据。本示例结果为:
5TMVT8H4yTSSoING+afhRlGcCZAIxTs8Z7o3vGpid6tF2aF7C73uZ44qMopuNPCFmwOLOJ8xViCTHUfe/xYZSb71/VRSEDeIqqwN4eg=
8.
组装消息。
消息头:appId、timestamp、sign,version
字符编码 UTF-8
消息体。使用plain text消息体,内容为第6步计算结果
本例结果:
POST http://{{crm-address}}/recieve
appId: zc_test
timestamp: 1596681164807
version: 1
sign: 317672b4685d9b8bafe1794390e31209aed5cef912683292fed94a69085919d3
Content-Type: text/plain;charset=UTF-8
Content-Length: 104

5TMVT8H4yTSSoING+afhRlGcCZAIxTs8Z7o3vGpid6tF2aF7C73uZ44qMopuNPCFmwOLOJ8xViCTHUfe/xYZSb71/VRSEDeIqqwN4eg=

消息解密流程#

1.
从消息头中读取appId,判断是否持有对应的appKey,如果没有,则放弃操作。
a. 可选操作:检验sign值,以认证消息是否是由平台发出
2.
按照AES密钥生成流程恢复出AES密钥
3.
按照CTR分组模式IV生成流程恢复出IV
4.
将收到的消息体按Base64进行解码,得到加密字节数据
5.
使用第2步得到的密钥和第3步得到的IV对第4步得到的字节数据做AES/CTR/PKCS5Padding解密,得到加密前字节数据
6.
使用第5步得到的数据使用UTF-8编码恢复字符串数据。恢复的结果为JSON字符串
7.
处理JSON消息,并根据处理结果响应是否成功。

接收接口响应约定#

为保证消息到达或成功接收处理,对接推送的公司CRM应给予正确的响应。
同时满足以下条件的响应被认为成功接收:
响应HTTP状态为OK 200
响应体不限
其他响应状态均被视为消息推送地址不可用, 不予推送消息。
注意
请保证提供的推送接口可用且稳定, 以下情况会认为不可用, 并将推送地址下线, 待推送地址恢复正常后, 在重新上线推送地址。
1.
接口未响应HTTP状态200,认为接口不可用
2.
接口超5秒未响应,认为接口不可用
建议: 推送消息体量大, 接收消息方异步处理消息, 及时响应, 保证推送接口的吞吐量

推送地址被识别不可用,下线后,如何恢复?#

订阅方可重新调用 推送注册接口 恢复接口即可。
上一页
概述
下一页
推送地址注册回调推送
Built with