04/29/2024 11:54:53

群组

详细的工会群流程、权限申请说明，可参见 群组模块 。

一、工会绑群（手Q）

工会会长创建并直接绑定 QQ 群（使用时需要申请权限）。

1.1 接口名

/v2/group/create_bind_group

1.2 请求参数

1.3 返回参数

1.4 请求示例

• 请求

   {
        "openid":"D08BF5F51A67414795F602000B000000",
        "token":"6A27E8C2B4EB505BB6D4A230BDDEF00A",
        "guild_id":"2134",
        "guild_name":"testitop",
        "zone_id":"1",
        "roleid":"2"
    }
  

• 回包

    {
        "ret":0,
        "msg":"",
        "groupid":"735088906",
        "group_name":"testitop"
    }
  

二、查询群关系（手Q或微信）

当工会已绑定群后，调用该接口查询用户与群关系信息接口；可返回用户与群的关系（群主、管理员、普通成员，非成员）信息（使用时需要申请权限）。

2.1 接口名

/v2/group/get_group_rela_info

2.2 请求参数

注意：不要混淆 groupid 和 guild_id ，前者是 QQ 群 ID，后者是游戏中的工会 ID。

2.3 返回参数

2.4 请求示例

• 请求

    {
        "openid":"D08BF5F51A67414795F602000B000000",
        "token":"6A27E8C2B4EB505BB6D4A230BDDEF00A",
        "groupid":"735088906"
    }
  

• 回包

    {
        "ret":0,
        "msg":"",
        "relation":1
    }
  

三、加入已存在的群（手Q）

游戏内工会成员加入 QQ 群接口；调用该接口前，先调用 /v2/group/get_group_info 接口查询用户是否是群成员，当用户为非群成员身份时，显示加群按钮（新）（使用时需要申请权限）。

3.1 接口名

/v2/group/join_group

3.2 请求参数

注意：不要混淆 groupid 和 guild_id ，前者是 QQ 群 ID，后者是游戏中的工会 ID。

3.3 返回参数

3.4 请求示例

• 请求

    {
        "openid":"D08BF5F51A67414795F602000B000000",
        "token":"6A27E8C2B4EB505BB6D4A230BDDEF00A",
        "guild_id":"2134",
        "groupid":"706990493",
        "zone_id":"1"
    }
  

• 回包

    {
        "ret":0,
        "msg":""
    }
  

四、解绑群（手Q或微信）

如果用户解散了工会 QQ 群，工会和工会 QQ 群不会自动解绑
PS：如果群被解散有两种方式可以取消绑定关系：

1. 会长调用解绑接口解散群关系
   当工会成员调用加群接口时，此时是查询不到群 ID 的，则会默认进行解绑
   如果 QQ 群被解散而没有进行过以上任意一种操作时，则绑定关系不会自动消失
   
2. 会长转让后，新会长也可以进行解绑操作
   

4.1 接口名

/v2/group/unbind_group

4.2 请求参数

channel_info字段
手Q：

微信：

4.3 返回参数

4.4 请求示例

• 请求

    {
        "openid":"D08BF5F51A67414795F602000B000000",
        "token":"6A27E8C2B4EB505BB6D4A230BDDEF00A",
        "channel_info":{
            "guild_id":"2135",
            "guild_name":"itopv2",
            "zone_id":"1"
        }
    }
  

• 回包

    {
        "ret":0,
        "msg":""
    }
  

五、拉取QQ群列表（手Q）

当会长将工会绑定自己已经创建的 QQ 群时，用于拉取已创建的群列表接口。

5.1 接口名

/v2/group/get_group_list

5.2 请求参数

5.3 返回参数

group_list 每条数据包含字段列表

5.4 请求示例

• 请求

    {
        "openid":"D08BF5F51A67414795F602000B000000",
        "token":"6A27E8C2B4EB505BB6D4A230BDDEF00A"
    }
  

