instagram-private-api 响应类型全解析：DirectRepositoryCreateGroupThreadResponseFriendshipStatus 接口详解

• 后端

在 Instagram 私信（Direct）系统中，每一次创建群聊线程的接口调用都会在响应中带回每个参与者的完整资料快照，而其中最有信息量、也最容易被开发者忽视的，就是嵌套在用户对象里的friendship_status子对象。本文以 instagram-private-api 项目官方 TypeDoc 生成的接口文档 DirectRepositoryCreateGroupThreadResponseFriendshipStatus.md 为骨架，结合仓库源码，完整解析该接口的 7 个布尔字段语义、它在群聊创建响应中的嵌套结构、底层 API 调用链，以及与其它friendship_status变体的区别，帮助读者在拿到创建群聊的返回值后，能够正确判断每一位成员的关注关系、私密状态与互动限制，从而支撑自动化私信、成员关系判断等实战需求。

接口速览：一个描述"你与他关系状态"的布尔集合

DirectRepositoryCreateGroupThreadResponseFriendshipStatus是 instagram-private-api 在创建群聊线程响应中，用于描述当前登录用户与线程中某个成员之间的社交关系状态的数据结构。它由 7 个boolean属性组成，每个属性对应 Instagram 服务器计算好的一个二元关系维度：

该接口在源码中定义于 src/responses/direct.repository.create-group-thread.response.ts 的 51～59 行：

export interface DirectRepositoryCreateGroupThreadResponseFriendshipStatus { following: boolean; blocking: boolean; is_private: boolean; incoming_request: boolean; outgoing_request: boolean; is_bestie: boolean; is_restricted: boolean; }

所有字段均为必选（非可选），因为该接口只针对创建群聊时服务器已经明确计算过的成员，Instagram 端始终会为每一位返回的成员补齐完整的关系状态，SDK 因此得以用严格的非可选类型约束来保证类型安全。

七个字段的逐一语义解析

following：你是否已关注对方

表示当前登录账号与该成员之间是否存在"已关注"关系。这是判断两人社交关系的基本盘，true表示你已关注对方。

blocking：你是否已拉黑对方

表示你方是否已将对方拉黑。注意该字段的方向是"你 → 对方"，而非"对方 → 你"——对方是否拉黑你并不会体现在这个字段中。

is_private：对方是否为私密账号

描述该成员的账号可见性。私密账号（true）的内容只对已通过其关注请求的用户可见。这一字段对于判断"创建群聊后能否直接查看对方主页内容"非常有参考价值。

incoming_request：对方是否向你发来关注请求

true表示该成员已经向你发起了关注请求，正等待你审批。结合following: false与is_private: true，可以推断出"对方希望关注我，但我尚未接受"的典型私密账号互动场景。

outgoing_request：你是否已向对方发起关注请求

true表示你向对方发起了关注请求，但尚未被对方批准。此时即使对方账号是公开的，你的主页也会展示"请求已发送"状态；在私密账号场景下，你暂时无法查看对方内容。

is_bestie：对方是否在你的密友名单中

表示该成员是否被当前登录用户标记为密友（Close Friends）。该字段为后续判断"该成员是否可以看到我发布的密友专属 Story"提供了依据。

is_restricted：你是否已限制对方

Instagram 的"受限（Restricted）"功能是一种比拉黑更温和的管控手段：受限账号的评论仅对其本人可见，其发送的私信会进入"消息请求"而非正常收件箱，且对方无法看到你的在线状态。true表示你已对该成员启用此限制。

响应中的位置：嵌套在用户列表里的关系快照

该接口并非独立出现在 API 响应顶层，而是作为DirectRepositoryCreateGroupThreadResponseUsersItem.friendship_status存在。整个响应对象的结构如下：

