10/27/2025 18:02:31

好友关系链

一、同玩好友(不包含自己)

手Q/微信渠道拉取好友关系链需要到平台侧申请关系链权限，为了方便业务接入，飞鹰集成了快速申请权限的通道，飞鹰系统 -> 左侧菜单 MSDK接入->特殊权限申请->手Q关系链/微信关系链。
目前支持渠道：QQ、WeChat、Facebook、garena、VK、steam。

1.1 接口名

/v2/friend/friend_list

1.2 请求参数

参数 类型 描述
openid string 【必填】用户唯一标识
token string 【必填】用户登录态
sub_channelid int 【选填】查询当前账号绑定的其他渠道的同玩好友时传入，用于指定需要查询的渠道，取值可以参考服务端API说明

1.3 返回参数

参数 类型 描述
ret int 返回码 0：正确，其他：失败
msg string 返回结果详细说明
lists array 同玩好友个人信息列表
is_lost int 仅 QQ 渠道需要关注：
值为 0，说明手Q返回的好友数据正常。业务可直接使用返回的好友数据；
值为 1，是手Q的一个降级方案，表示可能拉取的数据不全。如果业务接受降级可选择使用不全的数据，反之可认定为失败；

lists说明

lists {
    string openid;          // 用户标识
    string user_name;       // 昵称
    int gender;             // 性别，未定义：0，男：1，女：2。手Q渠道固定返回 0，微信不支持该字段
    string picture_url;     // QQ/微信好友头像 URL
    string country;         // 国家
    string provice;         // 省份
    string city;            // 城市，微信不支持该字段
    string language;        // 语言
    string nick_name;       //（仅微信支持）好友在社交渠道的昵称，先确认字段存在后再取值，因为权限正常且微信正常返回昵称时该字段才存在
    string friend_remark;   //（仅微信支持）好友备注名，先确认字段存在后再取值，因为权限正常且微信正常返回昵称时该字段才存在
}

特别说明

  • user_name 会随时根据策略进行管控，如有明确使用微信备注名的需求，请务必使用 friend_remark 来获取；新接入业务 user_name，默认只返回昵称；
  • 针对新业务，昵称应该使用 nick_name 字段，如果需要好友备注，需要走申请报备流程，确认好友备注使用的合规性再使用 friend_remark 字段；
  • QQ 好友头像 URL，必须在 URL 后追加参数 /40 或 /100。这样可以分别获得 <40*40>(/40) 或 <100*100>(/100) 规格的图片；
  • 微信好友头像 URL，必须在 URL 后追加参数 /0、/46、/64、/96 或 /132。这样可以分别获得原始图片(/0)、<46*46>(/46)、<64*64>(/64)、<96*96>(/96) 或 <132*132>(/132) 规格的图片；
  • 海外渠道如 Facebook 为了出海游戏符合 GDPR 规范，好友信息的性别信息固定返回 0；
  • 没有同玩好友时，回包中没有 lists 字段是正常现象；

1.4 请求示例

微信渠道

  • 请求
      {
      "openid": "13601369187816917176",
      "token": "61_nTO2IrYUm4KTM58tuZYZR8wZMbjyDJWndI_AMzuIKjAOGDobd94FtNLaiH8KmB774Q40xDo14hjnmHi_mZocsuACKV3GVps7gPXr-glx4Ts"
  }
  • 回包
      {
      "ret": 0,
      "msg": "",
      "lists": [
          {
              "user_name": "zzz",
              "picture_url": "https://wx.qlogo.cn/mmhead/No0JxNE4LEUcXM5dmgJcjEadU8jllM45SGtOHxsmiafM",
              "provice": "",
              "openid": "6292984005760995448",
              "nick_name": "Σ(￣。￣ノ)ノ",
              "friend_remark": "小张"
          },
          {
              "user_name": "小佳",
              "picture_url": "https://wx.qlogo.cn/mmhead/Zc9yUpJNc2MVN3IzgUtL9BsfA09pp4MSaaib8nSDb03M",
              "provice": "",
              "openid": "18182179939911361117",
              "nick_name": "小佳"
          }
      ],
      "seq": "1664333165-3965425163-019804-0315511573"
  }

