WeTool HOOK 智群管家接口文档

发布专员

WeTool 智群管家接口文档
智群管家接口文档

从智群管家客户端4.1.0版本开始，提供三方服务接口对接能力。请联系智群工作人开通权限，权限开通后在后台配置回调地址。

(回调地址设置界面)

三方提供回调地址（如 http://xxx/zhiqun/callback），智群向回调地址发送post请求，包括定时的轮询(pull_task)请求以及各种事件上报（如：上报好友和群消息，群成员变化，好友变化，好友信息变更等）。

回调服务收到请求后，可以根据请求的具体内容做出响应，返回各种任务（如：发送消息，踢人等）。

(智群客户端和三方回调服务通讯示例)

智群客户端和回调服务之间使用json数据格式通讯，utf-8编码。

请求格式

智群客户端向回调地址发起http post请求

header:

Content-Type: application/json; charset=UTF-8

body:

{
  "action": "",//接口名
  "wxid": "",  //当前登录的wxid
  "data": {}   //接口对应的数据
}

响应格式

header:

Content-Type: application/json; charset=UTF-8

body:

{
  "error_code": 0,      //整型，0代表没有错误
  "error_reason": "",   //出错原因的描述
  "ack_type":"xxx_ack", //和请求的action对应   
  "data":{}             //ack_type对应的数据
}


请求接口轮询任务

该请求是由客户端向贵司服务端轮询发起的，目的是接收服务端下发的任务，如：发送消息给好友或群等。具体请参考task文档。

请求action: pull_task

data内容：无。

客户端定时发起pull_task请求，间隔可通过login_ack设置，最小1秒，默认5秒。

响应ack_type: pull_task_ack

data内容单个任务。

data内容：

	描述
task	单个任务

示例：向客户端下发一个踢人任务。

{
    "error_code": 0,                    
    "error_reason": "",     
    "ack_type":"pull_task_ack",         
    "data":
    {
        "task_id": "aaaa111222",   
        "task_data":
        {
           "task_type":2,
           "task_dict":
           {
              "room_wxid":"bcdef@chatroom",
              "wxid":"wxid_abc"      
           }
        }
    }
}

任务执行结果

请求action: report_task_result

data内容：

字段	描述
task_id	pull_task下发的task_id
task_result	0,任务执行失败,1任务执行成功
error_reason	为什么执行失败,若任务执行成功则为空

任务执行成功只意味着客户端"把数据交给微信客户端"，不代表微信已经执行成功。

微信后台会对数据(微信号的用户行为)做各种判断和过滤，若触发了微信的相关限制，最终的结果会是失败的(比如发送了一段含政治敏感的聊天文本，微信检测到了会拦截这则消息，对方会无法收到这则消息)。

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

示例：

{
  "error_code": 0,
  "error_reason": "",
  "ack_type": "common_ack",
  "data": {
      "reply_task_list":[
          {
            "task_type": 1,  
            "task_dict":
            {
                "wxid_to":"filehelper",
                "msg_list":[
                    {
                    "msg_type": 1,
                    "msg":"测试发送结果",
                    "customid":"test001"
                    }
                ]
            }
        }
      ]
  }
}


上线登录

请求action: login

软件和微信登录成功后上报。

data内容：

字段	描述
nickname	微信昵称
wx_alias	微信号（没用设置过微信号的为空）
head_img	微信头像url
client_version	智群客户端版本号
zq_username	当前客户端登录的智群账号(4.4.0 新增)

示例：

{
    "action" : "login",
    "wxid" : "wxid_fo1039029348sfj",
    "data" : {
      "nickname": "Bill",
      "wx_alias": "mccbill",
      "head_img": "http://xxxxxx",
      "client_version":"xxxxxx"
    }
}

响应ack_type: login_ack

data内容

字段		描述
option	flag_report_contact	定义report_contact上报的数据内容 0：不上报 1：好友列表 2：群列表 3：好友+群 4：公众号列表 5：好友+公众号 6：群+公众号 7：好友+群+公众号 默认7，全部上传。
	pull_task_interval	pull_task轮询间隔(秒)，最少1秒。默认5秒。
	upload_file_url	文件上传地址。 收到图片、视频、文件等消息时，是否需要上传，如果需要请指定文件上传地址。 具体实现方式，请参考文件上传

示例1：

使用默认设置：上报好友+群+公众号，pull_task轮询间隔5秒

