微伴助手OpenAPI
  1. 消息订阅
微伴助手OpenAPI
  • OpenAPI基本介绍
  • 错误码参考表
  • 访问频率和并发限制
  • 消息订阅
    • 订阅消息加解密指南
    • 回调应用配置指南
    • 工单变更消息
      • 工单变更消息回调
      • 创建工单回调
      • 流转工单回调
      • 关闭工单回调
      • 重新打开工单回调
      • 评论工单回调
  • 获取访问凭据
    • 获取访问凭据
      POST
  • 员工管理
    • 获取员工列表
      GET
    • 获取员工详情
      GET
    • 发送员工通知
      POST
  • 自定义订单管理
    • 订单信息删除
      GET
    • 获取订单信息列表
      GET
    • 批量同步店铺信息
      POST
    • 批量同步商品信息
      POST
    • 批量同步订单信息v2
      POST
    • 批量删除商品信息
      POST
    • 删除店铺信息
      GET
    • 批量删除订单信息
      POST
    • 获取店铺信息详情
      POST
    • 获取店铺信息列表
      GET
    • 获取商品信息详情
      POST
    • 获取商品信息列表
      GET
  • 客户管理
    • 获取客户列表
      GET
    • 根据更新时间获取客户列表
      GET
    • 获取客户详情
      GET
    • 获取流失提醒客户列表
      GET
    • 导入客户信息
      POST
    • 添加客户评分
      POST
    • 添加自定义字段
      POST
    • 批量预设客户属性
      POST
    • 批量修改自定义字段的值
      POST
    • 创建批量加好友任务(批量创建添加客户任务)
      POST
    • 批量unionid&openid换external_user_id
      POST
    • external_user_id换unionid
      POST
    • unionid&openid换客户id
      POST
    • 获取客户自定义字段值列表
      GET
    • 批量获取客户详情
      POST
    • 获取批量加好友待添加列表
      GET
  • 客户积分管理
    • 批量增减客户积分
    • 批量获取客户积分
    • 获取单个客户积分明细记录
    • 获取全部客户积分明细记录
  • 客户标签管理
    • 获取标签列表
    • 批量更新客户企业标签
    • 给客户添加企业标签
    • 删除客户的企业标签
    • 给客户添加微伴个人标签
    • 删除客户的微伴个人标签
    • 获取预打标签信息
    • 批量预打企业标签
    • 根据手机号删除预打标签任务
    • 根据unionid删除预打标签任务
    • 获取指定用户预打标签任务详情
    • 获取预打标签任务列表
    • 添加预打标签任务
  • 客户画像管理
    • 获取客户事件列表
    • 创建自定义客户事件
    • 获取自定义客户事件类型列表
    • 获取自定义客户事件类型详情
    • 添加自定义客户事件类型
    • 删除自定义客户事件类型
    • 更新自定义客户事件类型
    • 获取客户阶段状态
  • 标签库管理
    • 获取标签列表V2
    • 获取指定标签信息
    • 新增企业标签组
    • 新增企业标签
    • 删除企业标签
    • 更新企业标签
    • 同步企业微信标签
  • 群聊管理
    • 获取群聊列表
    • 获取群聊成员列表
    • 获取客户所在群聊
    • 查看客户是否在群聊中
    • 获取群聊详情
  • 工单管理
    • 工单模块OpenAPI开发必读
    • 获取工单列表
    • 获取工单详情
    • 获取工单流内处理人
    • 获取工单模板列表
    • 获取工单模板详情
    • 新建工单
    • 修改工单
    • 流转工单
    • 评论工单
    • 关闭工单
  • 销售过程管理
    • 获取商机列表
    • 获取商机详情
    • 修改商机阶段
    • 获取线索公海列表
    • 批量导入线索
    • 修改线索
    • 获取线索列表
    • 员工单条/批量领取线索
    • 获取线索客户列表
  • 聊天记录管理
    • 获取会话消息
    • 获取会话消息2(按照消息时间逆序)
    • 获取员工会话
  • 拉新排行榜
    • 获取拉新排行榜列表
  • 群裂变
    • 获取群裂变活动列表
    • 获取群裂变任务详情
    • 获取群裂变客户详情列表
  • 群打卡
    • 获取群打卡活动列表
    • 获取群打卡任务详情
  • 企微任务宝
    • 获取企微任务宝活动列表
    • 获取企微任务宝任务详情
    • 获取企微任务宝对应的客户数据列表
    • 获取客户对应的企微任务宝数据列表
  • 拉新排行榜
    • 获取拉新排行榜活动列表
  • 自定义表单
    • 获取自定义表单列表
    • 自定义表单用户与表单关系列表
    • 自定义表单提交数据详情列表
    • 获取自定义表单分组列表
  • 客户转化
    • 批量新增手机线索转化
  • 员工个人群发记录管理
    • 获取员工个人群发记录列表
    • 获取员工个人群发记录结果列表
  • 渠道码管理
    • 获取渠道码列表
    • 获取渠道码加人数据
  • 素材库管理
    • 获取素材库列表
    • 获取素材库标签列表
    • 新增素材
    • 更新素材
    • 删除素材
    • 新建素材分组
    • 修改素材分组
    • 添加素材库标签
    • 删除素材库标签
    • 删除素材分组
    • 素材分组列表
  • 互动雷达管理
    • 获取雷达列表
    • 获取雷达详情
    • 添加雷达
    • 修改雷达
    • 删除雷达
    • 上传file
    • 获取雷达分组列表
    • 获取雷达客户访问记录
  • 自定义侧边栏身份校验
    • 侧边栏模块化-自定义卡片功能说明
    • 自定义侧边栏Code校验
  • 有赞订单管理
    • 获取有赞订单
    • 获取有赞订单列表
  • 小鹅通订单管理
    • 获取小鹅通TOKEN
  • 项目管理
    • 项目列表
  • 门店信息
    • 批量导入门店
    • 批量更新门店
    • 门店列表
  • 人群包
    • 人群包列表获取
    • 创建人群包
    • 更新人群包
    • 创建的人群包中添加数据
    • 获取人群包数据详情
  • 客户群发
    • 客户群发创建
    • 群发任务列表
    • 群群发详情获取
    • 员工群发结果
    • 客户群群发创建
    • 员工-群群发结果
    • 获取群发错误unionid/extid
  • 企微朋友圈
    • 企微朋友圈创建
    • 企微朋友圈任务列表
    • 企微朋友圈任务发表详情
  • 个人SOP
    • 个人SOP列表
    • 个人SOP详情-规则列表
    • 个人SOP详情-执行记录
  • 部门管理
    • 获取部门列表
  • 群标签管理
    • 获取群聊标签分组及其子列表
    • 群聊批量打标签
  • 话术库
    • 企业话术分组列表
    • 企业话术列表
  • 企微数据专区
    • 获取会话消息(企微数据专区)
  1. 消息订阅

