instagram-private-api 中 `DirectThreadRepositoryGetByParticipantsResponseItemsItem` 响应接口的深度解析与实战指南

原创2026-10-14 19:47:041,621 阅读
文章标签:后端

instagram-private-api 中 DirectThreadRepositoryGetByParticipantsResponseItemsItem 响应接口的深度解析与实战指南

本篇技术指南聚焦 instagram-private-api(NodeJS Instagram 私有 API SDK,TypeScript 编写)中 Direct Message 模块的 getByParticipants 调用链及其消息项响应接口 DirectThreadRepositoryGetByParticipantsResponseItemsItem,围绕接口字段定义、底层请求实现、timestamp 毫秒时间戳转换、item_type 消息类型判别与多线程消息处理实战展开,帮助读者在读取会话消息时准确解析与运用每一条消息项数据。

一、接口定位:getByParticipants 调用链中的消息项类型

DirectThreadRepositoryGetByParticipantsResponseItemsItem 定义在 src/responses/direct-thread.repository.get-by-participants.response.ts(即文档 "Defined in" 所指源码位置),它是 DirectThreadRepositoryGetByParticipantsResponseThread.items 数组的元素类型。整个响应结构如下:

DirectThreadRepositoryGetByParticipantsResponseRootObject
└── thread: DirectThreadRepositoryGetByParticipantsResponseThread
    ├── users: DirectThreadRepositoryGetByParticipantsResponseUsersItem[]
    ├── items: DirectThreadRepositoryGetByParticipantsResponseItemsItem[]   ← 本文主题
    ├── inviter: DirectThreadRepositoryGetByParticipantsResponseInviter
    ├── last_permanent_item: DirectThreadRepositoryGetByParticipantsResponseLastPermanentItem
    └── last_activity_at / cursor 系列 / last_seen_at 等
└── status: string

该接口属于 docs/modules/responses.md 中导出的 responses 类型集合,通过 src/responses/index.ts 统一导出。从源码结构看,getByParticipants 是 DirectThreadRepository 下"按参与者查找会话"的唯一入口,其返回的 items 数组即本次查询所定位会话内的消息列表,DirectThreadRepositoryGetByParticipantsResponseItemsItem 正是描述其中单条消息的结构化类型。

二、字段定义逐一解析(完整继承原文档)

原文档定义了 5 个属性,此处逐一展开并补充取值范围与用途:

属性 类型 说明
item_id string 消息的唯一 ID,由 Instagram 服务端生成。可用于 directThread.markItemSeen(threadItemId)、directThread.deleteItem(threadId, itemId) 等后续操作
user_id number 发送这条消息的用户数字 ID(pk)。注意它是 number 而非 string,与 DirectThreadRepositoryGetByParticipantsResponseUsersItem.pk 的类型一致
timestamp string 消息发送时间的 Unix 毫秒时间戳,以字符串形式返回,使用前必须转换为数字(详见下文"时间戳处理")
item_type string 消息类型标识,如 text、link、media_share、reel_share、story_share、configure_photo、configure_video、share_voice、profile 等
text string 消息正文。对文本消息是实际内容;对媒体/分享类消息通常是附带文案或链接文本

字段顺序与 src/responses/direct-thread.repository.get-by-participants.response.ts 源码一致(item_id → user_id → timestamp → item_type → text)。

三、底层请求实现:GET get_by_participants

getByParticipants 在 src/repositories/direct-thread.repository.ts 中实现,请求细节如下:

public async getByParticipants(
  recipientUsers: string[] | number[],
): Promise<DirectThreadRepositoryGetByParticipantsResponseRootObject> {
  const { body } = await this.client.request.send<DirectThreadRepositoryGetByParticipantsResponseRootObject>({
    url: '/api/v1/direct_v2/threads/get_by_participants/',
    method: 'GET',
    qs: {
      recipient_users: JSON.stringify(recipientUsers),
    },
  });
  return body;
}

关键点:

  • HTTP 方式:GET 请求,endpoint 为 /api/v1/direct_v2/threads/get_by_participants/;
  • 入参:recipientUsers 为 string[] | number[],是参与会话的用户 ID 列表,通过 query string 以 recipient_users 键传递,且须经 JSON.stringify 序列化;
  • 鉴权:该方法未显式携带 _csrftoken 等表单字段,因为 GET 请求的 cookie 鉴权由 Request 层统一完成;
  • 返回值:完整响应体 DirectThreadRepositoryGetByParticipantsResponseRootObject,其中的 thread.items 即为 DirectThreadRepositoryGetByParticipantsResponseItemsItem[]。

调用方式:客户端实例 IgApiClient 的 directThread 属性(见 src/core/client.ts)即 DirectThreadRepository 实例:

import { IgApiClient } from 'instagram-private-api';

const ig = new IgApiClient();
// 登录初始化(session / account.login 等)后:
const { thread } = await ig.directThread.getByParticipants(['user_a_id', 'user_b_id']);
for (const item of thread.items) {
  // item 即为 DirectThreadRepositoryGetByParticipantsResponseItemsItem
  console.log(item.item_id, item.user_id, item.item_type, item.text);
}

四、消息类型(item_type)判别与实战处理

item_type 是 string 类型,实际取值与 DirectThreadEntity 支持发送的消息类型一一对应(可对照 src/entities/direct-thread.entity.ts 中的 broadcast* 方法):