{
  "error_code": 0,                       
  "error_reason": "",                    
  "ack_type":"login_ack",
  "data":{
     "option":{}
  }
}

示例2：

上报好友+群，pull_task轮询间隔1秒，文件上传地址http://xxxx/zhiqun/upload

{
  "error_code": 0,                       
  "error_reason": "",                    
  "ack_type":"login_ack",
  "data":{
     "option":{
        "flag_report_contact":3,
        "pull_task_interval":1,
        "upload_file_url":"http://xxxx/zhiqun/upload"
    }
  }
}

下线登出

请求action: logout

软件或微信退出登录时上报。

data内容：

字段	描述
client_version	客户端版本号

示例：

{
    "action":"logout",
    "wxid": "wxid_xxxxxxx",
    "data":{
       "client_version":"4.0.0"   
    }
}

响应ack_type: logout_ack

data内容： 无。 客户端主动上报的下线事件，无需响应。

上报通讯录

请求action: report_contact

login接口成功后，根据login接口返回的flag_report_contact上报。

data内容：

字段		描述
friend_list	[userinfo]	userinfo数组
group_list	[roominfo]	roominfo数组
public_list	[]	数组，以下为数组中的对象字段
	wxid	公众号id
	wx_alias	公众号名称
	head_img	头像url

示例：

{
  "action":"report_contact",
  "wxid": "wxid_xxxxxxx",
  "data":{
    "friend_list":[
        {
            "wxid":"wxid_xxxxxxx",
            "wx_alias":"abcd",
            "nickname":"昵称",
            "remark_name":"备注",
            "head_img":"http://xxxx",
            "sex":1,
            "country":"CN",
            "province":"ZheJiang",
            "city":"HangZhou",
            "label_id_list":"1,2,3"
        }
    ],
    "group_list":[
        {
            "wxid":"1234564322@chatroom",
            "room_wxid":"1234564322@chatroom",
            "name":"智群对接1群",
            "owner_wxid":"wxid_xxxxx",
            "member_count":100,
            "head_img":"http://xxxx",
            "member_wxid_list":["wxid_xxx","wxid_xxxx"]
        }
    ],
    "public_list":[
        {
            "wxid":"gh_xxxx",
            "nickname":"腾讯游戏",
            "head_img":"http://xxxx"
        }
    ]
  }
}

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

好友信息变更

请求action: report_contact_update

当好友信息或群名称发生变更时上报。

data内容：

字段		描述
update_list	[userinfo,roominfo]	数组，变更的好友和群列表。

示例：

{
    "action": "report_contact_update",
    "wxid": "wxid_xxxxxxx",
    "data": {
        "update_list": [
            {
                "wxid": "wxid_xxxxxxx",
                "wx_alias": "abcd",
                "nickname": "昵称",
                "remark_name": "备注",
                "head_img": "http://xxxx",
                "sex": 1,
                "country": "CN",
                "province": "ZheJiang",
                "city": "HangZhou"
            },
            {
                "wxid": "1234564322@chatroom",
                "room_wxid": "1234564322@chatroom",
                "name": "智群对接1群",
                "owner_wxid": "wxid_xxxxx",
                "member_count": 100,
                "head_img": "http://xxxx",
                "member_wxid_list": [
                    "wxid_xxx",
                    "wxid_xxxx"
                ]
            }
        ]
    }
}

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

群成员信息详情

请求action: report_room_member_info

回调接口通过下发“上报群成员信息”任务触发。

data内容：

字段		描述
room_data_list	room_wxid	群wxid
	name	群名称
	owner_wxid	群主wxid
	head_img	群头像url
	member_count	群人数
	memberInfo_list	[memberInfo]

示例:

{
    "action":"report_room_member_info",
    "wxid" : "wxid_fo1039029348sfj",
    "data" : {
       "room_data_list":[
           {
              "room_wxid":"xxxxx1@chatroom",  
              "name":"xxxx",
              "owner_wxid":"xxxxx",
              "head_img":"http://xxxxxxx",
              "member_count": 100,
              "memberInfo_list":[
                {
                    "wxid":"wxid_xxxx",
                    "wx_alias":"abcd",
                    "nickname":"昵称",
                    "room_nickname":"群昵称",
                    "head_img":"http://xxxxx",
                    "sex": 0
                }
              ]
           },
           ........
       ]
    }
}

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