回调应用配置指南

回调配置#

1.什么时候需要回调服务#

在集成微伴助手与内部系统时,我们往往需要搭建一个回调服务。回调服务,可以实现:
可以及时获取到状态变化。比如,工单发生变化时,不需要定时去拉取工单对比,而是实时地获取到变化的工单,进行同步。

2.回调服务怎么配置#

image.png
配置回调服务,需要有三个配置项,分别是:URL, Token, AESKey。
首先,URL为回调服务地址,由开发者搭建(需要满足接口要求,参考第3部分说明),用于接收通知消息或者事件。
其次,Token用于计算签名,由英文或数字组成且长度不超过32位的自定义字符串。开发者提供的URL是公开可访问的,这就意味着拿到这个URL,就可以往该链接推送消息。那么URL服务需要解决两个问题:
如何分辨出是否为微伴助手来源
如何分辨出推送消息的内容是否被篡改
通过数字签名就可以解决上述的问题。具体为:约定Token作为密钥,仅开发者和微伴助手知道,在传输中不可见,用于参与签名计算。微伴助手在推送消息时,将消息内容与Token计算出签名。开发者接收到推送消息时,也按相同算法计算出签名。如果为同一签名,则可信任来源为微伴助手,并且内容是完整的。
如果非微伴助手来源,由于攻击者没有正确的Token,无法算出正确的签名;
如果消息内容被篡改,由于开发者会将接收的消息内容与Token重算一次签名,该值与参数的签名不一致,则会拒绝该请求。
image.png
最后,AESKey用于消息内容加密,由英文或数字组成且长度为43位的自定义字符串。由于消息是在公开的因特网上传输,消息内容是可被截获的,如果内容未加密,则截获者可以直接阅读消息内容。若消息内容包含一些敏感信息,就非常危险了。AESKey就是在这个背景基础上提出,将发送的内容进行加密,并组装成一定格式后再发送。
image.png

3.开发者服务需要实现以下功能#

配置回调服务时,需要能同时支持HttpGet以及HttpPost两种能力,
微伴助手会先判断URL服务是否具备解析微伴助手推送消息的能力。
具体方式是,微伴助手往URL服务上发一条Get请求带签名及密文参数到URL服务上,如果URL服务检查签名通过,并能正确返回密文参数对应的明文字符串,则验证通过。此时在微伴助手的配置就开始生效。
后续的业务请求(比如应用菜单的点击事件,用户消息等),都会类似的方式(签名+密文)向服务URL推送消息。URL服务验证签名通过后,需要将POST数据解密,就可以得到对应的业务消息明文
image.png