手Q渠道

  • 请求

      {
      "openid":"4724195171999796436",
      "token":"27A50B44430AAD6BFFBE09BA875E48BB"
  }
  • 回包
      {
      "ret": 0,
      "msg": "",
      "lists": [
          {
              "user_name": "小张",
              "gender": 0,
              "picture_url": "https://q.qlogo.cn/qqapp/1106977030/A7DB20EFF6DD4A617367B71186DB33A6/",
              "openid": "14882639338379730531"
          },
          {
              "user_name": "小佳",
              "gender": 0,
              "picture_url": "https://thirdqq.qlogo.cn/qqopen/ZdvYp9s7k6qJuCiaNlJR3hT5vtL0rJxiclJ814gxnmuKYXv0xs04j1WWUoKX1u1MlE/",
              "openid": "15991060247728890761"
          }
      ],
      "is_lost": 0,
      "seq": "1664333315-0844862987-022347-0109203549"
  }

二、获取未注册手Q好友/微信密友

2.1 接口名

/v2/friend/recall_friends_list

2.2 接口说明

重要：获取未注册手Q好友/微信密友（关系链推广员能力），在游戏内调用时会获取未经授权的用户数据，经《个人信息保护法》评估须进行改造，请已接入使用的项目组关注。未接入的游戏暂停接入申请。

① 平台改造方案：在游戏内该接口将返回“无推荐好友”的空数据，请项目组关注用户界面处理，必要时需隐藏游戏内使用未注册密友/推广员的界面入口。

② 生效时间：2021年11月5日 18:00 前。

手Q平台公告详情可咨询 qqconnecthelper(QQ互联及登录咨询);
微信平台公告详情可咨询 wxgame(微信游戏助手) 或参见 https://mmgame.oa.com/index.html#/announce/detail?id=174 。

2.3 请求参数

参数 类型 描述
openid string [必填]用户 openid
token string [必填]用户 token
task_id int [微信必填]任务 id，向微信申请时获得
count int [手Q必填]期待拉取好友的个数，建议填写 20（不要超过 20，最多返回20个好友）

2.4 返回参数

参数 类型 描述
ret int 返回码，0 ：成功，其他：失败
msg string 返回信息
result object 返回结果对象，微信和手Q分别描述

1）微信 result 结构

参数 类型 描述
friend_list array 密友列表
model_id int 模型 id
send_list array 发送列表

2）手Q result 结构

参数 类型 描述
friend_list array 未注册好友列表

注意：friend_list 列表中每个对象包含 sopenid、head_img_url、nick_name 三个字段

2.5 请求示例

# 微信
curl -X POST -H 'Content-Type: application/json' 'https://hktest.itop.qq.com/v2/friend/recall_friends_list?channelid=1&conn=&gameid=12&os=1&seq=&source=0&ts=1570764309&version=2.0&sig=cae2c68c247db13d0d9e111f90f0eb54' -d '{"openid":"3505996091832136773","token":"26_cUcJse2lEvZP9SojX5Oc-EKdaFV96i-sMOOCL3OB_fMSiwmq6wjC4e3tOj_zW7f8U3j8BAqBjwNaJPdR70U76B-hRkkgs1CMcVhLLiVj86U","task_id":0}'