群人数变化

请求action: report_room_member_change

群成员增加或减少时上报。

data内容：

字段	描述
room_wxid	群wxid
owner_wxid	群主wxid
wxid_list	变化的成员wxid列表["wxid_xxx","wxid_xxxxx"]
increase_member_list	新增的群成员信息 [memberInfo]
flag	0减少，1增加

示例：

{
    "action":"report_room_member_change",
    "wxid": "wxid_xxxxxxx",
      "data":{
        "room_wxid":"xxxxxxx@chatroom",
        "owner_wxid":"xxxxx",
        "wxid_list";["xxxxxx","xxxxx"],
        "flag": 0
      }
}

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

群成员信息更新

请求action: report_room_member_update

群成员信息更新时自动上报。

data内容：

字段	描述
room_wxid	群wxid
memberInfo_list	信息变化的群成员信息 [memberInfo]

示例：

{
    "action":"report_room_member_update",
    "wxid": "wxid_xxxxxxx",
      "data":{
        "room_wxid":"xxxxxxx@chatroom",
        "memberInfo_list":[
            {
                "wxid":"wxid_xxxx",
                "nickname":"昵称",
                "room_nickname":"群昵称",
                "head_img":"http://xxxxx"
            }
        ]
      }
}

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

上报新群

请求action: report_new_room

当发现新群时时上报。如新建群或被拉入群。

data内容：

字段	描述
wxid	群wxid
name	群名称
owner_wxid	群主wxid
head_img	群头像url
memberInfo_list	群成员列表[memberInfo]

示例：

{
    "action":"report_new_room",
    "wxid": "wxid_xxxxxxx",
      "data":{
        "wxid":"xxxxx",   
        "name":"xxxx",     
        "owner_wxid":"xxxxx",
        "head_img":"xxxx",  
        "memberInfo_list":[$memberInfo,$memberInfo,.....]
      }
}

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

群减少

请求action: report_room_removed

退出群聊或者被移出群聊时上报。

data内容：

字段	描述
wxid_removed	退出的群

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

上报消息

请求action: report_new_msg

上报收到和发送的消息。

data内容：

字段	描述
msg	report_msgunit

示例：

{
    "action" : "report_new_msg",
    "wxid" : "wxid_fo1039029348sfj",
    "data" : {
      "msg": $report_msgunit       //上报单条消息
    }
}

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

加好友请求

请求action: report_friend_add_request

收到添加好友的请求(此时对方还不是我的好友,不能给对方发消息)

微信系统对每个账号每天通过的好友请求有限制。

服务端需要储存(v1,v2) 值, 以便通过任务下发的方式通过好友验证

data内容：

字段	描述
v1	若要自动通过,请在ack中回传
v2	若要自动通过,请在ack中回传
notice_word	新好友加我时的打招呼的内容,可能为空
raw_msg	微信中的原始消息,xml格式

若要自动通过好友验证,可在reply_task_list字段中加入"通过好友验证"的任务(task_type为13)

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

删除好友通知

请求action: report_friend_removed

当某个好友被删除了会上报该事件

data内容：

字段	描述
wxid_removed	被删除好友的wxid

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

新好友通知

请求action: report_new_friend

每当有新的好友时,上报新好友的个人信息(此时对方已经成为了我的好友)

data内容：

字段	描述
fans_wxid	新好友wxid
wx_alias	好友微信号，可能为空
nickname	好友昵称
head_img	头像url
notice_word	新好友加我时的打招呼的内容,可能为空
sourceusername	推荐人的wxid,可能为空
sourcenickname	推荐人昵称,可能为空

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

好友信息

请求action: report_user_info

上报具体某个微信好友的详情。

上报时机：回调服务下发16任务(获取单个好友信息)后上报。

data内容：userinfo

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表

微信标签

请求action: report_tag_info

上报完整的微信标签列表。

上报时机：

1、  下发20任务（上报标签列表）

2、  通过客户端修改标签，或者通过接口修改标签。手机上修改标签不会自动上报，请下发20任务重新获取。

data内容：

字段		类型	描述
meta_tag_list		[]	标签列表
	tag_id	number	标签id
	tag_name	string	标签名称

响应ack_type: common_ack

common_ack为通用响应类型，data内容可以为各种任务。

data内容：

字段		描述
reply_task_list	[task]	数组，任务列表