企业会话接口说明
创建会话
- 请求说明
Https请求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/chat/create?access_token=ACCESS_TOKEN
请求包结构体为:
{ "chatid": "1", "name": "企业应用中心", "owner": "zhangsan", "userlist": ["zhangsan","lisi","wangwu"] }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
chatid | 是 | 会话id。字符串类型,最长32个字符。只允许字符0-9及字母a-zA-Z, 如果值内容为64bit无符号整型:要求值范围在[1, 2^63)之间, [2^63, 2^64)为系统分配会话id区间 |
name | 是 | 会话标题 |
owner | 是 | 管理员userid,必须是该会话userlist的成员之一 |
userlist | 是 | 会话成员列表,成员用userid来标识。会话成员必须在3人或以上,2000人以下 |
- 返回结果
{ "errcode": 0, "errmsg": "ok" }
获取会话
- 请求说明
Https请求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/chat/get?access_token=ACCESS_TOKEN&chatid=CHATID
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
chatid | 是 | 会话id |
- 返回结果
{ "errcode": 0, "errmsg": "ok", "chat_info": { "chatid": "235364212115767297", "name": "企业应用中心", "owner": "zhangsan", "userlist": ["zhangsan", "lisi", "wangwu"] } }
参数 | 说明 |
---|---|
errcode | 返回码 |
errmsg | 返回码的文本描述信息 |
chat_info | 会话信息 |
chatid | 会话id |
name | 会话标题 |
owner | 管理员userid |
userlist | 会话成员列表,成员用userid来标识 |
修改会话信息
- 请求说明
Https请求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/chat/update?access_token=ACCESS_TOKEN
请求包结构体为:
{ "chatid": "235364212115767297", "op_user": "lisi", "name": "企业应用中心", "owner": "zhangsan", "add_user_list": ["zhaoli"], "del_user_list": ["zhangsan"] }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
chatid | 是 | 会话id |
op_user | 是 | 操作人userid |
name | 否 | 会话标题 |
owner | 否 | 管理员userid,必须是该会话userlist的成员之一 |
add_user_list | 否 | 会话新增成员列表,成员用userid来标识 |
del_user_list | 否 | 会话退出成员列表,成员用userid来标识 |
- 返回结果
{ "errcode": 0, "errmsg": "ok" }
退出会话
- 请求说明
Https请求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/chat/quit?access_token=ACCESS_TOKEN
请求包结构体为:
{ "chatid": "235364212115767297", "op_user": "lisi" }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
chatid | 是 | 会话id |
op_user | 是 | 操作人userid |
- 返回结果
{ "errcode": 0, "errmsg": "ok" }
清除会话未读状态
- 请求说明
Https请求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/chat/clearnotify?access_token=ACCESS_TOKEN
请求包结构体为:
{ "op_user": "zhangsan", "chat": { "type": "single", "id": "lisi" } }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
op_user | 是 | 会话所有者的userid |
chat | 是 | 会话 |
type | 是 | 会话类型:single|group,分别表示:群聊|单聊 |
id | 是 | 会话值,为userid|chatid,分别表示:成员id|会话id |
- 返回结果
{ "errcode": 0, "errmsg": "ok" }
发消息
- 接口说明
消息支持文本、图片、文件、语音、链接,在发送时需要区分群聊和单聊。如果接收人不存在,则发送失败。在企业IM端发送的消息,在同步到发送者的微信上时,不会有提醒。
可以通过文本消息下发表情(下载微信表情转换表)
- 请求说明
Https请求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/chat/send?access_token=ACCESS_TOKEN
请求包结构体为:
text消息请求(单聊):
{ "receiver": { "type": "single", "id": "lisi" }, "sender": "zhangsan", "msgtype": "text", "text": { "content": "Holiday Request For Pony(http://xxxxx)" } }
text消息请求(群聊):
{ "receiver": { "type": "group", "id": "235364212115767297" }, "sender": "zhangsan", "msgtype": "text", "text": { "content": "Holiday Request For Pony(http://xxxxx)" } }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
receiver | 是 | 接收人 |
type | 是 | 接收人类型:single|group,分别表示:群聊|单聊 |
id | 是 | 接收人的值,为userid|chatid,分别表示:成员id|会话id |
sender | 是 | 发送人 |
msgtype | 是 | 消息类型,此时固定为:text |
content | 是 | 消息内容 |
image消息请求(单聊):
{ "receiver": { "type": "single", "id": "lisi" }, "sender": "zhangsan", "msgtype": "image", "image": { "media_id": "MEDIA_ID" } }
image消息请求(群聊):
{ "receiver": { "type": "group", "id": "235364212115767297" }, "sender": "zhangsan", "msgtype": "image", "image": { "media_id": "MEDIA_ID" } }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
参数 | 是否必须 | 描述 |
receiver | 是 | 接收人 |
type | 是 | 接收人类型:single|group,分别表示:群聊|单聊 |
id | 是 | 接收人的值,为userid|chatid,分别表示:成员id|会话id |
sender | 是 | 发送人 |
msgtype | 是 | 消息类型,此时固定为:image |
media_id | 是 | 图片media_id,可以调用上传素材文件接口获取 |
file消息请求(单聊):
{ "receiver": { "type": "single", "id": "lisi" }, "sender": "zhangsan", "msgtype": "file", "file": { "media_id": "MEDIA_ID" } }
file消息请求(群聊):
{ "receiver": { "type": "group", "id": "235364212115767297" }, "sender": "zhangsan", "msgtype": "file", "file": { "media_id": "MEDIA_ID" } }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
参数 | 是否必须 | 描述 |
receiver | 是 | 接收人 |
type | 是 | 接收人类型:single|group,分别表示:群聊|单聊 |
id | 是 | 接收人的值,为userid|chatid,分别表示:成员id|会话id |
sender | 是 | 发送人 |
msgtype | 是 | 消息类型,此时固定为:file |
media_id | 是 | 文件media_id,可以调用上传素材文件接口获取。文件须大于4字节 |
voice消息请求(单聊):
{ "receiver": { "type": "single", "id": "lisi" }, "sender": "zhangsan", "msgtype": "voice", "voice": { "media_id": "MEDIA_ID" } }
voice消息请求(群聊):
{ "receiver": { "type": "group", "id": "235364212115767297" }, "sender": "zhangsan", "msgtype": "voice", "voice": { "media_id": "MEDIA_ID" } }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
参数 | 是否必须 | 描述 |
receiver | 是 | 接收人 |
type | 是 | 接收人类型:single|group,分别表示:群聊|单聊 |
id | 是 | 接收人的值,为userid|chatid,分别表示:用户id|会话id |
sender | 是 | 发送人 |
msgtype | 是 | 消息类型,此时固定为:voice |
media_id | 是 | 语音media_id,可以调用上传素材文件接口获取。size须大于4字节 |
- 返回结果
{ "errcode": 0, "errmsg": "ok" }
link消息请求(单聊):
{ "receiver": { "type": "single", "id": "lisi" }, "sender": "zhangsan", "msgtype": "link", "link": { "title": "title01", "description":"link消息描述", "url":"http://www.qq.com", "thumb_media_id": "177fIcVBfOLYa703hzBByU1EH3_sdp4hyyaxN4Gfdc-o66vG7k-lXgEacQqfuCcJ-VbZnPlUKJDF8ig_8Zgh6-g" } }
link消息请求(群聊):
{ "receiver": { "type": "group", "id": "235364212115767297" }, "sender": "zhangsan", "msgtype": "link", "link": { "title": "title01", "description":"link消息描述", "url":"http://www.qq.com", "thumb_media_id": "177fIcVBfOLYa703hzBByU1EH3_sdp4hyyaxN4Gfdc-o66vG7k-lXgEacQqfuCcJ-VbZnPlUKJDF8ig_8Zgh6-g" } }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
参数 | 是否必须 | 描述 |
receiver | 是 | 接收人 |
type | 是 | 接收人类型:single|group,分别表示:群聊|单聊 |
id | 是 | 接收人的值,为userid|chatid,分别表示:成员id|会话id |
sender | 是 | 发送人 |
msgtype | 是 | 消息类型,此时固定为:link |
title | 是 | 消息标题,不超过128个字节 |
description | 否 | 消息描述,不超过512个字节 |
url | 是 | 跳转的url |
thumb_media_id | 否 | 图片media_id,可以调用上传素材文件接口获取 |
- 返回结果
{ "errcode": 0, "errmsg": "ok" }
设置成员新消息免打扰
- 接口说明
该接口可设置成员接收到的消息是否提醒。主要场景是用于对接企业im的在线状态,如成员处于在线状态时,可以设置该成员的消息免打扰。当成员离线时,关闭免打扰状态,对微信端进行提醒。
- 请求说明
Https请求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/chat/setmute?access_token=ACCESS_TOKEN
请求包结构体为:
{ "user_mute_list": [ { "userid": "zhangsan", "status": 0 }, { "userid": "lisi", "status": 1 } ] }
- 参数说明
参数 | 必须 | 说明 |
---|---|---|
user_mute_list | 是 | 成员新消息免打扰参数,数组,最大支持10000个成员 |
userid | 是 | 成员UserID |
status | 是 | 免打扰状态,0关闭,1打开,默认为0。当打开时所有消息不提醒;当关闭时,以成员对会话的设置为准。 |
- 返回结果
列表中不存在的成员会返回在invaliduser里,剩余合法成员会继续执行。
{ "errcode": 0, "errmsg": "ok", "invaliduser":["zhangsan"] }