企业可通过此接口,根据外部联系人的userid(如何获取?),拉取客户详情。
请求方式:GET(HTTPS)
请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get?access_token=ACCESS_TOKEN&external_userid=EXTERNAL_USERID&cursor=CURSOR
参数说明:
参数 | 必须 | 说明 |
---|---|---|
access_token | 是 | 调用接口凭证 |
external_userid | 是 | 外部联系人的userid ,注意不是企业成员的帐号 |
cursor | 否 | 上次请求返回的next_cursor |
权限说明:
- 企业需要使用系统应用“客户联系”或配置到“可调用应用”列表中的自建应用的secret所获取的accesstoken来调用(accesstoken如何获取?);
- 第三方应用需具有“企业客户权限->客户基础信息”权限
- 第三方/自建应用调用时,返回的跟进人follow_user仅包含应用可见范围之内的成员。
- 当客户在企业内的跟进人超过500人时需要使用cursor参数进行分页获取
返回结果:
<span style="color:#000000"><span style="background-color:var(--ww_bg_gray_mobile_0)"><span style="background-color:#ffffff"><span style="color:#333333"><span style="color:black"><code class="language-javascript"><span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"errcode"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span> <span style="color:#c92c2c">0</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"errmsg"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span> <span style="color:#2f9c0a">"ok"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"external_contact"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"external_userid"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"woAJ2GCAAAXtWyujaWJHDDGi0mACHAAA"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"李四"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"position"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"Manager"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"avatar"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"http://p.qlogo.cn/bizmail/IcsdgagqefergqerhewSdage/0"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"corp_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"腾讯"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"corp_full_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"腾讯科技有限公司"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"type"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">2</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"gender"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">1</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"unionid"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"ozynqsulJFCZ2z1aYeS8h-nuasdAAA"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"external_profile"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"external_attr"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">[</span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"type"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">0</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"文本名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"text"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"value"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"文本"</span>
<span style="color:#5f6364">}</span>
<span style="color:#5f6364">}</span><span style="color:#5f6364">,</span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"type"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">1</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"网页名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"web"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"url"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"http://www.test.com"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"title"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"标题"</span>
<span style="color:#5f6364">}</span>
<span style="color:#5f6364">}</span><span style="color:#5f6364">,</span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"type"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">2</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"测试app"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"miniprogram"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"appid"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span> <span style="color:#2f9c0a">"wx8bd80126147df384"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"pagepath"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span> <span style="color:#2f9c0a">"/index"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"title"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span> <span style="color:#2f9c0a">"my miniprogram"</span>
<span style="color:#5f6364">}</span>
<span style="color:#5f6364">}</span>
<span style="color:#5f6364">]</span>
<span style="color:#5f6364">}</span>
<span style="color:#5f6364">}</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"follow_user"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">[</span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"userid"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"rocky"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"remark"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"李部长"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"description"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"对接采购事务"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"createtime"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">1525779812</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"tags"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">[</span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"group_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"标签分组名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"tag_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"标签名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"tag_id"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"etAJ2GCAAAXtWyujaWJHDDGi0mACHAAA"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"type"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">1</span>
<span style="color:#5f6364">}</span><span style="color:#5f6364">,</span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"group_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"标签分组名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"tag_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"标签名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"type"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">2</span>
<span style="color:#5f6364">}</span><span style="color:#5f6364">,</span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"group_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"标签分组名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"tag_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"标签名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"tag_id"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"stAJ2GCAAAXtWyujaWJHDDGi0mACHAAA"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"type"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">3</span>
<span style="color:#5f6364">}</span>
<span style="color:#5f6364">]</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"remark_corp_name"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"腾讯科技"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"remark_mobiles"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span>
<span style="color:#5f6364">[</span>
<span style="color:#2f9c0a">"13800000001"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"13000000002"</span>
<span style="color:#5f6364">]</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"oper_userid"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"rocky"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"add_way"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">10</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"wechat_channels"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span> <span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"nickname"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span> <span style="color:#2f9c0a">"视频号名称"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"source"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span> <span style="color:#c92c2c">1</span>
<span style="color:#5f6364">}</span>
<span style="color:#5f6364">}</span><span style="color:#5f6364">,</span>
<span style="color:#5f6364">{</span>
<span style="color:#2f9c0a">"userid"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"tommy"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"remark"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"李总"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"description"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"采购问题咨询"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"createtime"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">1525881637</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"state"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"外联二维码1"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"oper_userid"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"woAJ2GCAAAXtWyujaWJHDDGi0mACHAAA"</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"add_way"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#c92c2c">3</span>
<span style="color:#5f6364">}</span>
<span style="color:#5f6364">]</span><span style="color:#5f6364">,</span>
<span style="color:#2f9c0a">"next_cursor"</span><span style="background-color:rgba(255, 255, 255, 0.5)"><span style="color:#a67f59">:</span></span><span style="color:#2f9c0a">"NEXT_CURSOR"</span>
<span style="color:#5f6364">}</span></code></span></span></span></span></span>
参数说明:
参数 | 说明 |
---|---|
errcode | 返回码 |
errmsg | 对返回码的文本描述内容 |
external_userid | 外部联系人的userid |
name | 外部联系人的名称[注1] |
avatar | 外部联系人头像,代开发自建应用需要管理员授权才可以获取,第三方不可获取,上游企业不可获取下游企业客户该字段 |
type | 外部联系人的类型,1表示该外部联系人是微信用户,2表示该外部联系人是企业微信用户 |
gender | 外部联系人性别 0-未知 1-男性 2-女性。第三方不可获取,上游企业不可获取下游企业客户该字段,返回值为0,表示未定义 |
unionid | 外部联系人在微信开放平台的唯一身份标识(微信unionid),通过此字段企业可将外部联系人与公众号/小程序用户关联起来。仅当联系人类型是微信用户,且企业绑定了微信开发者ID有此字段。查看绑定方法。第三方不可获取,上游企业不可获取下游企业客户的unionid字段 |
position | 外部联系人的职位,如果外部企业或用户选择隐藏职位,则不返回,仅当联系人类型是企业微信用户时有此字段 |
corp_name | 外部联系人所在企业的简称,仅当联系人类型是企业微信用户时有此字段 |
corp_full_name | 外部联系人所在企业的主体名称,仅当联系人类型是企业微信用户时有此字段。仅企业自建应用可获取;第三方应用、代开发应用、上下游应用不可获取,返回内容为企业名称,即corp_name。 |
external_profile | 外部联系人的自定义展示信息,可以有多个字段和多种类型,包括文本,网页和小程序,仅当联系人类型是企业微信用户时有此字段,字段详情见对外属性; |
follow_user.userid | 添加了此外部联系人的企业成员userid |
follow_user.remark | 该成员对此外部联系人的备注 |
follow_user.description | 该成员对此外部联系人的描述 |
follow_user.createtime | 该成员添加此外部联系人的时间 |
follow_user.tags.group_name | 该成员添加此外部联系人所打标签的分组名称(标签功能需要企业微信升级到2.7.5及以上版本) |
follow_user.tags.tag_name | 该成员添加此外部联系人所打标签名称 |
follow_user.tags.type | 该成员添加此外部联系人所打标签类型, 1-企业设置,2-用户自定义,3-规则组标签(仅系统应用返回) |
follow_user.tags.tag_id | 该成员添加此外部联系人所打企业标签的id,用户自定义类型标签(type=2)不返回 |
follow_user.remark_corp_name | 该成员对此微信客户备注的企业名称(仅微信客户有该字段) |
follow_user.remark_mobiles | 该成员对此客户备注的手机号码,代开发自建应用需要管理员授权才可以获取,第三方不可获取,上游企业不可获取下游企业客户该字段 |
follow_user.add_way | 该成员添加此客户的来源,具体含义详见来源定义 |
follow_user.wechat_channels | 该成员添加此客户的来源add_way为10时,对应的视频号信息 |
follow_user.wechat_channels.nickname | 视频号名称 |
follow_user.wechat_channels.source | 视频号添加场景,0-未知 1-视频号主页 2-视频号直播间(微信版本要求:iOS ≥ 8.0.20,Android ≥ 8.0.21,且添加时间不早于2022年4月21日。否则添加场景值为0) |
follow_user.oper_userid | 发起添加的userid,如果成员主动添加,为成员的userid;如果是客户主动添加,则为客户的外部联系人userid;如果是内部成员共享/管理员分配,则为对应的成员/管理员userid |
follow_user.state | 企业自定义的state参数,用于区分客户具体是通过哪个「联系我」添加,由企业通过创建「联系我」方式指定 |
next_cursor | 分页的cursor,当跟进人多于500人时返回 |
注1:如果是微信用户,则返回其微信昵称。如果是企业微信联系人,则返回其设置对外展示的别名或实名
如何绑定微信开发者ID
- 登录企业的管理后台-客户联系-客户-api(注:若企业管理端没有客户联系的入口,而是家校沟通的入口,则通过 家校沟通-家校沟通-api ),点击绑定去到微信公众平台进行授权,支持绑定公众号和小程序(需要同时绑定微信开放平台);绑定的公众号或小程序主体需与企业微信主体一致,暂且支持绑定一个
- 绑定完成,即可通过接口获取微信联系人所对应的微信unionid
来源定义
add_way表示添加客户的来源,有固定的值,而state表示此客户的渠道,可以由企业进行自定义的配置,请注意二者的不同。
值 | 含义 |
---|---|
0 | 未知来源 |
1 | 扫描二维码 |
2 | 搜索手机号 |
3 | 名片分享 |
4 | 群聊 |
5 | 手机通讯录 |
6 | 微信联系人 |
8 | 安装第三方应用时自动添加的客服人员 |
9 | 搜索邮箱 |
10 | 视频号添加 |
11 | 通过日程参与人添加 |
12 | 通过会议参与人添加 |
13 | 添加微信好友对应的企业微信 |
14 | 通过智慧硬件专属客服添加 |
201 | 内部成员共享 |
202 | 管理员/负责人分配 |
本节内容
- 获取客户详情