获取客户群列表

POST

/cgi-bin/externalcontact/groupchat/list

该接口用于获取配置过客户群管理的客户群列表。

如果不指定 owner_filter，会拉取应用可见范围内的所有群主的数据，但是不建议这样使用。如果可见范围内人数超过1000人，为了防止数据包过大，会报错 81017。此时，调用方需通过指定 owner_filter 来缩小拉取范围
旧版接口以offset+limit分页，要求offset+limit不能超过50000，该方案将废弃，请改用cursor+limit分页

权限说明:

企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
第三方应用需具有“企业客户权限->客户基础信息”权限
对于第三方/自建应用，群主必须在应用的可见范围。

文档ID: 19409
原文档地址：
https://open.work.weixin.qq.com/api/doc/90000/90135/92120
https://open.work.weixin.qq.com/api/doc/90001/90143/93414

请求示例

Shell

JavaScript

Java

Swift

curl --location -g --request POST 'https://qyapi.weixin.qq.com/cgi-bin/externalcontact/groupchat/list?access_token=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status_filter": 0,
    "owner_filter": {
        "userid_list": ["abel"]
    },
    "cursor" : "r9FqSqsI8fgNbHLHE5QoCP50UIg2cFQbfma3l2QsmwI",
    "limit" : 10
}'

响应示例

{
    "errcode": 0,
    "next_cursor": "string",
    "errmsg": "string",
    "group_chat_list": [
        {
            "chat_id": "string",
            "status": 0
        }
    ]
}

请求参数

Query 参数

access_token

调用接口凭证

必需

示例值:

Body 参数application/json

status_filter

integer

必需

{ "status_filter": 0, "owner_filter": { "userid_list": ["abel"] }, "cursor" : "r9FqSqsI8fgNbHLHE5QoCP50UIg2cFQbfma3l2QsmwI", "limit" : 10 }

owner_filter

object

可选

群主过滤。如果不填，表示获取应用可见范围内全部群主的数据（但是不建议这么用，如果可见范围人数超过1000人，为了防止数据包过大，会报错 81017）

userid_list

array[string]

可选

用户ID列表。最多100个

cursor

string

可选

用于分页查询的游标，字符串类型，由上一次调用返回，首次调用不填

limit

integer

必需

分页，预期请求的数据量，取值范围 1 ~ 1000

示例

返回响应

🟢200成功

application/json

Body

errcode

integer <int32>

返回码

可选

next_cursor

string

可选

分页游标，下次请求时填写以获取之后分页的记录。如果该字段返回空则表示已没有更多数据

errmsg

string

可选

对返回码的文本描述内容

group_chat_list

array [object {2}]

客户群列表

可选

chat_id

string

客户群ID

可选

status

integer <int32>

可选

客户群跟进状态。 0 - 跟进人正常 1 - 跟进人离职 2 - 离职继承中 3 - 离职继承完成

修改于 2022-01-14 04:25:47

分配离职成员的客户群

获取客户群详情