# API加好友

该接口用于"SCRM"自动加好友功能中向系统请求要添加的手机号码信息。使用此接口前请先在SCRM->自动加好友功能中创建规则并获取规则 ID

注意：

调用该接口，实际为添加好友申请任务，并非即时发送好友申请，存在延时为正常现象
具体任务记录可以通过"SCRM"查看

添加好友的默认配置: 若需要调整配置，请联系运营

维度	限定值	说明
起止时间	9:00--21:00	限定之外的时间段，不会执行添加好友任务，未完成的任务次日执行
日上限	100	每个机器人每日允许添加的次数，可以通过增加配置的机器人，增加每日发起总量
请求间隔	4min —— 5min	单个机器人维度的主加执行时间间隔

请求方式：POST

请求地址：https://$basehost/gateway/qopen/AddExtUserByRule

body参数：

{
    "rule_id": "规则ID",
    "ext_user_list":
    [
        {
            "mobile": "手机号码",
            "validation_message": "好友验证信息",
            "tag_list": [
                "企业标签"
            ],
            "mark_id": "标识字段，结果回调中返回(仅支持扫码号)",
        }
    ]
}

字段	类型	必填	说明
rule_id	string	是	规则ID，通过 SCRM 自动加好友中创建规则并获取规则 ID
ext_user_list	array	是	需要添加的好友信息数组，数组长度最大为100
ext_user_list[x].mobile	string	是	手机号码，支持企业微信随机串代替明文手机号
ext_user_list[x].validation_message	string	否	加好友验证信息，不填时取rule_id对应规则的验证信息,最大长度50个字符
ext_user_list[x].tag_list	array	否	企业标签列表，不填时取rule_id对应规则的标签列表
mark_id	string	否	标识字段，结果回调(42012), 成为好友后(20001)中返回

返回值：

{
    "data": {
        "invalid_mobile_list": [],
        "invalid_tag_list": [],
    },
    "errcode": 0,
    "errmsg": "",
    "hint": ""
}

字段	类型	说明
errcode	int	状态码，0为正常，非0代表错误
errmsg	string	错误信息
data	json	json返回值
invalid_mobile_list	array	无效的手机号列表
invalid_tag_list	array	无效的标签列表
hint	string	请求日志ID

完整请求示例：

curl -X POST \
  https://$basehost/gateway/qopen/AddExtUserByRule \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -H 'Token: c2NdxDHKXIJ5j1zrhJeq2eJEHjh9xxx' \
  -d '{
    "rule_id": "规则ID",
    "ext_user_list":
    [
        {
            "mobile": "手机号码",
            "validation_message": "好友验证信息",
            "tag_list": [
                "企业标签"
            ]
        }
    ]
}'

# 随机串置换回调

企业微信提供使用手机号获取随机串的能力，能使用随机串添加对应手机号为好友。
随机串有30分钟的时效性，需要使用随机串添加好友的企业需要实现“置换随机串的api功能”，提供给ql置换随机串
ql检测到随机串过期时会向企业发送随机串过期事件，企业返回置换后的随机串
在后台配置callback地址，当随机串过期后ql向该地址发送事件。 ####注意事项
置换随机串可能会进行多次，每次都是使用最初上传的随机串进行置换，请保留原始随机串

# 随机串过期事件回调结构

encoding_content解密后的结构：

{
    "event_type": 40027,
    "data": {
        hash: "过期随机串"
    }
}

说明

字段	类型	说明
event_type	int	事件类型 40027
hash	string	过期随机串

企业端api返回结构协议

{
    "success": true,
    "message": "操作成功",
    "data":{
        "old_hash": "过期随机串",
        "hash": "有效随机串"
    }
}

# 回调说明

执行成功，返回好友申请执行成功回调-40028，好友申请执行结果回调-42012
执行失败，返回好友申请执行结果回调-42012
使用者根据业务场景接入的回调类型

# 好友申请执行成功回调

注意：

调用接口成功不会立刻返回该回调，而是当好友申请执行成功之后，触发回调。

事件回调结构

encoding_content解密后的结构：

{
    "event_type": 40028,
    "rule_id": "对应的规则id",
    "robot_id": "机器人id",
    "send_time": 1599466270,
    "ext_user_phone": "外部联系人手机号",
    "ext_user_name": "外部联系人用户名",
    "ext_user_avatar": "外部联系人头像url"
}

说明

字段	类型	说明
event_type	int	事件类型，40028
rule_id	string	对应的规则id
robot_id	string	机器人id
send_time	int	unix时间戳
ext_user_phone	string	外部联系人手机号
ext_user_name	string	外部联系人用户名
ext_user_avatar	string	外部联系人头像url

# 好友申请执行结果回调

好友申请执行成功或者失败，都会触发该回调；

注意：

调用接口成功不会立刻返回该回调，而是当好友申请执行之后，触发回调。
MarkId字段仅支持扫码号，需在调用api时传入

事件回调结构

encoding_content解密后的结构：

{
    "event_type": 42012,
    "rule_id": "对应的规则id",
    "robot_id": "机器人id",
    "send_time": 1599466270,
    "ext_user_phone": "外部联系人手机号",
    "ext_user_name": "外部联系人用户名",
    "ext_user_avatar": "外部联系人头像url",
    "mark_id": "业务传入的标识字段(仅支持扫码号)",
    "is_sent" : true,
    "desc": "执行情况描述",
}

说明

字段	类型	说明
event_type	int	事件类型，42012
rule_id	string	对应的规则id
robot_id	string	机器人id
send_time	int	unix时间戳
ext_user_phone	string	外部联系人手机号
ext_user_name	string	外部联系人用户名
ext_user_avatar	string	外部联系人头像url
mark_id	string	业务传入的标识字段(仅支持扫码号)
is_sent	bool	true:执行成功，false:执行失败
desc	string	执行情况描述

← 通过手机号加好友通过扫一扫添加好友（平台号） →