The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
QQ-weixin-work-v0.10
River stage zero No dependents
1 ++
/ QQ::weixin::work::externalcontact::customer_acquisition

Name

QQ::weixin::work::externalcontact::customer_acquisition

DESCRIPTION

获客链接管理 最后更新：2023/11/13

SYNOPSIS

https://developer.work.weixin.qq.com/document/path/97297

FUNCTION

list_link(access_token, hash);

获取获客链接列表

SYNOPSIS

https://developer.work.weixin.qq.com/document/path/97297#获取获客链接列表

请求说明：

企业可通过此接口获取当前仍然有效的获客链接。

请求包结构体为：

        {
           "limit":100,
           "cursor":"CURSOR"
        }

参数说明：

        参数                  必须  说明
    access_token        是       调用接口凭证
        limit   否       返回的最大记录数，整型，最大值100
        cursor  否       用于分页查询的游标，字符串类型，由上一次调用返回，首次调用可不填

权限说明：

调企业需要使用配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。 第三方或代开发应用需具有“企业客户权限->获客助手”权限 不支持客户联系系统应用调用

RETURN 返回结果：

        {
                "errcode": 0,
                "errmsg": "ok",
                "link_id_list":
                [
                        "LINK_ID_AAA",
                        "LINK_ID_BBB",
                        "LINK_ID_CCC"
                ],
                "next_cursor":"CURSOR"
        }

RETURN 参数说明：

        参数              说明
    errcode     返回码
        errmsg  对返回码的文本描述内容
        link_id_list    link_id列表
        next_cursor     分页游标，在下次请求时填写以获取之后分页的记录

get(access_token, hash);

获取获客链接详情

SYNOPSIS

https://developer.work.weixin.qq.com/document/path/97297#获取获客链接详情

请求说明：

企业可通过此接口根据获客链接id获取链接配置详情。

请求包结构体为：

        {
           "link_id":"LINK_ID_AAA"
        }

参数说明：

        参数                  必须  说明
    access_token        是       调用接口凭证
        link_id 是       获客链接id

权限说明：

企业需要使用配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。 第三方或代开发应用需具有“企业客户权限->获客助手”权限 不支持客户联系系统应用调用

RETURN 返回结果：

        {
          "errcode": 0,
          "errmsg": "ok",
          "link":
                {
                        "link_name":"LINK_NAME",
                        "url":"https://work.weixin.qq.com/ca/xxxxxx",
                        "create_time":1672502400,
                        "skip_verify":true
                },
                "range":
                {
                        "user_list":["rocky","sam"],
                        "department_list":[1]
                },
        }

RETURN 参数说明：

        参数              说明
    errcode     返回码
        errmsg  对返回码的文本描述内容
        link.link_name  获客链接的名称
        link.url        获客链接实际的url
        link.create_time        创建时间
        link.skip_verify        是否无需验证，默认为true
        range.user_list 该获客链接使用范围成员列表
        range.department_list   该获客链接使用范围的部门列表

create_link(access_token, hash);

创建获客链接

SYNOPSIS

https://developer.work.weixin.qq.com/document/path/97297#创建获客链接

请求说明：

企业可通过此接口创建新的获客链接。

请求包结构体为：

        {
           "link_name":"获客链接1号",
           "range":
           {
                        "user_list":["zhangsan","lisi"],
                        "department_list":[2,3]
           },
           "skip_verify":true
        }

参数说明：

        参数                  必须  说明
    access_token        是       调用接口凭证
        link_name       是       链接名称
        range.user_list 否       此获客链接关联的userid列表，最多500人
        range.department_list   否       此获客链接关联的部门id列表，部门覆盖总人数最多500个
        skip_verify     否       是否无需验证，默认为true

range.user_list和range.department_list不可同时为空，range覆盖的总用户数不得超过500人。

权限说明：

企业需要使用配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。 第三方或代开发应用需具有“企业客户权限->获客助手”权限 不支持客户联系系统应用调用

RETURN 返回结果：

        {
                "errcode": 0,
                "errmsg": "ok",
                "link":{
                        "link_id":"LINK_ID",
                        "link_name":"获客链接1号",
                        "url":"URL",
                        "create_time":1667232000
                }
        }

RETURN 参数说明：

        参数              说明
    errcode     返回码
        errmsg  对返回码的文本描述内容
        link.link_id    获客链接的id
        link.link_name  获客链接名称
        link.url        获客链接
        create_time     获客链接创建时间

如为获取更好的跳转体验，也可将获客链接的url调整为scheme使用，方法如下： scheme = weixin://biz/ww/profile/{urlencode(LINK_URL?customer_channel=STATE)}

示例，如果创建的获客链接为https://work.weixin.qq.com/ca/caXXXXX， 希望配置的customer_channel参数为WORK，则生成的scheme为: weixin://biz/ww/profile/https%3A%2F%2Fwork.weixin.qq.com%2Fca%2FcaXXXXX%3Fcustomer_channel%3DWORK

update_link(access_token, hash);

编辑获客链接

SYNOPSIS

https://developer.work.weixin.qq.com/document/path/97297#编辑获客链接

请求说明：

企业可通过此接口编辑获客链接，修改获客链接的关联范围或修改获客链接的名称。

请求包结构体为：

        {
           "link_id":"LINK_ID",
           "link_name":"获客链接1号",
           "range":
           {
                        "user_list":["zhangsan","lisi"],
                        "department_list":[2,3]
           },
           "skip_verify":true
        }