3.1 支持Http Get请求验证URL有效性#

开发者填完3个配置项点击确定,此时微伴助手会向开发者填写的URL地址发起一个Get请求来验证URL的有效性;假设开发者服务的地址为https://api.com/receive_weiban_message
请求地址: https://api.com/receive_weiban_message?msg_signature=8ddba101fe5f9404e6b28e2d6cfb7565c7572d09&timestamp=1639731768&nonce=64390332&echostr=505deLub74lMxyhj6SZk55rjDRxM7lEzVa/8ZFdOUWkkv9kFpNI%2B9c3YLRLDjL%2B1GEIWpvuQSFw2ck2zb0QcAQ%3D%3D
收到请求后开发者需要
1、对URL解码,解析出Get请求的参数,包括消息体签名(msg_signature),时间戳(timestamp),随机数字串(nonce)以及微伴助手推送过来的随机加密字符串(echostr)
2、验证签名msg_signature、解密echostr得到明文消息内容reply_echostr;可以直接使用加解密库的[验证URL函数]
3、响应Get请求,响应内容为上一步得到的明文消息内容reply_echostr

3.2 支持Http Post请求接收业务数据#

微伴助手在Post请求失败之后会再发起2次Post请求
请求地址: https://api.com/receive_weiban_message?msg_signature=cee361999ae632f3e4b9f153475930ce0903b7b7&timestamp=1639732244&nonce=741425964
请求参数
{
  "corp_id": "1704174310933890049", 
  "app_id": "100001", 
  "encrypt": "3bVgLZLP6TtC8U5qbXxHoq6bL2ZZyarp0s5lyp5RwqNY6E3mhmCU6sb2UlizgL8sHwFqqEtgpOC1OuHBKXF987LB/l8HSRaRHfYseZ5/9QWOJftb/nnI2t6lsEB5aIDkOv3RuvdOYEsvoPy45v6eCbe8sR3WMvy5YDjBiauLWw9us9xvGFx/aRV3DTjPzf8J6H5u8D5339MUP0I+nM11Mhe9pIFnnWMY6Cbd6g9fpwXKalRWBU4N6LXF2/eMypBuVsvJRAncvergZJoBj3svtc2LbaI70qod/G5OmEtbco5A6BXcoaN9HlszmvYH3XIUS8PyRqBOTaELLgIlSIAtzJEX8J7ZjK65LfgVYY2AZzvxxXkQd/mWHhh90M1HPgGQrCYQSkuRb1jGHgKf4HtWgqFzTY50+YwOmrNY4DAun6jrbLwKweMWNMU7g5Qd3YuEklwnteftmL9iAJxJRnx+EihOR+DZjqWibfRnuhPQLuHkMXLvQIzkD+LHDdOYOaWJ3kXvUwt9BGgLKP9QD/kow6nc6xbnUUI+ELxWo65P9PzrJ0otkh1r59rZiwaUC4FFl8W75dh3EGp8dg3Y2adtfekz3Ok9OxMW07HcVoedYdaapUQh8gozu5LC3VZ3Tmmv8TMY/XhWzj8mWIpI6eE57pWTZT3MANhILBmm/n0HmocqIXALjcllklMWWm0X6Z+HEOaf4DiSGk8bRgl9jgifbG0B+s5hV5+1qBMWLaGBLi4MWClldW6wk1YdonlD3fKl0Uxma0eQSVGFlTMezdcJi+92higQevlEC+xanZ3E4m0=",
  "retry_count": 1
}
参数说明
corp_id公司id
app_id应用id,对于每个公司从100001开始递增
encrypt密文,解密可得到明文的消息结构体
retry_count重试次数,值有0、1、2
收到请求后开发者需要
1、对msg_signature签名进行校验; 解密encrypt,得到明文的消息结构体
2、正确响应本次请求,响应的状态码需要为200
明文消息的格式如下
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "corp_id": "1704174310933890049",
    "create_time": 1640244967,
    "type": "event",
    "event": "work_order_change",
    "status": "switch",
    "msg_data": {}
}
参数说明
id消息id
corp_id公司id
create_time消息创建时间,精确到小数点后3位
type消息类型,值为"event"表示消息为事件类型
event_type事件类型
status事件变更类型
msg_data消息体,不同事件类型消息体不同

3.3 微伴助手服务器的ip段设置为白名单#

设置防火墙拦截其他ip地址,将微伴助手服务域名weibanzhushou.com设置为白名单

4.回调服务demo#

Python
https://github.com/weiban-open-platform/open-msg-crypt-python

Golang
https://github.com/weiban-open-platform/open-msg-crypt-golang
上一页
订阅消息加解密指南
下一页
工单变更消息回调
Built with