# API加好友

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

注意:

  1. 调用该接口,实际为添加好友申请任务,并非即时发送好友申请,存在延时为正常现象
  2. 具体任务记录可以通过"圈客宝"/"企客宝"查看

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

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

请求方式:POST

请求地址:https://api.aquanliang.com/gateway/qopen/AddExtUserByRule

body参数

{
    "rule_id": "规则ID",
    "ext_user_list":
    [
        {
            "mobile": "手机号码",
            "validation_message": "好友验证信息",
            "tag_list": [
                "企业标签"
            ],
            "mark_id": "标识字段,结果回调中返回(仅支持扫码号)",
        }
    ]
}
字段 类型 必填 说明
rule_id string 规则ID,通过 圈客宝/企客宝 自动加好友中创建规则并获取规则 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 标识字段,结果回调中返回(仅支持扫码号)

返回值:

{
    "data": {
        "invalid_mobile_list": [],
        "invalid_tag_list": [],
    },
    "errcode": 0,
    "errmsg": ""
}
字段 类型 说明
errcode int 状态码,0为正常,非0代表错误
errmsg string 错误信息
invalid_mobile_list array 无效的手机号列表
invalid_tag_list array 无效的标签列表

完整请求示例:

curl -X POST \
  https://api.aquanliang.com/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
  • 使用者根据业务场景接入的回调类型

# 好友申请执行成功回调

注意:

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

事件回调结构

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

# 好友申请执行结果回调

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

注意:

  1. 调用接口成功不会立刻返回该回调,而是当好友申请执行之后,触发回调。
  2. 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 事件类型,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
mark_id string 业务传入的标识字段(仅支持扫码号)
is_sent bool true:执行成功,false:执行失败
desc string 执行情况描述