加好友接口

通过手机号加好友接口

POST https://ex-api.botorange.com/addFriend/send

请求示例：

{
  "token": "xxx", // 获取请参考图一
  "phoneNum": "13538551111", // 手机号
  "remark": "用户备注", //自动打上备注， 可选
  "helloMsg": "我是XX，请添加我的企业微信", //邀请语
  "extraInfo": "{}", // 附加信息，回调原样返回
  "userId": "FuLiGuan", // 机器人的userId，不填则由对应小组随机托管账号执行加好友操作
  "instant": true, // 是否是实时执行加好友任务. true代表实时, 开启后不受页面涨粉设置所限制
  "isEncrypt": false // 是否是一个加密的手机号
}

请求参数：

名称	类型	是否必须	备注
token	string	是	调用接口凭证, 获取方式
phoneNum	string	是	手机号
remark	string	否	备注信息
helloMsg	string	是	邀请语
extraInfo	string	否	附加信息，回调原样返回
userId	string	否	机器人的userId，不填则由对应小组随机托管账号执行加好友操作, 详见wxUserId
instant	boolean	否	是否是实时执行加好友任务. true代表实时, 开启后不受页面涨粉设置所限制
isEncrypt	boolean	否	是否是一个加密的手机号加好友

返回示例：

{
  "code": 0, // 请求成功
}

返回参数说明：

参数	类型	必定存在	备注
code	number	是	返回码

添加好友回调

POST ***/friend/send

请求示例：

{
  "code": 0, // 0 发送成功， 1 搜索不到或搜索失败
  "data": {
    "fromwxid": "168...", // 企微号id
    "fromwxName": "张三", // 企微号名称
    "fromwxAvatar": "http://wx.qlogo..", // 企微号头像
    "type": 1, // 1 手机号加好友，2 群聊加好友，3 名片加好友
    "phoneNum": "13538551111", // 手机号（type为1时存在）
    "roomWxid": "R:1111111", // 加好友的群聊wxid（type为2时存在）
    "contactSenderWxid": "12345678", // 发送名片的联系人wxid（type为3时存在）
    "extraInfo": "", //
    "payload": { // 0则返回
      "avatar": "http://wx.qlogo.cn/mmhead/OibRNdtlJ..", // 头像
      "name": "XX", //名字
      "gender": 2, // 性别， 0 未知 1 男 2 女
      "wxid": "788748399949943", // 微信内部id
      "friend": true, // 是否已经是好友
    },
    "createTimestamp": 1620736936935, // 任务创建时间
    "sendTimestamp": 1620736947934, // 好友申请发送时间
    "token": "xxx", // token
    "message": "", // code=1则有返回错误信息
    "errorCode": 165, //code=1则有返回错误信息
  },
}

请求参数：

名称	类型	是否必须	备注
code	number	是	错误码 0表示成功 1表示搜索不到或搜索失败
data.fromwxid	string	是	企微号id, 详见imBotId
data.fromwxName	string	是	企微号名称
data.fromwxAvatar	string	是	企微号头像
data.type	number	是	加好友的方式类型，1: 手机号 2: 群聊加好友 3: 名片加好友
data.phoneNum	string	否	手机号，当type为1的时候存在
data.roomWxid	string	否	群聊的wxid，当type为2的时候存在, 详见roomWxid
data.contactSenderWxid	string	否	发名片的联系人的wxid，当type为3的时候存在, 详见contactWxid
data.extraInfo	string	是	附加信息
data.payload	object	否	当成功时 返回
data.payload.avatar	string	是	头像
data.payload.name	string	是	名字
data.payload.gender	number	是	0:未知 1:男 2:女
data.payload.wxid	string	是	微信内部id, 详见contactWxid
data.payload.friend	boolean	是	是否已经是好友
data.createTimestamp	number	是	当前加好友任务的创建时间
data.sendTimestamp	number	是	当前加好友任务的好友请求发送时间
data.message	string	否	当有问题时 返回错误信息
data.errorCode	number	否	165搜索好友失败(手机号没注册微信/隐私设置), 166 请求太频繁被限制

好友通过后回调

POST ***/friend/confirm

请求示例：

{
  "code": 0, // 0 成功
  "data": {
    "fromwxid": "16837362837774", // 所属微信id
    "token": "xxx", // 请求的token
    "wxid": "788748399949943", // 通过请求的好友微信内部id
    "phoneNum": "13538551111",
    "remark": "用户备注",
    "helloMsg": "我是张敏，请添加我的企业微信",
    "extraInfo": "{}", //附加信息
    "externalUserId": "wo4JW7EQAAQHKG9u_m4da3zq0hSJd5ee"
  },
  "message": ""
}

请求参数：

