第三方应用开发 服务端API 客户联系 联系我与客户入群方式 客户联系「联系我」管理
客户联系「联系我」管理
最后更新:2023/12/01
可联系渠道经理采购或代理智慧硬件接口已支持设备 联系渠道经理
客户联系「联系我」管理
最后更新:2023/12/01

目录

  • 权限说明
  • 配置客户联系「联系我」方式
  • 获取企业已配置的「联系我」方式
  • 获取企业已配置的「联系我」列表
  • 更新企业已配置的「联系我」方式
  • 删除企业已配置的「联系我」方式
  • 结束临时会话
  • 结束语定义
  • 附录
  •  

    权限说明

    调用接口的应用需要满足如下的权限:

    应用类型权限要求
    自建应用配置到「客户联系 可调用接口的应用」中
    代开发应用具有「配置「联系我」二维码」权限
    第三方应用具有「配置「联系我」二维码」权限
    • 传入的成员和部门需要在此应用的可见范围内。
    • 配置的使用成员必须在企业微信激活且已经过实名认证且配置了客户联系功能。。
    • 临时会话的二维码具有有效期,添加企业成员后仅能在指定有效期内进行会话,仅支持医疗行业企业创建。
      临时会话模式可以配置会话结束时自动发送给用户的结束语。

     

    配置客户联系「联系我」方式

    企业可以在管理后台-客户联系-加客户中配置成员的「联系我」的二维码或者小程序按钮,客户通过扫描二维码或点击小程序上的按钮,即可获取成员联系方式,主动联系到成员。
    企业可通过此接口为具有客户联系功能的成员生成专属的「联系我」二维码或者「联系我」按钮。
    如果配置的是「联系我」按钮,需要开发者的小程序接入小程序插件

    注意:
    通过API添加的「联系我」不会在管理端进行展示,每个企业可通过API最多配置50万个「联系我」。
    用户需要妥善存储返回的config_id,config_id丢失可能导致用户无法编辑或删除「联系我」
    临时会话模式不占用「联系我」数量,但每日最多添加10万个,并且仅支持单人。
    临时会话模式的二维码,添加好友完成后该二维码即刻失效。

     

    请求方式:POST(HTTPS
    请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/add_contact_way?access_token=ACCESS_TOKEN

    请求示例:

    {
       "type" :1,
       "scene":1,
       "style":1,
       "remark":"渠道客户",
       "skip_verify":true,
       "state":"teststate",
       "user" : ["zhangsan", "lisi", "wangwu"],
       "party" : [2, 3],
       "is_temp":true,
       "expires_in":86400,
       "chat_expires_in":86400,
       "unionid":"oxTWIuGaIt6gTKsQRLau2M0AAAA",
       "is_exclusive":true,
       "conclusions":
       {
    		"text": 
    		{
    			"content":"文本消息内容"
    		},
        	"image": 
    		{
            	"media_id": "MEDIA_ID"
       		},
        	"link":
    		{
            	"title": "消息标题",
            	"picurl": "https://example.pic.com/path",
            	"desc": "消息描述",
            	"url": "https://example.link.com/path"
        	},
        	"miniprogram":
    		{
            	"title": "消息标题",
    			"pic_media_id": "MEDIA_ID",
            	"appid": "wx8bd80126147dfAAA",
            	"page": "/path/index.html"
        	}
       }
    }

    参数说明:

    参数必须说明
    access_token调用接口凭证
    type联系方式类型,1-单人, 2-多人
    scene场景,1-在小程序中联系,2-通过二维码联系
    style在小程序中联系时使用的控件样式,详见附表
    remark联系方式的备注信息,用于助记,不超过30个字符
    skip_verify外部客户添加时是否无需验证,默认为true
    state企业自定义的state参数,用于区分不同的添加渠道,在调用“获取外部联系人详情”时会返回该参数值,不超过30个字符
    user使用该联系方式的用户userID列表,在type为1时为必填,且只能有一个
    party使用该联系方式的部门id列表,只在type为2时有效
    is_temp是否临时会话模式,true表示使用临时会话模式,默认为false
    expires_in临时会话二维码有效期,以秒为单位。该参数仅在is_temp为true时有效,默认7天,最多为14天
    chat_expires_in临时会话有效期,以秒为单位。该参数仅在is_temp为true时有效,默认为添加好友后24小时,最多为14天
    unionid可进行临时会话的客户unionid,该参数仅在is_temp为true时有效,如不指定则不进行限制
    is_exclusive是否开启同一外部企业客户只能添加同一个员工,默认为否,开启后,同一个企业的客户会优先添加到同一个跟进人
    conclusions结束语,会话结束时自动发送给客户,可参考“结束语定义”,仅在is_temp为true时有效
    注意,每个联系方式最多配置100个使用成员(包含部门展开后的成员)
    当设置为临时会话模式时(即is_temp为true),联系人仅支持配置为单人,暂不支持多人
    使用unionid需要调用方(企业或服务商)的企业微信“客户联系”中已绑定微信开发者账户

     

    返回结果:

    {
       "errcode": 0,
       "errmsg": "ok",
       "config_id":"42b34949e138eb6e027c123cba77fAAA",
       "qr_code":"http://p.qpic.cn/wwhead/duc2TvpEgSdicZ9RrdUtBkv2UiaA/0"
    }

    参数说明:

    参数说明
    errcode返回码
    errmsg对返回码的文本描述内容
    config_id新增联系方式的配置id
    qr_code联系我二维码链接,仅在scene为2时返回

     

    获取企业已配置的「联系我」方式

    获取企业配置的「联系我」二维码和「联系我」小程序按钮。
    请求方式:POST(HTTPS
    请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_contact_way?access_token=ACCESS_TOKEN

    请求示例:

    {
       "config_id":"42b34949e138eb6e027c123cba77fad7"
    }

    参数说明:

    参数必须说明
    access_token调用接口凭证
    config_id联系方式的配置id

     

    返回结果:

    {
       "errcode": 0,
       "errmsg": "ok",
       "contact_way":
        {
            "config_id":"42b34949e138eb6e027c123cba77fAAA",
            "type":1,
            "scene":1,
            "style":2,
    		"remark":"test remark",
    		"skip_verify":true,
    		"state":"teststate",
    		"qr_code":"http://p.qpic.cn/wwhead/duc2TvpEgSdicZ9RrdUtBkv2UiaA/0",
    		"user" : ["zhangsan", "lisi", "wangwu"],
            "party" : [2, 3],
    		"is_temp":true,
    		"expires_in":86400,
            "chat_expires_in":86400,
    		"unionid":"oxTWIuGaIt6gTKsQRLau2M0AAAA",
    		"conclusions":
    		{
        		"text": 
    			{
    				"content":"文本消息内容"
    			},
        		"image": 
    			{
    				"pic_url": "http://p.qpic.cn/pic_wework/XXXXX"
        		},
       		 	"link": 
    			{
    				"title": "消息标题",
            		"picurl": "https://example.pic.com/path",
            		"desc": "消息描述",
            		"url": "https://example.link.com/path"
        		},
        		"miniprogram": 
    			{
            		"title": "消息标题",
    				"pic_media_id": "MEDIA_ID",
           			 "appid": "wx8bd80126147dfAAA",
            		"page": "/path/index"
       			}
       		}
        }
    }

    参数说明:

    参数说明
    errcode返回码
    errmsg对返回码的文本描述内容
    config_id新增联系方式的配置id
    type联系方式类型,1-单人,2-多人
    scene场景,1-在小程序中联系,2-通过二维码联系
    is_temp是否临时会话模式,默认为false,true表示使用临时会话模式
    remark联系方式的备注信息,用于助记
    skip_verify外部客户添加时是否无需验证
    state企业自定义的state参数,用于区分不同的添加渠道,在调用“获取外部联系人详情”时会返回该参数值
    style小程序中联系按钮的样式,仅在scene为1时返回,详见附录
    qr_code联系二维码的URL,仅在scene为2时返回
    user使用该联系方式的用户userID列表
    party使用该联系方式的部门id列表
    expires_in临时会话二维码有效期,以秒为单位
    chat_expires_in临时会话有效期,以秒为单位
    unionid可进行临时会话的客户unionid
    conclusions结束语,可参考“结束语定义

     

    获取企业已配置的「联系我」列表

    获取企业配置的「联系我」二维码和「联系我」小程序插件列表。不包含临时会话。
    注意,该接口仅可获取2021年7月10日以后创建的「联系我」
    请求方式:POST(HTTPS
    请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/list_contact_way?access_token=ACCESS_TOKEN

    请求示例:

    {
       "start_time":1622476800,
       "end_time":1625068800,
       "cursor":"CURSOR",
       "limit":1000
    }

    参数说明:

    参数必须说明
    access_token调用接口凭证
    start_time「联系我」创建起始时间戳, 默认为90天前
    end_time「联系我」创建结束时间戳, 默认为当前时间
    cursor分页查询使用的游标,为上次请求返回的 next_cursor
    limit每次查询的分页大小,默认为100条,最多支持1000条

     

    返回结果:

    {
       "errcode": 0,
       "errmsg": "ok",
        "contact_way":
    	[
    		{
    			"config_id":"534b63270045c9ABiKEE814ef56d91c62f"
    		}
    		{
    			"config_id":"87bBiKEE811c62f63270041c62f5c9A4ef"
    		}
    	],
    	"next_cursor":"NEXT_CURSOR"
    }

    参数说明:

    参数说明
    errcode返回码
    errmsg对返回码的文本描述内容
    contact_way.config_id联系方式的配置id
    next_cursor分页参数,用于查询下一个分页的数据,为空时表示没有更多的分页

     

    更新企业已配置的「联系我」方式

    更新企业配置的「联系我」二维码和「联系我」小程序按钮中的信息,如使用人员和备注等。

    请求方式:POST(HTTPS
    请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/update_contact_way?access_token=ACCESS_TOKEN

    请求示例:

    {
       "config_id":"42b34949e138eb6e027c123cba77fAAA",
       "remark":"渠道客户",
       "skip_verify":true,
       "style":1,
       "state":"teststate",
       "user" : ["zhangsan", "lisi", "wangwu"],
       "party" : [2, 3],
        "expires_in":86400,
        "chat_expires_in":86400,
    	 "unionid":"oxTWIuGaIt6gTKsQRLau2M0AAAA",
    	 "conclusions":
    	 {
        	"text":
    		{
    			"content":"文本消息内容"
    		},
        	"image": 
    		{
            	"media_id": "MEDIA_ID"
        	},
        	"link": 
    		{
            	"title": "消息标题",
            	"picurl": "https://example.pic.com/path",
            	"desc": "消息描述",
            	"url": "https://example.link.com/path"
        	},
        	"miniprogram": 
    		{
            	"title": "消息标题",
    			"pic_media_id": "MEDIA_ID",
            	"appid": "wx8bd80126147dfAAA",
            	"page": "/path/index"
        	}
       }
    }

    参数说明:

    参数必须说明
    access_token调用接口凭证
    config_id企业联系方式的配置id
    remark联系方式的备注信息,不超过30个字符,将覆盖之前的备注
    skip_verify外部客户添加时是否无需验证
    style样式,只针对“在小程序中联系”的配置生效
    state企业自定义的state参数,用于区分不同的添加渠道,在调用“获取外部联系人详情”时会返回该参数值
    user使用该联系方式的用户列表,将覆盖原有用户列表
    party使用该联系方式的部门列表,将覆盖原有部门列表,只在配置的type为2时有效
    expires_in临时会话二维码有效期,以秒为单位,该参数仅在临时会话模式下有效
    chat_expires_in临时会话有效期,以秒为单位,该参数仅在临时会话模式下有效
    unionid可进行临时会话的客户unionid,该参数仅在临时会话模式有效,如不指定则不进行限制
    conclusions结束语,会话结束时自动发送给客户,可参考“结束语定义”,仅临时会话模式(is_temp为true)可设置
    注意:已失效的临时会话联系方式无法进行编辑
    当临时会话模式时(即is_temp为true),联系人仅支持配置为单人,暂不支持多人

    返回结果:

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

    参数说明:

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

     

    删除企业已配置的「联系我」方式

    删除一个已配置的「联系我」二维码或者「联系我」小程序按钮。
    请求方式:POST(HTTPS
    请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/del_contact_way?access_token=ACCESS_TOKEN

    请求示例:

    {
    	"config_id":"42b34949e138eb6e027c123cba77fAAA"
    }

    参数说明:

    参数必须说明
    access_token调用接口凭证
    config_id企业联系方式的配置id

     

    返回结果:

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

    参数说明:

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

    结束临时会话

    将指定的企业成员和客户之前的临时会话断开,断开前会自动下发已配置的结束语。
    请求方式:POST(HTTPS
    请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/close_temp_chat?access_token=ACCESS_TOKEN

    请求示例:

    {
    	"userid":"zhangyisheng",
    	"external_userid":"woAJ2GCAAAXtWyujaWJHDDGi0mACHAAA"
    }

    参数说明:

    参数必须说明
    access_token调用接口凭证
    userid企业成员的userid
    external_userid客户的外部联系人userid
    注意:请保证传入的企业成员和客户之间有仍然有效的临时会话, 通过其他方式的添加外部联系人无法通过此接口关闭会话

     

    返回结果:

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

    参数说明:

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

     

    结束语定义

    字段内容:

    "conclusions":
    {
    	"text":
    		{
    			"content":"文本消息内容"
    		},
        	"image": 
    		{
            	"media_id": "MEDIA_ID",
    			"pic_url": "http://p.qpic.cn/pic_wework/XXXXX"
        	},
        	"link": 
    		{
            	"title": "消息标题",
            	"picurl": "https://example.pic.com/path",
            	"desc": "消息描述",
            	"url": "https://example.link.com/path"
        	},
        	"miniprogram": 
    		{
            	"title": "消息标题",
    			"pic_media_id": "MEDIA_ID",
            	"appid": "wx8bd80126147dfAAA",
            	"page": "/path/index"
        	}
       }
    }

    参数说明:

    参数说明
    text.content消息文本内容,最长为4000字节
    image.media_id图片的media_id
    image.pic_url图片的url
    link.title图文消息标题,最长为128字节
    link.picurl图文消息封面的url
    link.desc图文消息的描述,最长为512字节
    link.url图文消息的链接
    miniprogram.title小程序消息标题,最长为64字节
    miniprogram.pic_media_id小程序消息封面的mediaid,封面图建议尺寸为520*416
    miniprogram.appid小程序appid,必须是关联到企业的小程序应用
    miniprogram.page小程序page路径
    text、image、link和miniprogram四者不能同时为空;
    text与另外三者可以同时发送,此时将会以两条消息的形式触达客户;
    image、link和miniprogram只能有一个,如果三者同时填,则按image、link、miniprogram的优先顺序取参,也就是说,如果image与link同时传值,则只有image生效;
    media_id可以通过素材管理接口获得;
    构造结束语使用image消息时,只能填写meida_id字段,获取含有image结构的联系我方式时,返回pic_url字段。

     

    附录

    企业微信为“在小程序中联系”按钮提供了如下的默认样式,用户可根据需要自行选择,style参数和样式的对应关系如下:
    单人类型:
    样式1(style=1):
    样式2(style=2):
    样式3(style=3):
    多人类型:
    样式1(style=1):
    样式2(style=2):

    上一篇
    客户群opengid转换
    下一篇
    客户群「加入群聊」管理