参数说明：

        参数                  必须  说明
    access_token        是       调用接口凭证
        link_id 是       获客链接的id
        link_name       否       更新的链接名称
        range.user_list 否       此获客链接关联的userid列表，最多可关联500个
        range.department_list   否       此获客链接关联的部门id列表，部门覆盖总人数最多500个
        skip_verify     否       是否无需验证，默认为true

range为覆盖更新，覆盖的总人数不能超过500人。

权限说明：

企业需要使用配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。 第三方或代开发应用需具有“企业客户权限->获客助手”权限 不支持客户联系系统应用调用

RETURN 返回结果：

    {
                "errcode": 0,
                "errmsg": "ok"
        }

RETURN 参数说明：

        参数              说明
    errcode     返回码
        errmsg  对返回码的文本描述内容

delete_link(access_token, hash);

删除获客链接

SYNOPSIS

https://developer.work.weixin.qq.com/document/path/97297#删除获客链接

请求说明：

企业可通过此接口删除获客链接，删除后的获客链接将无法继续使用。

请求包结构体为：

        {
           "link_id":"LINK_ID"
        }

参数说明：

        参数                  必须  说明
    access_token        是       调用接口凭证
        link_id 是       获客链接的id

权限说明：

企业需要使用配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。 第三方或代开发应用需具有“企业客户权限->获客助手”权限 不支持客户联系系统应用调用

RETURN 返回结果：

    {
                "errcode": 0,
                "errmsg": "ok"
        }

RETURN 参数说明：

        参数              说明
    errcode     返回码
        errmsg  对返回码的文本描述内容

customer(access_token, hash);

获取由获客链接添加的客户信息 最后更新：2023/10/18

获取获客客户列表

SYNOPSIS

https://developer.work.weixin.qq.com/document/path/97298

请求说明：

企业可通过此接口获取到由指定的获客链接添加的客户列表。

请求包结构体为：

        {
           "link_id":"LINK_ID",
           "limit":1000,
           "cursor":"CURSOR"
        }

参数说明：

        参数                  必须  说明
    access_token        是       调用接口凭证
        link_id 是       获客链接id
        limit   否       返回的最大记录数，整型，最大值1000
        cursor  否       用于分页查询的游标，字符串类型，由上一次调用返回，首次调用可不填

权限说明：

企业需要使用配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。 第三方或代开发应用需具有“企业客户权限->获客助手”权限 不支持客户联系系统应用调用

RETURN 返回结果：

        {
                "errcode": 0,
                "errmsg": "ok",
                "customer_list":
                [
                        {
                                "external_userid":"woAJ2GCAAAXtWyujaWJHDDGi0mACAAA",
                                "userid":"zhangsan",
                                "chat_status":0,
                                "state":"CHANNEL_A"
                        },
                        {       
                                "external_userid":"woAJ2GCAAAXtWyujaWJHDDGi0mACAAA",
                                "userid":"lisi",
                                "chat_status":0,
                                "state":"CHANNEL_B"
                        },
                        {
                                "external_userid":"woAJ2GCAAAXtWyujaWJHDDGi0mBCBBB",
                                "userid":"rocky",
                                "chat_status":1,
                                "state":"CHANNEL_A"
                        }
                ],
                "next_cursor":"CURSOR"
        }

RETURN 参数说明：

        参数              说明
    errcode     返回码
        errmsg  对返回码的文本描述内容
        customer_list.external_userid   客户external_userid
        customer_list.userid    通过获客链接添加此客户的跟进人userid
        customer_list.chat_status       会话状态，0-客户未发消息 1-客户已发送消息 2-客户发送消息状态未知
        customer_list.state     用于区分客户具体是通过哪个获客链接进行添加，用户可在获客链接后拼接customer_channel=自定义字符串，字符串不超过64字节，超过会被截断。通过点击带有customer_channel参数的链接获取到的客户，调用获客信息接口或获取客户详情接口时，返回的state参数即为链接后拼接自定义字符串
        next_cursor     分页游标，再下次请求时填写以获取之后分页的记录，如果已经没有更多的数据则返回空

statistic(access_token, hash);

获客助手额度管理与使用统计 最后更新：2023/08/08

查询链接使用详情

SYNOPSIS

https://developer.work.weixin.qq.com/document/path/97375#查询链接使用详情

请求说明：

企业可通过此接口查询指定获客链接在指定时间范围内的访问情况。

请求包结构体为：

        {
           "link_id":"caxxxxxxx",
           "start_time":1688140800,
           "end_time":1688486400
        }

参数说明：

        参数                  必须  说明
    access_token        是       调用接口凭证
        link_id 是       获客链接的id
        start_time      是       统计起始时间戳
        end_time        是       统计结束时间戳

注意： 1.统计范围的最小粒度为日，将自动转换为时间戳所在日进行统计，区间为闭区间。 2.仅可查询最近180天内的使用记录，起始和结束时间相差不可超过30天

权限说明：

企业需要使用配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）； 第三方或代开发应用需具有“企业客户权限->获客助手”权限 不支持客户联系系统应用调用

RETURN 返回结果：

        {
           "errcode": 0,
           "errmsg": "ok",
           "click_link_customer_cnt":1000,
           "new_customer_cnt":500,
        }

RETURN 参数说明：

        参数              说明
    errcode     返回码
        errmsg  对返回码的文本描述内容
        click_link_customer_cnt 点击链接客户数
        new_customer_cnt        新增客户数