instagram-private-api 中 `DirectThreadRepositoryGetByParticipantsResponseItemsItem` 响应接口的深度解析与实战指南
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,处理方式相同。
六、与相邻数据结构的辨析
为准确使用该接口,需区分以下几组易混结构:
DirectThreadRepositoryGetByParticipantsResponseItemsItemvsDirectThreadFeedResponseItemsItem:后者出现在会话历史分页 Feed(src/feeds/direct-thread.feed.ts 的DirectThreadFeed,endpoint/api/v1/direct_v2/threads/{id}/),在 5 个字段之外多出client_context: string(发送方生成的客户端上下文,用于消息去重与幂等)。若需历史分页读取与消息去重,应使用 DirectThreadFeed 而非getByParticipants;DirectThreadRepositoryGetByParticipantsResponseItemsItemvsDirectThreadRepositoryBroadcastResponsePayload:后者(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 模块索引。