item_type 取值 对应发送方法 text 语义
text broadcastText 纯文本消息,text 为完整内容
link broadcastLink 含链接文本,text 为展示文案
media_share broadcastPost 帖子分享,text 为附带文案
reel_share broadcastReel 故事回复(上滑私信),text 为回复文字
story_share broadcastUserStory 故事转发,text 为附带文案
configure_photo broadcastPhoto 图片消息
configure_video broadcastVideo 视频消息
share_voice broadcastVoice 语音消息
profile broadcastProfile 主页账号分享

注意:DirectThreadRepositoryGetByParticipantsResponseItemsItem 是精简版消息结构,仅含 item_id/user_id/timestamp/item_type/text。若需消息的媒体 URL、回复计数等扩展字段,Instagram 会按 item_type 附带不同类型子对象,而本项目将该结构保持精简。因此实战中建议用 item_type 做分流:

for (const item of thread.items) {
  if (item.item_type === 'text') {
    console.log(`文本消息(${item.user_id}): ${item.text}`);
  } else if (item.item_type === 'link') {
    console.log(`链接消息: ${item.text}`);
  } else {
    console.log(`其他类型 ${item.item_type}: id=${item.item_id}`);
  }
}

五、timestamp 字符串时间戳的正确处理

timestamp 以字符串承载 Unix 毫秒时间戳。将其转为可读时间时需显式转换类型,避免字符串拼接陷阱:

const ts = Number(item.timestamp);              // 必须转换
const date = new Date(ts);                       // Date 构造时传入 number
console.log(date.toISOString());                 // 如 2026-10-14T11:45:57.000Z
console.log(ts, Date.now() - ts < 60_000);       // 是否在 1 分钟内到达

排序会话消息时也应按数字比较:

thread.items.sort((a, b) => Number(a.timestamp) - Number(b.timestamp));

注意:同一线程中,last_permanent_item(见 src/responses/direct-thread.repository.get-by-participants.response.ts)与 DirectThreadRepositoryGetByParticipantsResponseItemsItem 结构一致,同样携带字符串型 timestamp,处理方式相同。

六、与相邻数据结构的辨析

为准确使用该接口,需区分以下几组易混结构:

  • DirectThreadRepositoryGetByParticipantsResponseItemsItem vs DirectThreadFeedResponseItemsItem:后者出现在会话历史分页 Feed(src/feeds/direct-thread.feed.ts 的 DirectThreadFeed,endpoint /api/v1/direct_v2/threads/{id}/),在 5 个字段之外多出 client_context: string(发送方生成的客户端上下文,用于消息去重与幂等)。若需历史分页读取与消息去重,应使用 DirectThreadFeed 而非 getByParticipants;
  • DirectThreadRepositoryGetByParticipantsResponseItemsItem vs DirectThreadRepositoryBroadcastResponsePayload:后者(src/responses/direct-thread.repository.broadcast.response.ts)是发送消息后返回的确认结构,含 client_context/item_id/timestamp/thread_id,用于把 DirectThreadEntity 绑定到已创建会话(见 src/entities/direct-thread.entity.ts);
  • 消息项 vs 会话元数据:items 数组之外的 thread_id/thread_v2_id/users/thread_title/is_group/pending/archived 等字段(见 src/responses/direct-thread.repository.get-by-participants.response.ts)描述会话本身,消息处理时应以 items 为数据源、以 thread 其余字段为上下文。

七、综合实战:按参与者定位会话并解析消息

将以上要点整合为一个完整场景——定位与某两位用户的会话并读取其中文本消息:

import { IgApiClient } from 'instagram-private-api';
import { DirectThreadRepositoryGetByParticipantsResponseRootObject } from 'instagram-private-api';

async function dumpThreadMessages(
  ig: IgApiClient,
  userIds: string[],
): Promise<void> {
  const res: DirectThreadRepositoryGetByParticipantsResponseRootObject =
    await ig.directThread.getByParticipants(userIds);

  if (!res.thread) {
    console.log('未找到会话(或需先建立会话)');
    return;
  }
  console.log(`会话 ${res.thread.thread_id},共 ${res.thread.items.length} 条消息`);
  res.thread.items
    .sort((a, b) => Number(a.timestamp) - Number(b.timestamp))
    .forEach((item) => {
      console.log(
        `[${new Date(Number(item.timestamp)).toISOString()}] ` +
          `user=${item.user_id} type=${item.item_type} text=${item.text}`,
      );
    });
}

几点实战提醒:

  • getByParticipants 依赖客户端已通过登录/会话初始化(可参考 examples/session.example.ts);
  • 入参 recipientUsers 传数字数组时,JSON.stringify 输出 [123,456];传字符串数组时输出 ["123","456"],Instagram 服务端对两者均接受;
  • 该方法与 directThread.broadcast({ item: 'text', ... })(src/repositories/direct-thread.repository.ts)组合使用,可实现"先定位会话、再向该会话发送消息"的完整读写闭环。

八、小结

DirectThreadRepositoryGetByParticipantsResponseItemsItem 虽只有 5 个字段,却是 getByParticipants 调用链中承载消息实体的核心类型。掌握其字段类型约束(user_id: number、timestamp: string)、item_type 分流逻辑、与 DirectThreadFeedResponseItemsItem/BroadcastResponsePayload 的边界,即可在 instagram-private-api 中可靠地读取、排序和展示私信会话内容。如需进一步查阅,可参考 DirectThreadRepository 类文档 及 responses 模块索引。

登录后查看全文
instagram-private-api