{
    "msg": "success",
    "result": {
        "friend_list": [
            {
                "sopenid": "sHlap1bakvTsj1fyeeWxPoIW5OiY",
                "head_img_url": "http://wx.qlogo.cn/mmopen/vi_32/298Iynvq8598KfjWKRxHX0w2P1icnoE1mnj6BlOBicEOAoG6qbl6oD6Csumiaq2LFIsiat5ZZAsN95SRDULfoiaob4g/0",
                "nick_name": "弓长月半月半"
            },
            {
                "sopenid": "sHlap1V3R7QDESg-WgyRfXI5ZKcI",
                "head_img_url": "http://wx.qlogo.cn/mmopen/vi_32/Q0j4TwGTfTIAmxdv26icib4TayhbZqqdJ49Zvwicukf8vJw6zCgPdDAYxMEG37tkkmg54Y8zrObeFCKpKMcRaMGzg/0",
                "nick_name": "林"
            }
        ],
        "model_id": 0,
        "send_list": []
    },
    "ret": 0,
    "seq": "1570770148-0268717065-046971-0000003701"
}

# 手Q
curl -X POST -H 'Content-Type: application/json' 'https://hktest.itop.qq.com/v2/friend/recall_friends_list?channelid=2&conn=&gameid=12&os=1&seq=&source=0&ts=1572523399&version=2.0&sig=a8598291194154e79cb6b7c0a6f40e55' -d '{"token":"D46EF700A328F58231FF69045A54C91D","openid":"15879468368890148661","count":20}'

{
    "msg": "success",
    "ret": 0,
    "result": {
        "friend_list": [
            {
                "sopenid": "ChBBXeAbRjqUbDa8zZ8K_A1oNBKBAWK9mxgNDNwJIxBYd6IWho2aWtjfbWqkjpi7",
                "nick_name": "禾苗苗芋头",
                "head_img_url": "https://thirdqq.qlogo.cn/qqapp/1106977030/B784C3A8411A406546E40DCD9D898635/100"
            },
            {
                "sopenid": "NYcNfgzl7EIk5d96VCJOYJtHI3wYf0qUOqG5X8ilZGW8lMlr2v0QtXUkcXQrH4d3",
                "nick_name": "运营开发-蒋慧强",
                "head_img_url": "https://thirdqq.qlogo.cn/qqapp/1106977030/255E40A981DF206E75975A7440098C1D/100"
            },
            {
                "sopenid": "ajOYNtR74_zxjXaKF6h-0GuOCNhXuCrtGS_ADdx3D_V-9Jb_wsQOvYbHjUXZaCUs",
                "nick_name": "纳斯达．α",
                "head_img_url": "https://thirdqq.qlogo.cn/qqapp/1106977030/DF5130F8023DFE197B121346B10EB9FA/100"
            },
            {
                "sopenid": "P61CN9sYPuDO05-ydiefCUGYKGzPE8avgAhhMVlUBQVu7-VAq1CclagM2qo5f_R8",
                "nick_name": "王志波",
                "head_img_url": "https://thirdqq.qlogo.cn/qqapp/1106977030/56ED3920969AFAD056EB83A323B1155D/100"
            }
        ]
    },
    "seq": "1572525472-0016777343-022540-0000000191"
}

