企业会话接口说明

来自企业号开发者接口文档
跳转至: 导航搜索

创建会话

  • 请求说明

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"]
}