企业会话接口说明

来自企业号开发者接口文档
2017年3月27日 (一) 03:41Wikiadmin（讨论 | 贡献）的版本

(差异) ←上一版本 | 最后版本 (差异) | 下一版本→ (差异)
跳转至： 导航、 搜索

创建会话

  • 请求说明

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"]
}
取自“https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明&oldid=2444”