企业微信API
2021-08-19 10:57:29 224 举报AI智能生成
企业微信3.0 企业微信API
作者其他创作
大纲/内容
第三方应用开发
参数说明
suite_id
第三方应用ID
第三方应用ID
suite_secret
第三方应用密钥
第三方应用密钥
获取方法为：登录服务商管理后台->标准应用服务->应用管理栏，点进某个应用即可看到
provider_secret
获取方法为：登录服务商管理后台->标准应用服务->通用开发参数
suite_ticket (安全凭证)
有效期为30分钟
有效期为30分钟
服务商的token
应用授权的token
企业接口的token
服务商注册&配置
注册条件
拥有企业微信
用系统管理员身份在“企业微信服务商官网”进行申请
企业Logo
企业简介
企业官网
配置开发信息
ProviderSecret
系统事件接收URL
Token
EncodingAESKey
白名单IP
应用创建
普通应用
通讯录应用
一家企业只能授权一个通讯录应用
应用上线
提交上线
3个工作日内完成审核
上线应用
服务端API
规则与说明
所有的接口需使用HTTPS协议、JSON数据格式、UTF8编码
请求地址，参数中标注大写的单词，表示为需要替换的变量
返回结果根据errcode存在且不为0判断为失败，否则为成功
access_token
provider_access_token
服务商的token
服务商的token
corpid（服务商CorpID）
provider_secret（服务商密钥）
suite_access_token
第三方应用的token
第三方应用的token
suite_id（第三方应用ID）
suite_secret（第三方应用密钥）
suite_ticket (安全凭证)
有效期为30分钟
有效期为30分钟
access_token
授权企业的token
授权企业的token
企业安装第三方应用后
第三方服务商以企业的corpid
永久授权码
回调配置
三个配置项
URL
回调服务地址
回调服务地址
需要能同时支持HttpGet以及HttpPost两种能力
验证逻辑：
企业微信往URL服务上发一条Get请求带签名及密文参数到URL服务上，如果URL服务检查签名通过，并能正确返回密文参数对应的明文字符串，则验证通过。
企业微信往URL服务上发一条Get请求带签名及密文参数到URL服务上，如果URL服务检查签名通过，并能正确返回密文参数对应的明文字符串，则验证通过。
Token
用于计算签名
用于计算签名
分辨出是否为企业微信来源
分辨出推送消息的内容是否被篡改
分辨出推送消息的内容是否被篡改
英文或数字组成且长度不超过32位的自定义字符串
EncodingAESKey
用于消息内容加密
用于消息内容加密
英文或数字组成且长度为43位的自定义字符串
将发送的内容进行加密，并组装成一定格式后再发送
Http Get请求
验证URL有效性
验证URL有效性
参数说明
msg_signature
企业微信加密签名
String
企业微信加密签名
String
计算规则
sha1(sort(token、timestamp、nonce、msg_encrypt))
sha1(sort(token、timestamp、nonce、msg_encrypt))
timestamp
时间戳
Integer
时间戳
Integer
nonce
随机数
Sting
随机数
Sting
echostr
加密的字符串
String
加密的字符串
String
需要解密得到消息内容明文，解密后有random、msg_len、msg、receiveid四个字段
其中msg即为消息内容明文
其中msg即为消息内容明文
①对密文BASE64解码aes_msg=Base64_Decode(msg_encrypt)
②AESKey = Base64_Decode(EncodingAESKey + "=")
③使用AESKey做AES-256-CBC解密 rand_msg = aes_decrypt(aes_msg, AESKey)
④去掉rand_msg头部的16个随机字节和4个字节的msg_len，截取msg_len长度的部分即为msg，剩下的为尾部的receiveid
②AESKey = Base64_Decode(EncodingAESKey + "=")
③使用AESKey做AES-256-CBC解密 rand_msg = aes_decrypt(aes_msg, AESKey)
④去掉rand_msg头部的16个随机字节和4个字节的msg_len，截取msg_len长度的部分即为msg，剩下的为尾部的receiveid
参数值需要做Urldecode处理
1秒内响应GET请求，响应内容为得到的明文消息内容（不能加引号，不能带bom头，不能带换行符）
Http Post请求
接收业务数据
接收业务数据
企业微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次
XML数据格式
获取企业微信服务器的ip段
建议企业每天定时拉取IP段，更新防火墙设置，避免因IP段变更导致网络不通
当IP段变更时，新旧IP段会同时保留一段时间
https://qyapi.weixin.qq.com/cgi-bin/getcallbackip?access_token=ACCESS_TOKEN
GET
GET
应用授权
授权方式
从服务商网站发起
从企业微信应用市场发起
通讯录权限体系
相关接口
通讯录管理
secret
通讯录管理secret
建议此种方式
建议此种方式
应用secret
通讯录展示组件
浏览器方案
小程序方案
服务商需存储接入企业的参数
corpid
永久授权码
通讯录管理secret
客户联系secret
问题
应用如何设置为通讯录应用
内部：服务端API
规则与说明
所有的接口需使用HTTPS协议、JSON数据格式、UTF8编码
请求地址，参数中标注大写的单词，表示为需要替换的变量
返回结果根据errcode存在且不为0判断为失败，否则为成功
开发者工具
调用频率限制
调用单个cgi/api不可超过2000次/分，30000次/小时
每ip调用单个cgi/api不可超过20000次/分，600000次/小时
所有应用创建群数累积不可超过1000/天
所有应用变更群次数累积不可超过100/小时
基本概念介绍
corpid
每个企业都拥有唯一的corpid，获取此信息可在管理后台“我的企业”－“企业信息”下查看“企业ID”（需要有管理员权限）
userid
每个成员都有唯一的userid，即所谓“帐号”
agentid
每个应用都有唯一的agentid
secret
secret是企业应用里面用于保障数据安全的“钥匙”，每一个应用都有一个独立的访问密钥，为了保证数据的安全，secret务必不能泄漏
access_token
access_token是企业后台去企业微信的后台获取信息时的重要票据，由corpid和secret产生。所有接口在通信时都需要携带此信息用于验证接口的访问权限
获取access_token
注意：不能频繁调用gettoken接口，否则会受到频率拦截
开发者需要缓存access_token
有效期通过返回的expires_in来传达
默认7200秒（2小时）有效
有效期内重复获取返回相同结果，过期后获取会返回新的access_token
每个应用的access_token是彼此独立的
回调配置
三个配置项
URL
回调服务地址
回调服务地址
需要能同时支持HttpGet以及HttpPost两种能力
验证逻辑：
企业微信往URL服务上发一条Get请求带签名及密文参数到URL服务上，如果URL服务检查签名通过，并能正确返回密文参数对应的明文字符串，则验证通过。
企业微信往URL服务上发一条Get请求带签名及密文参数到URL服务上，如果URL服务检查签名通过，并能正确返回密文参数对应的明文字符串，则验证通过。
Token
用于计算签名
用于计算签名
分辨出是否为企业微信来源
分辨出推送消息的内容是否被篡改
分辨出推送消息的内容是否被篡改
英文或数字组成且长度不超过32位的自定义字符串
EncodingAESKey
用于消息内容加密
用于消息内容加密
英文或数字组成且长度为43位的自定义字符串
将发送的内容进行加密，并组装成一定格式后再发送
Http Get请求
验证URL有效性
验证URL有效性
参数说明
msg_signature
企业微信加密签名
String
企业微信加密签名
String
计算规则
sha1(sort(token、timestamp、nonce、msg_encrypt))
sha1(sort(token、timestamp、nonce、msg_encrypt))
timestamp
时间戳
Integer
时间戳
Integer
nonce
随机数
Sting
随机数
Sting
echostr
加密的字符串
String
加密的字符串
String
需要解密得到消息内容明文，解密后有random、msg_len、msg、receiveid四个字段
其中msg即为消息内容明文
其中msg即为消息内容明文
①对密文BASE64解码aes_msg=Base64_Decode(msg_encrypt)
②AESKey = Base64_Decode(EncodingAESKey + "=")
③使用AESKey做AES-256-CBC解密 rand_msg = aes_decrypt(aes_msg, AESKey)
④去掉rand_msg头部的16个随机字节和4个字节的msg_len，截取msg_len长度的部分即为msg，剩下的为尾部的receiveid
②AESKey = Base64_Decode(EncodingAESKey + "=")
③使用AESKey做AES-256-CBC解密 rand_msg = aes_decrypt(aes_msg, AESKey)
④去掉rand_msg头部的16个随机字节和4个字节的msg_len，截取msg_len长度的部分即为msg，剩下的为尾部的receiveid
参数值需要做Urldecode处理
1秒内响应GET请求，响应内容为得到的明文消息内容（不能加引号，不能带bom头，不能带换行符）
Http Post请求
接收业务数据
接收业务数据
企业微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次
XML数据格式
获取企业微信服务器的ip段
建议企业每天定时拉取IP段，更新防火墙设置，避免因IP段变更导致网络不通
当IP段变更时，新旧IP段会同时保留一段时间
https://qyapi.weixin.qq.com/cgi-bin/getcallbackip?access_token=ACCESS_TOKEN
GET
GET
回调事件
添加企业客户事件
配置了客户联系功能的成员添加外部联系人时，回调该事件
配置了客户联系功能的成员添加外部联系人时，回调该事件
外部联系人免验证添加成员事件
外部联系人添加了配置了客户联系功能且开启了免验证的成员时（此时成员尚未确认添加对方为好友），回调该事件
外部联系人添加了配置了客户联系功能且开启了免验证的成员时（此时成员尚未确认添加对方为好友），回调该事件
删除企业客户事件
配置了客户联系功能的成员删除外部联系人时，回调该事件
配置了客户联系功能的成员删除外部联系人时，回调该事件
删除跟进成员事件
配置了客户联系功能的成员被外部联系人删除时，回调该事件
配置了客户联系功能的成员被外部联系人删除时，回调该事件
客户群变更事件
客户群被修改后（群名变更，群成员增加或移除），回调该事件
客户群被修改后（群名变更，群成员增加或移除），回调该事件
获取企业微信API域名IP段
https://qyapi.weixin.qq.com/cgi-bin/get_api_domain_ip?access_token=ACCESS_TOKEN
GET
GET
外部联系人管理
外部联系人分为企业微信联系人和微信联系人两种类型
销售同事需配置客户联系功能
必须先做好关联绑定微信开发者ID
绑定的公众号或小程序主体需与企业微信主体一致，暂且支持绑定一个
绑定的公众号或小程序主体需与企业微信主体一致，暂且支持绑定一个
设置同事对外展示信息
目前支持文本、网页、小程序三种类型
必须是有在本企业安装授权的小程
必须是有在本企业安装授权的小程
配置客户联系「联系我」
微信小程序接入按钮
生成专属的「联系我」二维码
每个企业可通过API最多配置10万个「联系我」
需要妥善存储返回的config_id
config_id丢失可能导致无法编辑或删除「联系我」
config_id丢失可能导致无法编辑或删除「联系我」
获取客户列表
企业可通过此接口获取指定成员添加的客户列表。
客户是指配置了客户联系功能的成员所添加的外部联系人。
没有配置客户联系功能的成员，所添加的外部联系人将不会作为客户返回。
客户是指配置了客户联系功能的成员所添加的外部联系人。
没有配置客户联系功能的成员，所添加的外部联系人将不会作为客户返回。
权限说明：
企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）；
第三方应用需拥有“企业客户”权限。
第三方/自建应用只能获取到可见范围内的配置了客户联系功能的成员。
企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）；
第三方应用需拥有“企业客户”权限。
第三方/自建应用只能获取到可见范围内的配置了客户联系功能的成员。
请求参数
access_token
userid
企业成员的userid
企业成员的userid
返回参数
external_userid
外部联系人的userid列表
外部联系人的userid列表
获取客户详情
请求参数
access_token
external_userid
外部联系人的userid，注意不是企业成员的帐号
外部联系人的userid，注意不是企业成员的帐号
返回核心参数
name
外部联系人的姓名或别名
外部联系人的姓名或别名
avatar
外部联系人头像，第三方不可获取
外部联系人头像，第三方不可获取
type
外部联系人的类型，1表示该外部联系人是微信用户，2表示该外部联系人是企业微信用户
外部联系人的类型，1表示该外部联系人是微信用户，2表示该外部联系人是企业微信用户
unionid
外部联系人在微信开放平台的唯一身份标识（微信unionid）
必须先做好关联绑定微信开发者ID，绑定的公众号或小程序主体需与企业微信主体一致，暂且支持绑定一个
外部联系人在微信开放平台的唯一身份标识（微信unionid）
必须先做好关联绑定微信开发者ID，绑定的公众号或小程序主体需与企业微信主体一致，暂且支持绑定一个
follow_user
所有添加此用户企业同时都可以获取
所有添加此用户企业同时都可以获取
userid（添加了此外部联系人的企业成员userid）
remark (该成员对此外部联系人的备注)
createtime (该成员添加此外部联系人的时间)
tags（该成员添加此外部联系人所打标签，有下级tag详细信息）
remark_corp_name (该成员对此客户备注的企业名称)
state (该成员添加此客户的渠道，由用户通过创建「联系我」方式指定)
权限说明：
企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）；
第三方/自建应用调用时，返回的跟进人follow_user仅包含应用可见范围之内的成员。
企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）；
第三方/自建应用调用时，返回的跟进人follow_user仅包含应用可见范围之内的成员。
修改客户备注信息
请求参数
access_token
userid (企业成员的userid)
external_userid (外部联系人userid)
remark（此用户对外部联系人的备注）
description（此用户对外部联系人的描述）
remark_company (此用户对外部联系人备注的所属公司名称,为微信用户时有效)
remark_mobiles (此用户对外部联系人备注的手机号，会覆盖旧的备注手机号，清除所有手机号填写一个空字符串(“”))
remark_pic_mediaid（备注图片的mediaid，可以通过素材管理接口获得）
获取客户群列表
权限说明:
企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
暂不支持第三方调用。
企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
暂不支持第三方调用。
请求参数
access_token
status_filter (群状态过滤)
非必填
非必填
owner_filter (群主过滤。如果不填，表示获取全部群主的数据)
非必填
非必填
userid_list （用户ID列表。最多100个）
非必填
非必填
partyid_list（部门ID列表。最多100个）
非必填
非必填
offset（分页，偏移量）
limit（分页，预期请求的数据量，取值范围 1 ~ 1000）
返回参数
group_chat_list （客户群列表）
chat_id
status（客户群状态）
获取客户群详情
权限说明:
企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
暂不支持第三方调用。
企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
暂不支持第三方调用。
请求参数
access_token
chat_id（客户群ID）
返回参数
chat_id
name（群名）
owner（群主ID）
create_time（群的创建时间）
notice （群公告）
member_list
群成员列表
群成员列表
userid
type（成员类型）
join_time（入群时间）
join_scene（入群方式）
添加企业群发消息任务
企业可通过此接口添加企业群发消息的任务并通知客服人员发送给相关客户
限制：
调用该接口并不会直接发送消息给客户，需要相关的客服人员操作以后才会实际发送（客服人员的企业微信需要升级到2.7.5及以上版本）
同一个企业对一个客户一个自然周内（周一至周日）至多只能发送一条消息，超过限制的用户将会被忽略。
调用该接口并不会直接发送消息给客户，需要相关的客服人员操作以后才会实际发送（客服人员的企业微信需要升级到2.7.5及以上版本）
同一个企业对一个客户一个自然周内（周一至周日）至多只能发送一条消息，超过限制的用户将会被忽略。
可发送文本、图文、小程序
发送新客户欢迎语
企业微信在向企业推送添加外部联系人事件时，会额外返回一个welcome_code，企业以此为凭据调用接口，可通过成员向新添加的客户发送个性化的欢迎语
限制：
企业仅可在收到相关事件后20秒内调用，且只可调用一次
多应用配置时，仅有最先调用的可以发送成功
如果已经开始聊天，发送失败
企业仅可在收到相关事件后20秒内调用，且只可调用一次
多应用配置时，仅有最先调用的可以发送成功
如果已经开始聊天，发送失败
获取离职成员的客户列表
离职成员的外部联系人再分配
离职成员的群再分配
获取联系客户统计数据
企业可通过此接口获取成员联系客户的数据，包括发起申请数、新增客户数、聊天数、发送消息数和删除/拉黑成员的客户数等指标。
获取客户群统计数据
获取指定日期全天的统计数据。注意，企业微信仅存储60天的数据。
0 条评论
下一页