特别说明

  • 调用微信密友接口需要申请权限，微信密友文档参考：https://mmgame.oa.com/doc/#/article/144；
  • 权限申请流程：
    1.产品参考”微信密友文档“中模板发送邮件申请；
    2.开发发起线上申请（https://weixin.oa.com/open_broker/ ），需要双方总监审批通过；
    3.测试环境调用接口当前需要联系@mmgame_helper(微信游戏开发助手)进行 appid 同步(正式环境绑定需要游戏过了 pr1 之后联系协同操作）；

三、获取 sopenid(仅QQ、微信渠道支持)

3.1 接口名

/v2/profile/get_sopenid

3.2 请求参数

参数 类型 描述
openid string [必填]用户 openid
token string [必填]用户 token

3.3 返回参数

参数 类型 描述
ret int 返回码，0 ：成功，其他：失败
msg string 返回信息
result object 返回结果对象，微信和手Q分别描述

3.4 请求示例

# 微信
curl -X POST -H 'Content-Type: application/json' 'https://test.itop.qq.com/v2/profile/get_sopenid?channelid=1&conn=&gameid=12&os=1&seq=&source=0&ts=1572523399&version=2.0&sig=b7724e08bc2627576391104c340df9bd' -d '{"token":"27_l7XUrQiS8dyqIA4vGGqfjJsVwVBl0EKl30kaArFK6ALSPRXseyJsDw2qZDd6Hl6UgvsLhe5cLEL2aJ5_j5Od1JrEaFwMOIOQ9aAd578sfyQ","openid":"3505996091832136773"}'

{
    "ret": 0,
    "msg": "success",
    "sopenid": "sHlap1b2ZKIs92noWooBci31u9Y8",
    "seq": "1572525723-0016777343-022546-0000000075"
}

# 手Q
curl -X POST -H 'Content-Type: application/json' 'https://test.itop.qq.com/v2/profile/get_sopenid?channelid=2&conn=&gameid=12&os=1&seq=&source=0&ts=1572523399&version=2.0&sig=074133c7f08e4b0320aee6584e244e49' -d '{"token":"D46EF700A328F58231FF69045A54C91D","openid":"15879468368890148661"}'

{
    "ret": 0,
    "msg": "success",
    "sopenid": "ikrjDgPqEUPTY_jnBKx9w5NZAkOimlyv-Tzl2Cj0gEFCtDHY_KjzRQBD9CuufGrM",
    "seq": "1572525777-0016777343-022540-0000000192"
}

四、分享(仅QQ渠道支持)

4.1 接口名

/v2/friend/share

4.2 接入说明

该接口平台侧已不再接受游戏接入，可以通过 手Q 游戏中心查询 接口实现 ARK 后端分享，如有特殊需求请联系手Q游戏中心对接（已接入游戏可继续使用）。

4.3 接口说明

手Q后端分享，可通过 C2C 收到分享的结构化消息 / ARK消息（在绿洲平台申请 sceneid 发送消息，调用 /v2/friend/ark_share ）。另外，也可以通过“QQ手游”公众号收到分享消息，但需提前关注该公众号。
分享的内容只有手机 QQ 上才可以看到，PC QQ 上看不到。

收发限制：
1、结构化消息
同一对号码发送接收，互动次数是一天一次。
接收方，每天最多接收 5 条，每周最多接收 20 条。
发送方，每天发给不同用户，最多发送 10 条，每周最多发送 40 条。
2、ark消息
接收方，每天最多接收5条，接收自同一个人最多3条。
发送方，每天最多30条，每周最多100条。

通过"QQ手游"公众号接收的消息，平台侧会延时下发，于每日固定三个时间段（当前是每天12点，20点，22点）通过公众号下发，单用户每天最多收到3条公众号消息。

4.4 请求参数

参数 类型 描述
openid string 【必填】用户唯一标识
token string 【必填】 用户登录态
type int 【必填】固定填写 20000 即可
fopenid string 【同玩好友必填】同玩好友 openid
sopenid string 【邀请未注册好友必填】未注册好友 sopenid（通过 /v2/friend/recall_friends_list 接口获得）
title string 标题
desc string 摘要
link string 分享链接使用【暂不支持链接分享】
image_url string 分享图片 url
game_tag string 【必填】由平台侧分配，需同手Q平台沟通后填写（以下仅列出部分参考值）:
1. 通过公众号收到推送消息
“MSG_INVITE”：邀请；
“MSG_FRIEND_EXCEED”：超越炫耀；
“MSG_HEART_SEND”：送心；
“MSG_SHARE_FRIEND_PVP”：PVP对战；
2. 通过C2C推送收到结构化消息
“MSG_RECALL”：召回；
“MSG_INVITE_NEW”：邀请；
3. ARK消息
“MSG_RECALL_ARK”：召回；
“MSG_INVITE_ARK”：邀请；
“MSG_INVITE_FRIEND_ARK”：拉新；
channel_info object 渠道信息
extra string 其他扩展信息

channel_info 字段

参数 类型 描述
act int 拉起游戏：1
target_url string 游戏中心详情页 URL，自定义信息可在 Url 后添加 gamedata 参数实现透传，例如：https://speed.gamecenter.qq.com/pushgame/v1/detail?appid=xxx&gamedata=gamedata
src int 消息来源，默认值 0
dst int 只能填 1001
flag int 漫游，只能填1

4.5 请求返回

参数 类型 描述
ret int 返回码 0：正确，其他：失败
msg string 返回结果详细说明
seq string 请求 url 中的 seq 字段

4.6 请求示例

  • 请求URL

      http://hktest.itop.qq.com/v2/friend/share?channelid=2&gameid=11&os=1&seq=123&ts=1530792639&version=&sig=f544c40d50c28f4094aabd2d6638a9a3

  • 请求Body

      {
      "openid": "4724195171999796436",
      "token": "27A50B44430AAD6BFFBE09BA875E48BB",
      "fopenid": "4124157778415485412",
      "title": "test_share",
      "desc": "nothing to share",
      "link": "",
      "image_url": "http://mat1.gtimg.com/www/images/qq2012/erweimaNewsPic.png",
      "game_tag": "",
      "type": 20000,
      "channel_info": {
          "target_url": "http://mat1.gtimg.com/www/images/qq2012/erweimaNewsPic.png",
          "dst": 1001,
          "src": 0,
          "flag": 1
      }
  }

  • 响应

      {
      "ret": 0,
      "msg": "success!",
      "seq": "123"
  }

五、手Q ARK 后端分享(仅QQ渠道支持)

5.1 接口名

/v2/friend/ark_share

5.2 接入说明

该接口平台侧已不再接受游戏接入，可以通过 手Q 游戏中心查询 接口实现 ARK 后端分享，如有特殊需求请联系手Q游戏中心对接（已接入游戏可继续使用）。

手Q ARK分享服务接口提供了ARK消息 C2C 分享能力（分享消息给手机QQ好友，在好友会话框中显示），在绿洲平台申请 sceneid，发送 ARK 类型消息。以下流程均需要联系腾讯对接人：
（1）接入方联系 QQ平台运营 录入信息，QQ平台运营 将信息提交给平台流程组录入；
（2）接口接入完成后验证分享是否成功。

5.3 接口说明

1.分享的内容只有手机QQ上才可看到，PC QQ上看不到。
2.收发限制：
接收方，每天最多接收5条，接收自同一个人最多3条。
发送方，每天最多30条，每周最多100条。

5.4 请求参数

参数 类型 描述
openid string 【必填】 发送分享的用户 id
token string 【必填】 发送分享用户的登录态 token
fopenid string 【同玩好友必填】接收分享的同玩好友的 openid
sopenid string 【邀请未注册好友必填】未注册好友 sopenid（通过 /v2/friend/recall_friends_list 接口获得）
extra string 【必填】透传手Q侧的分享模板 extraJson, 去掉json的注释和空白符，必需进行 urlencode 返回参数

说明：
extraJson 在手Q侧申请接入ARK分享流程完成后会拿到该参数 , 使用时需要将json串的注释和空白符去掉，压缩成一个字符串后再进行url encode加密。

5.5 请求返回

参数 类型 描述
ret int 返回码 0：正确，其他：失败
msg string 返回结果详细说明

5.6 请求示例

  • 请求URL

      https://itop.qq.com/v2/friend/ark_share?channelid=2&conn=&gameid=12&os=1&seq=1111-001&source=1&ts=1605081818&version=2.0&sig=62993d6c7f03f3e5c24fe5bb7ab06091

  • 请求Body

     {
   "openid": "6703731585054734300",
  "token": "17DD31B2CC12B2A078B8CE4A7333B7FA",
  "fopenid": "14719294144616908484",
  "extra": "%7B%22app%22%3A%22com.tencent.gamecenter.qqsy%22%2C%22view%22%3A%22picView2%22%2C%22desc%22%3A%22%E6%B8%B8%E6%88%8F%E5%88%86%E4%BA%AB%22%2C%22ver%22%3A%221.0.0.1%22%2C%22config%22%3A%7B%22forward%22%3A0%2C%22type%22%3A%22normal%22%7D%2C%22meta%22%3A%7B%22shareData%22%3A%7B%22appid%22%3A%221109719108%22%2C%22openId%22%3A%22%22%2C%22scene%22%3A%22446%22%2C%22url%22%3A%22%22%7D%7D%7D"
 }

  • 响应

      {
      "ret": 0,
      "msg": "success!",
      "seq": "1594899989-0268717065-054062-0000016317"
  }

六、手Q ARK 分享签名生成接口(仅QQ渠道支持)

6.1 接口名

/v2/friend/ark_sign

6.2 接口说明

该接口平台侧已不再接受游戏接入，接入 手Q 游戏中心查询，如有特殊需求请联系手Q游戏中心对接（已接入游戏可继续使用）。

【注意】业务正式发布前请联系 MSDK助手 评估修改 OIDB 单据频率。

6.3 请求参数

参数 类型 描述
openid string 【必填】 openid（gopenid）
token string 【必填】 token（MSDK token）
extra string 【必填】ark分享json（从绿洲获取模板后插入数据生成）

6.4 请求返回

参数 类型 描述
ret int 返回码 0：正确，其他：失败
msg string 返回结果详细说明
data string 签名后的ark分享json

6.5 请求示例

  • 请求URL

      https://dev.itop.qq.com/v2/friend/ark_sign?channelid=2&conn=&gameid=12&os=1&seq=&source=0&ts=1692601073&version=2.0&sig=fcd4ef7647b1211af5edfe7c9ad26b02

  • 请求Body

     {
  "openid": "12629992397987394692",
  "token": "123123",
  "extra": "{\"app\":\"com.tencent.channel.share\",\"prompt\":\"[分享链接]Loading...\",\"meta\":{\"detail\":{\"origin\":\"分享链接\",\"title\":\"Loading...\",\"desc\":\"Level up your coding skills and quickly land a job. This is the best place to expand your knowledge and get prepared for your next interview.\",\"img\":\"https://qq.ugcimg.cn/v1/gpvjqfbrr4fbajrkhade6q8rum44amkp1gt5iaqi4n0r5o6hf4t6inmtuieq9f8hufb3f45k0ibus7htmnr12tih5n14b75954jqvs0/goeub8be9seqoorm568262dnoo\",\"link\":\"https://leetcode.com/problems/word-ladder/\"}},\"config\":{\"ctime\":1629030272,\"autosize\":1,\"forward\":1},\"view\":\"albumAddPic\",\"ver\":\"1.0.0.1\"}"
  }

  • 响应

      {
  "ret": 0,
  "msg": "success!",
  "data": "{\"app\":\"com.tencent.channel.share\",\"config\":{\"autosize\":1,\"ctime\":1629030272,\"forward\":1,\"token\":\"d610fd3b4247fc8d362473aeb2282491\"},\"meta\":{\"detail\":{\"desc\":\"Level up your coding skills and quickly land a job. This is the best place to expand your knowledge and get prepared for your next interview.\",\"img\":\"https://qq.ugcimg.cn/v1/gpvjqfbrr4fbajrkhade6q8rum44amkp1gt5iaqi4n0r5o6hf4t6inmtuieq9f8hufb3f45k0ibus7htmnr12tih5n14b75954jqvs0/goeub8be9seqoorm568262dnoo\",\"link\":\"https://leetcode.com/problems/word-ladder/\",\"origin\":\"分享链接\",\"title\":\"Loading...\"}},\"prompt\":\"[分享链接]Loading...\",\"ver\":\"1.0.0.1\",\"view\":\"albumAddPic\"}\n",
  "seq": "1692604361-1415414537-022139-0000160877"
  }



Copyright © 2025 MSDK.
All rights reserved.

results matching ""

    No results matching ""