export interface DirectRepositoryCreateGroupThreadResponseRootObject { thread_id: string; thread_v2_id: string; users: DirectRepositoryCreateGroupThreadResponseUsersItem[]; // ... 线程元数据（muted、is_group、thread_title 等） inviter: DirectRepositoryCreateGroupThreadResponseInviter; status: string; } export interface DirectRepositoryCreateGroupThreadResponseUsersItem { pk: number; username: string; full_name: string; is_private: boolean; profile_pic_url: string; profile_pic_id: string; friendship_status: DirectRepositoryCreateGroupThreadResponseFriendshipStatus; is_verified: boolean; has_anonymous_profile_picture: boolean; is_directapp_installed: boolean; is_using_unified_inbox_for_direct: boolean; }

从源码结构看，friendship_status是每个线程成员对象的一部分，与pk、username、profile_pic_url等基础资料并列。这也解释了为什么该接口的 TypeDoc 文档被归类在docs/interfaces/responses/下、并由 responses 模块索引 统一导出——它本质上是一个响应子类型，服务于users数组的逐成员描述。在响应文件 src/responses/index.ts 中，该类型通过export * from './direct.repository.create-group-thread.response'随整个响应模块一起对外暴露。

底层调用链：createGroupThread 如何拿到这份数据

该接口的数据来源于DirectRepository.createGroupThread方法。在 src/repositories/direct.repository.ts 中，该方法的实现为：

export class DirectRepository extends Repository { public async createGroupThread( recipientUsers: string[], threadTitle: string, ): Promise<DirectRepositoryCreateGroupThreadResponseRootObject> { const { body } = await this.client.request.send({ url: '/api/v1/direct_v2/create_group_thread/', method: 'POST', form: this.client.request.sign({ _csrftoken: this.client.state.cookieCsrfToken, _uuid: this.client.state.uuid, _uid: this.client.state.cookieUserId, recipient_users: JSON.stringify(recipientUsers), thread_title: threadTitle, }), }); return body; } }

调用client.direct.createGroupThread(['userA_pk', 'userB_pk'], '群名')后，SDK 会向/api/v1/direct_v2/create_group_thread/发送签名 POST 表单，服务器返回的body直接作为DirectRepositoryCreateGroupThreadResponseRootObject返回。拿到返回值后，即可遍历response.users数组，访问其中每个成员的friendship_status：

const ig = new IgApiClient(); // ... 登录逻辑 const thread = await ig.direct.createGroupThread(['123456', '789012'], '项目讨论组'); for (const member of thread.users) { const fs = member.friendship_status; console.log(`${member.username}: following=${fs.following}, private=${fs.is_private}`); }

值得留意的是，recipient_users使用JSON.stringify序列化后提交，与thread_title一起经过this.client.request.sign()签名，体现了 Instagram 私信端点对请求完整性与设备指纹校验的严格要求。创建成功后的线程还可以通过 DirectThreadEntity（例如ig.entity.directThread(thread.thread_id)）进行后续的广播文本、图片、视频等操作。

与其它 friendship_status 变体的对比

在 instagram-private-api 的响应体系中，friendship_status是一个高频出现的结构，但不同端点返回的字段集合略有差异，理解差异有助于避免跨端点的字段误用：

从对比可以看出，创建群聊响应中的friendship_status是所有 Direct 相关响应中最完整的一个（含is_restricted），而关注/取关等FriendshipRepository.change动作返回的版本则额外包含"对方是否关注我（followed_by）"与"是否静音（muting）"维度，这是因为其典型消费场景是关注关系变更后的状态回显。开发者不应假设这些变体字段完全相同，跨端点使用时应以各自响应类型声明为准。

实战应用：基于关系状态驱动私信自动化

friendship_status的 7 个布尔字段组合起来，可以支撑丰富的业务判断逻辑。以下是几个可直接落地的场景：

1. 区分已关注与未关注成员：通过following直接筛选群内需要先建立关注关系的成员，结合 ProfileEntity.checkFollow 的幂等关注模式（先friendship.show检查、再friendship.create），避免重复发送关注请求。

2. 识别待审批的私密账号：当is_private === true && following === false && outgoing_request === true时，说明你已发出请求但仍被对方"卡在"审批阶段；反之incoming_request === true则说明对方想关注你。这一判断在群聊运营场景（如"哪些成员还没接受我的关注"）中非常实用。

3. 密友内容定向：is_bestie直接标识群内属于你密友名单的成员，可用于决定是否将其纳入仅密友可见的内容推送范围。

4. 受限成员感知：is_restricted可帮助你识别曾被你限制互动的成员，在群聊中对其消息处理保持谨慎或跳过自动回复。

需要强调的是，这些关系状态的底层判定与变更均由 Instagram 服务器完成，SDK 只是忠实返回计算结果。following、blocking等关系的主动变更应通过 FriendshipRepository 的create、destroy、block、unblock、setBesties等方法执行，friendship_status则用于读取与判断当前状态，两者配合即可构建完整的"状态读取 → 状态变更 → 状态确认"闭环。

小结

DirectRepositoryCreateGroupThreadResponseFriendshipStatus虽然只是创建群聊响应中的一个嵌套子接口，但它浓缩了 Instagram 私信体系中最重要的 7 个关系维度。通过本文的字段解析、源码调用链还原与变体对比，读者可以在createGroupThread的返回值中精准提取每位成员的关系快照，并将关系判断无缝接入关注、密友、受限等私信自动化流程。若需进一步了解响应中的其它成员字段，可继续查阅同源的 DirectRepositoryCreateGroupThreadResponseUsersItem.md 与 DirectRepositoryCreateGroupThreadResponseRootObject.md 文档。

• 后端