• 回包

    {
        "ret":0,
        "msg":"",
        "group_list":[{
                "groupid":"735088906",
                "group_name":"testitop"
        }]
    }
  

六、绑定已创建的QQ群（手Q）

会长可将工会绑定到自己已经创建的 QQ 群接口；调用该接口前先调用 /v2/group/get_group_list 接口拉取已创建的群列表。

6.1 接口名

/v2/group/bind_existing_group

6.2 请求参数

注意：不要混淆 groupid 和 guild_id ，前者是 QQ 群 ID，后者是游戏中的工会 ID。

6.3 返回参数

6.4 请求示例

• 请求

    {
        "openid":"D08BF5F51A67414795F602000B000000",
        "token":"6A27E8C2B4EB505BB6D4A230BDDEF00A",
        "guild_id":"2134",
        "groupid":"735088906",
        "group_name":"testitop",
        "zone_id":"1"
    }
  

• 回包

    {
        "ret":0,
        "msg":""
    }
  

七、提醒会长绑群（手Q）

当工会未绑群时，会员可提醒会长绑群接口；把工会绑定到我已创建的 QQ 群，通过公众号“QQ手游”接收通知，频率限制每天只收到一条；校验提醒者和被提醒者必须为工会成员，游戏方来保证被提醒人为工会会长。

7.1 接口名

/v2/group/remind_leader_bind

7.2 请求参数

7.3 返回参数

7.4 请求示例

• 请求

    {
        "openid":"D08BF5F51A67414795F602000B000000",
        "token":"6A27E8C2B4EB505BB6D4A230BDDEF00A",
        "guild_id":"2135",
        "roleid":"2",
        "leader_openid":"D08BF5F51A67414795F602000B000000",
        "leader_roleid":"2",
        "zone_id":"1"
    }
  

• 回包

    {
        "ret":0,
        "msg":""
    }
  

八、拉取群信息（手Q或微信）

8.1 接口名

/v2/group/get_group_info

8.2 请求参数

channel_info
手Q:

微信:

8.3 返回参数

channel_info
手Q:

微信:

8.4 请求示例

• 请求

    {
        "openid":"D08BF5F51A67414795F602000B000000",
        "token":"6A27E8C2B4EB505BB6D4A230BDDEF00A",
        "channel_info":{
            "guild_id":"2135",
            "zone_id":"1"
        }
    }
  

• 回包

    {
        "ret":0,
        "msg":"",
        "channel_info":’{
            "groupid":"737550331",
            "group_name":"itopv2",
            "group_key":"hLG0YFQgoCIpQ-6_wo4yPXize0JbkzNu",
            "group_openid":"E571324A65B103B992714A6720DB4EBB"
        }
    }
  

九、发送群消息（微信）

9.1 接口名

/v2/group/send_group_msg

9.2 请求参数

open字段列表

9.3 返回参数

十、发送群消息（手Q）

调用此接口的业务，需要在手 Q 申请权限，配置回调地址，如果业务没有申请权限，调用返回 {"is_lost":0,"msg":"invalid appid","ret":-2} 。

10.1 接口名

/v2/group/send_group_msg

10.2 请求参数

10.3 返回参数

10.4 请求示例

• 请求

    curl -X POST -H 'Content-Type: application/json' 'https://dev.itop.qq.com/v2/group/nnelid=2&gameid=12&os=1&seq=&source=0&ts=1557836202&version=2.0&sig=0fcb1dc59df246cc957224cfe337380f' -d '{"openid":"15879468368890148661","token":"935C4F643BC40AC88095429B1F063E07","pf":"qqqun","group_openid":"EE12810F82CE90426B23F2DCA8301738","title":"msdk test qq send group message","desc":"msdk test qq send group message","redirect_url":"http://docs.itop.qq.com","image_url":"https://avatars0.githubusercontent.com/u/3755338?s=460&v=4","param":"11"}'
  

• 回包

    {
        "ret":0,
        "msg":""
    }