获取客户列表 - API接口文档

功能说明：

本接口可以获取企业下所有客户信息列表并支持获取指定员工添加的客户信息列表

客户信息包含：系统联系人ID、姓名、头像、性别、备注、好友状态、添加时间、联系人类型、对应企业标签、unionId、添加方式、添加员工信息、系统标签信息等。

请求参数

Query 参数

token

string

必需

企业级token, 调用接口凭证

示例值:

1c7090c6d0894856982a07ea7a8dd0a4

wecomUserId

string

企业微信员工id

可选

imBotId

string

可选

托管账号的系统员工Id

coworker

boolean

可选

当值为true时在返回外部客户信息的基础上增加内部员工信息，值为false则只返回外部客户信息

current

string

当前页数，不能为0

必需

pageSize

string

每页数据条数

必需

includeStranger

string

可选

当传入这个参数为字符串"true"的时候，会在结果中返回单删好友（客户删掉托管账号）注：includeStranger 将在 2025-12-31 后废弃

seq

string

可选

游标，在current不传时生效，生效后按照游标拉取数据，不返回总数

friendshipStatus

integer

可选

好友状态：1 表示联系人删除 bot，3 表示双向好友，和includeStranger互斥

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

Body

errcode

number

返回码

必需

0: 发送成功 -1: 无效的chatId -2: 机器人未找到（chatId对应的机器人未找到，可能已经删除） -3: 机器人不在线 -4: 机器人开启了养号模式，不能使用api发送消息 -6: 只支持mp4格式视频 -7: 当前账号不支持api，需高级版本或者开启api权限 -9: 加入队列失败 101:封面图错误

errmsg

string

对返回码的文本描述内容

必需

data

array [object {11}]

必需

imContactId

string

联系人的系统联系人id

必需

name

string

联系人姓名

必需

avatar

string

联系人头像

必需

gender

integer

联系人性别

必需

0 -未知 1 -男性 2 -女性

remark

string

当前员工给当前客户打的备注信息

可选

friendshipStatus

number

好友状态1 - 好友删除了托管账号，3 - 双向好友

必需

createTimestamp

string

联系人添加该员工时间戳（毫秒）

可选

remarkMobiles

array[string]

该成员对此客户备注的手机号码

必需

imInfo

object

IM工具特有信息

必需

botInfo

array [object {4}]

必需

systemTags

array [object {3}]

可选

current

integer

当前页数

必需

pageSize

integer

每页数量

必需

total

integer

客户总数

必需

next_seq

string

最新游标

可选

示例

{
    "errcode": 0,
    "errmsg": "string",
    "data": [
        {
            "imContactId": "string",
            "name": "string",
            "avatar": "string",
            "gender": 0,
            "remark": "string",
            "friendshipStatus": 0,
            "createTimestamp": "string",
            "remarkMobiles": [
                "string"
            ],
            "imInfo": {
                "type": 1,
                "tags": [
                    {
                        "tagName": "string",
                        "type": 3,
                        "groupName": "string",
                        "tagId": "string"
                    }
                ],
                "externalUserId": "string",
                "unionId": "string",
                "followUser": {
                    "wecomUserId": "string",
                    "state": "string",
                    "addWay": 0
                }
            },
            "botInfo": [
                {
                    "botId": "string",
                    "imBotId": "string",
                    "name": "string",
                    "avatar": "string"
                }
            ],
            "systemTags": [
                {
                    "groupName": "string",
                    "tagName": "string",
                    "tagId": "string"
                }
            ]
        }
    ],
    "current": 0,
    "pageSize": 0,
    "total": 0,
    "next_seq": "string"
}