名称	类型	是否必须	备注
code	number	是	错误码 0表示成功
data.fromwxid	string	是	所属微信id, 详见imBotId
data.token	string	是	请求的token, 获取方式
data.wxid	string	是	通过请求的好友微信内部id, 详见contactWxid
data.phoneNum	string	否	添加的手机号
data.roomWxid	string	否	群聊加好友的群wxid, 详见roomWxid
data.contactSenderWxid	string	否	名片加好友的发名片的好友的wxid, 详见contactWxid
data.remark	string	是	用户备注
data.helloMsg	string	是	邀请语
data.extraInfo	string	是	附加信息
data.externalUserId	string	否	客户的externalUserId, 详见externalUserId
message	string	否	当有问题时 返回错误信息

TIP

wxid 是唯一的，phoneNum 不一定唯一

群聊加好友接口

POST https://ex-api.botorange.com/addFriend/room/send

请求示例：

{
  "token": "xxx",
  "roomId": "R:10696049576015462", // 群聊wxid，该id在微信里唯一
  "contactId": "1688849967837780", // 群成员wxid
  "remark": "备注", //
  "helloMsg": "我是XX，请添加我的企业微信", //邀请语
  "extraInfo": "{}", // 附加信息，回调原样返回
  "userId": "FuLiGuan", // 机器人的userId，必须保证该托管账号在传入的群聊中
}

请求参数:

名称	类型	是否必须	备注
token	string	是	调用接口凭证, 获取方式
roomId	string	是	群聊wxid，该id在微信里唯一, 详见roomWxid
contactId	string	是	群成员wxid, 详见contactWxid
remark	string	否	备注信息
helloMsg	string	是	邀请语
extraInfo	string	否	附加信息
userId	string	是	机器人的userId，必须保证该托管账号在传入的群聊中, 详见wxUserId

返回示例:

{
  "code": 0, // 请求成功
}

返回参数说明：

参数	类型	必定存在	备注
code	number	是	返回码

code错误码说明

错误码	说明
0	成功
-1	托管账号不存在
-2	托管账号不在群聊内
-3	群聊不存在
-4	群成员不存在

通过企微id进行群聊加好友接口

POST https://ex-api.botorange.com/addFriend/room/sendByWecom

请求示例：

{
  "token": "xxx",
  "wecomChatId": "wrBkHDEQAAUrHK77bJU9z1hLinfNROca",
  "externalUserId": "wo4JW7EQAAQHKG9u_m4da3zq0hSJd5ee",
  "remark": "备注", //
  "helloMsg": "我是XX，请添加我的企业微信", //邀请语
  "extraInfo": "{}", // 附加信息，回调原样返回
  "wecomUserId": "FuLiGuan",
}

请求参数:

名称	类型	是否必须	备注
token	string	是	调用接口凭证, 获取方式
wecomChatId	string	是	企微的群chatId, 详见wecomChatId
externalUserId	string	是	企微的客户id, 详见externalUserId
remark	string	否	备注信息
helloMsg	string	是	邀请语
extraInfo	string	否	附加信息
wecomUserId	string	是	机器人的企微userId，必须保证该托管账号在传入的群聊中, 详见wxUserId

注意

因为涉及到数据修改，此接口支持 2022-08-26 之后登录的新账号。
历史托管账号想要使用此接口的，需要在 客户分层 -> 同步已有群聊 来更新数据，然后才可以使用该接口。

返回示例:

{
  "code": 0, // 请求成功
}

返回参数说明：

参数	类型	必定存在	备注
code	number	是	返回码

code错误码说明

错误码	说明
0	成功
-1	托管账号不存在
-2	托管账号不在群聊内
-3	群聊不存在
-4	群成员不存在

手机号加密接口

注意

这个接口是需要用户自行开发的接口，当在系统中使用加密手机号加好友功能的时候，用户需要实现这个接口，并把这个接口的调用地址配置在后台中

系统在发送加好友请求的时候，会调用这个接口，将原本加密的手机号id传过来，用户通过自己实现的逻辑，将这个加密手机号id换成一个明文手机号，或是一个通过企微接口进行加密的加密手机号

系统将根据用户返回的结果来发送加好友请求，以达到界面上完全不保存具体手机号的目的，保护用户的数据安全

GET ${加密助手地址}/phone/encrypt?id=${id}&token=${token}

请求 query 参数

参数	类型	必定存在	备注
id	string	是	加密手机号的 id，用户需要根据这个 id 来唯一定位到一个手机号
token	string	是	小组级接口的 token，可以在【聊天工作台 -> 智能对话 -> API 接入】 处获取到这个值

返回参数

{
  "data": {
    "encryptPhone": "1231231231"
  }
}

参数	类型	必定存在	备注
data.encryptPhone	string	是	明文手机号或通过企微接口获取的加密手机号

额外健康检查接口

注意

在后台配置这个加密助手地址的时候，系统会自动检测这个地址是否可以调用，如果发现填入的地址无法调用通过，则无法配置成功，下面这个接口就是系统会在配置的时候自动调用的接口地址和返回参数，如果收到的返回值不符合要求，也会认为当前配置的地址不可用

这样的设计是为了防止填入错误地址导致功能无法正常运行

GET ${加密助手地址}/health

返回数据

{
  code: 0
}