后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载本文以 instagram-private-api 的DirectThreadRepository类TypeDoc 参考见 DirectThreadRepository.md为核心系统讲解 Instagram 私信Direct Message线程的会话审批、参与者管理、消息删除/已读标记、静音与退出、群聊标题修改以及**各类消息广播文本/链接/图片/视频/语音/帖子/Reel/Story**的底层 API 封装。读完本文你将能基于ig.directThread直接驱动底层接口也能借助DirectThreadEntity的高层封装快速实现一个功能完整的 DM 机器人。一、类定位DM 操作在 SDK 中的坐标DirectThreadRepository继承自 Repository是 instagram-private-api 仓库体系中负责单条会话thread粒度操作的仓储层。它的几个关键事实可以从源码确认实例挂载在IgApiClient上源码见 client.tspublic directThread new DirectThreadRepository(this)因此所有调用入口都是ig.directThread.xxx()构造器只需接收IgApiClient实例即client与 其他 Repository 完全一致与负责收件箱列表的DirectRepository、负责会话内消息分页的 DirectThreadFeed 分工不同本类聚焦于对单个 thread 执行动作实体层 DirectThreadEntity 的多数方法updateTitle、mute、unmute、hide、leave、addUser、deleteItem、markItemSeen等最终都是委托给this.client.directThread对应方法实现的二者是实体便捷层 → 仓储底层的调用关系。所有方法都通过this.client.request.send发起请求src/repositories/direct-thread.repository.ts并依赖this.client.state中的会话数据详见下文。二、调用前提登录状态与会话参数虽然文档里只展示了方法签名但源码显示每个方法几乎都携带统一的form字段其来源是State见 state.tsform 字段来源说明_csrftokenclient.state.cookieCsrfToken从 cookie 中提取的csrftoken找不到时返回missing_uuidclient.state.uuid通过generateDevice(seed)生成随机 UUIDdevice_idclient.state.deviceId形如android-16位hex的设备 ID仅broadcast使用因此使用任何方法前必须先完成登录流程import { IgApiClient } from ./src; const ig new IgApiClient(); ig.state.generateDevice(process.env.IG_USERNAME); // 生成 uuid / deviceId / phoneId / adid ig.state.proxyUrl process.env.IG_PROXY; // 可选代理 await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD); // 登录成功后即可调用 ig.directThread.*获取threadId的典型途径ig.feed.directInbox().records()得到DirectThreadEntity[]其threadId字段即会话 ID。三、会话审批与请求消息管理approve / decline 系列Instagram 存在会话请求message requests机制非好友发来的新会话可能进入待审批状态。本类提供了五个方法对应处理源码src/repositories/direct-thread.repository.ts方法签名请求端点说明approve(threadId: string \| number)POST /api/v1/direct_v2/threads/{threadId}/approve/通过单条会话请求approveMultiple(threadIds: string[] \| number[])POST /api/v2/direct_v2/threads/approve_multiple/批量通过thread_ids以 JSON 字符串提交decline(threadId: string \| number)POST /api/v2/direct_v2/threads/{threadId}/decline/拒绝单条会话请求declineMultiple(threadIds: string[] \| number[])POST /api/v2/direct_v2/threads/decline_multiple/批量拒绝declineAll()POST /api/v2/direct_v2/threads/decline_all/拒绝全部请求无参数需要说明的是文档中方法标注的 URL 中direct_v2前缀在源码实际为direct_v2批量端点路径为/api/v1/direct_v2/threads/approve_multiple/等上表以源码为准approve见 源码第14行、approveMultiple见 第26行、decline见 第39行、declineMultiple见 第51行、declineAll见 第64行。这些方法全部返回 StatusResponse其结构仅为{ status: string }。批量方法通过JSON.stringify(threadIds)把数组序列化进form.thread_ids。await ig.directThread.approve(340282366841710300949128117407001010011); // 通过单条 await ig.directThread.approveMultiple([threadId1, threadId2]); // 批量通过 await ig.directThread.declineAll(); // 拒绝所有待处理请求四、参与者管理加人、审批入群、按参与者查找4.1 approveParticipantRequests审批加入群聊申请签名approveParticipantRequests(threadId: string | number, userIds: string[])端点POST /api/v1/direct_v2/threads/{threadId}/approve_participant_requests/实现见 源码第76行form中除了_csrftoken、_uuid外还固定携带user_ids: JSON.stringify(userIds)与share_join_chat_story: true是否将加入群聊这一事件同步分享到 Story。返回DirectThreadRepositoryApproveParticipantRequestResponseRootObject见 接口文档。4.2 addUser把用户加入会话签名addUser(threadId: string | number, userIds: string[] | number[])端点POST /api/v1/direct_v2/threads/{threadId}/add_user/实现见 源码第147行user_ids同样 JSON 序列化提交。返回DirectThreadRepositoryAddUserResponseRootObject见 接口文档。await ig.directThread.addUser(threadId, [1234567890, 9876543210]); // 可传字符串或数字数组4.3 getByParticipants按参与者反查会话签名getByParticipants(recipientUsers: string[] | number[])端点GET /api/v1/direct_v2/threads/get_by_participants/实现见 源码第94行与前几个方法不同它使用qsquery string而非form提交recipient_users: JSON.stringify(recipientUsers)。返回DirectThreadRepositoryGetByParticipantsResponseRootObject见 接口文档。这是实现根据用户列表找到对应会话例如查询与某用户是否已存在私聊的底层手段。源码中留有注释// move to direct-repo?可以推断该方法在作者计划中可能迁移到DirectRepository但当前仍归属于本类。4.4 updateTitle修改群聊标题签名updateTitle(threadId: string | number, title: string)端点POST /api/v1/direct_v2/threads/{threadId}/update_title/实现见 源码第107行form携带title。返回DirectThreadRepositoryUpdateTitleResponseRootObject见 接口文档其中包含action_log等结构可用于确认标题变更结果。五、会话状态操作静音、退出、隐藏、已读、删除这几个方法都返回 StatusResponse适合做会话管理工具方法签名端点实现位置mute(threadId: string \| number)POST /api/v1/direct_v2/threads/{threadId}/mute/第123行unmute(threadId: string \| number)POST /api/v1/direct_v2/threads/{threadId}/unmute/第135行leave(threadId: string)POST /api/v1/direct_v2/threads/{threadId}/leave/第163行hide(threadId: string)POST /api/v1/direct_v2/threads/{threadId}/hide/第175行markItemSeen(threadId: string, threadItemId: string)POST /api/v1/direct_v2/threads/{threadId}/items/{threadItemId}/seen/第188行deleteItem(threadId: string \| number, itemId: string \| number)POST /api/v1/direct_v2/threads/{threadId}/items/{itemId}/delete/第232行值得注意的源码细节hide与markItemSeen的form中额外携带use_unified_inbox: true与统一收件箱unified inbox机制相关markItemSeen还包含action: mark_seen、thread_id、item_id三个字段leave和hide的参数类型限定为string比mute/unmute的string | number更窄markItemSeen是标记消息已读deleteItem是删除某条消息二者都属于消息级操作itemId可从 DirectThreadFeed 返回的thread.items中获取。// 自动回复后标记已读 const items await ig.feed.directThread(threadId).items(); const latest items[0].item_id; await ig.directThread.markItemSeen(threadId, latest); // 删除自己的某条消息 await ig.directThread.deleteItem(threadId, latest);六、核心广播方法 broadcastDM 发送的统一通道broadcast是本类中参数最复杂、能力最强的方法源码第204行所有类型的私信发送最终都汇聚到这里。6.1 参数类型 DirectThreadBroadcastOptions类型定义见 direct-thread.broadcast.options.ts并在 types 模块文档 中导出interface ExistingThreadOptions { threadIds: Arraystring | number | string | number; } interface CreateThreadOptions { userIds: Arraystring | number | string | number; } interface DirectTreadBroadcastBaseOptions { item: string; // 消息类型标识如 text、configure_photo、media_share、reel_share form?: { [x: string]: any }; // 消息主体内容 qs?: { [x: string]: any }; // query string 附加参数 signed?: boolean; // 是否对 form 进行签名signed_body } export type DirectThreadBroadcastOptions DirectTreadBroadcastBaseOptions XORExistingThreadOptions, CreateThreadOptions;关键点threadIds与userIds通过ts-xor的XOR类型约束二者只能出现其一——指定threadIds表示向已存在的会话发送指定userIds表示创建新会话并发送。6.2 底层请求构造逻辑从源码可以还原broadcast的执行流程生成 mutation tokenconst mutationToken new Chance().guid()每次发送都会生成一个随机 GUID用于幂等与去重确定接收者字段优先取options.threadIds否则取options.userIdsrecipientsType对应thread_ids或recipient_users序列化接收者单个 ID 会被包装成数组注意细节——发送给用户时采用[recipientsIds]的嵌套数组结构发送给会话时直接使用recipientsIds最终都经JSON.stringify放入 form组装 form包含action: send_item、client_context、mutation_token、device_id、_csrftoken、_uuid再展开...options.form签名与发送若options.signed为真调用this.client.request.sign(form)生成ig_sig_key_version与signed_bodyHMAC-SHA256 签名见 request.ts最终请求POST /api/v1/direct_v2/threads/broadcast/{options.item}/可携带qs。await ig.directThread.broadcast({ item: text, threadIds: threadId, // 或 userIds: [1234567890] 来直接发新会话 form: { text: Hello from instagram-private-api! }, }); await ig.directThread.broadcast({ item: link, userIds: [1234567890], form: { link_text: 官方仓库, link_urls: JSON.stringify([https://gitcode.com/gh_mirrors/in/instagram-private-api]), }, signed: true, // 链接消息可开启签名 });6.3 广播响应结构返回类型为DirectThreadRepositoryBroadcastResponseRootObject见 broadcast.response.ts 与 接口文档action、status_code、status请求状态payload含client_context、item_id、timestamp、thread_idmessage_metadata[]每条含client_context、item_id、timestamp、thread_id、participant_ids[]。实体层 DirectThreadEntity 的私有broadcast()方法会依据响应中payload或message_metadata[0]回填threadId这解释了为何通过userIds创建新会话后同一实体后续可以直接基于 threadId 继续发送。七、实战示例组合仓储层与实体层发送各类内容官方示例 dm-thrad.broadast-media.example.ts 展示了在实体层直接调用broadcastPhoto/broadcastVideo/broadcastStory的完整流程import { DirectThreadEntity, IgApiClient } from ../src; import { promisify } from util; import { readFile } from fs; const readFileAsync promisify(readFile); const ig new IgApiClient(); async function login() { ig.state.generateDevice(process.env.IG_USERNAME); ig.state.proxyUrl process.env.IG_PROXY; await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD); } (async () { await login(); const [thread] await ig.feed.directInbox().records(); // 获取第一个会话实体 await sendPhoto(thread); await sendVideo(thread); })(); async function sendPhoto(thread: DirectThreadEntity) { const photo: Buffer await readFileAsync(PATH_TO_PHOTO.jpg); console.log(await thread.broadcastPhoto({ file: photo })); } async function sendVideo(thread: DirectThreadEntity) { const video: Buffer await readFileAsync(PATH_TO_VIDEO.mp4); console.log(await thread.broadcastVideo({ video, transcodeDelay: 5 * 1000, // 若遇到 202 transcode 错误可加大此延迟毫秒 })); }实体层在此基础上封装了更友好的消息类型其底层仍然调用ig.directThread.broadcast值得了解以便在需要直接控制时降级到仓储层实体方法底层item关键 form 字段broadcastText(text, skipLinkCheck?)texttext若检测到 URL 自动转linklink_text、link_urlsbroadcastPhotoconfigure_photoallow_full_aspect_ratio、upload_idbroadcastVideoconfigure_videovideo_result: 、upload_id、sampledbroadcastVoiceshare_voicewaveform未提供时生成正弦波形、waveform_sampling_frequency_hz、upload_idbroadcastPost(mediaId)media_sharemedia_id、carousel_share_child_media_id、send_attribution、unified_broadcast_format: 1broadcastReelreel_sharemedia_id、reel_id、text、entry: reelqs 带media_typebroadcastUserStorystory_sharestory_media_id、reel_id、text默认 signedbroadcastProfile(id)profileprofile_user_idbroadcastStory走ig.publish.story支持viewMode: replayable \| once与replyType对应的选项类型均定义在 direct-thread.broadcast-media.options.ts 与 direct-thread.broadcast-reel.options.ts例如interface DirectThreadBroadcastPhotoOptions { file: Buffer; allowFullAspectRatio?: boolean; // 默认 true实体层 uploadId?: string; } interface DirectThreadBroadcastVideoOptions { video: Buffer; uploadId?: string; sampled?: boolean; // 实体层默认 true transcodeDelay?: number; // 实体层默认 4000ms } interface DirectThreadBroadcastReelOptions { mediaId: string; reelId?: string; // 缺省时取 mediaId 中 _ 后的部分 text?: string; mediaType?: photo | video; }八、完整方法速查表汇总本类全部 16 个公开方法文档列表见 DirectThreadRepository.md方法参数返回类型approvethreadId: string \| numberStatusResponseapproveMultiplethreadIds: string[] \| number[]StatusResponseapproveParticipantRequeststhreadId: string \| number, userIds: string[]DirectThreadRepositoryApproveParticipantRequestResponseRootObjectdeclinethreadId: string \| numberStatusResponsedeclineAll无StatusResponsedeclineMultiplethreadIds: string[] \| number[]StatusResponsebroadcastoptions: DirectThreadBroadcastOptionsDirectThreadRepositoryBroadcastResponseRootObjectaddUserthreadId: string \| number, userIds: string[] \| number[]DirectThreadRepositoryAddUserResponseRootObjectgetByParticipantsrecipientUsers: string[] \| number[]DirectThreadRepositoryGetByParticipantsResponseRootObjectupdateTitlethreadId: string \| number, title: stringDirectThreadRepositoryUpdateTitleResponseRootObjectmutethreadId: string \| numberStatusResponseunmutethreadId: string \| numberStatusResponseleavethreadId: stringStatusResponsehidethreadId: stringStatusResponsemarkItemSeenthreadId: string, threadItemId: stringStatusResponsedeleteItemthreadId: string \| number, itemId: string \| numberStatusResponse九、使用注意事项登录是硬前提所有方法依赖state.cookieCsrfToken、state.uuid、state.deviceId未登录调用会因缺少 cookie 而失败可参考 session.example.ts 的会话序列化/反序列化方式复用登录态。返回类型差异approve/decline/mute/unmute/leave/hide/markItemSeen/deleteItem等返回的是仅含status字段的 StatusResponse而addUser、updateTitle、approveParticipantRequests、getByParticipants、broadcast返回完整的响应根对象可从中读取thread_id、item_id等业务数据。签名signed与转码延迟发送视频类内容时若服务端返回 202 transcode 错误应调大transcodeDelay实体层默认 4000ms部分接口如story_share、link默认或建议开启signed: true。实体层优先若你的threadId来自directInbox().records()大多数场景直接使用DirectThreadEntity上的便捷方法即可只有需要精确控制 form/qs、批量处理或基于userIds直发新会话时才需要直接操作ig.directThread.broadcast。接口路径随版本演进文档中部分端点在源码里的路径前缀可能随仓库迭代更新实际请求 URL 以 direct-thread.repository.ts 当前实现为准文中表格均已按源码标注。通过本文的梳理你可以把DirectThreadRepository的 16 个方法当作一套完整的会话控制 API配合 DirectThreadFeed 的消息读取能力即可构建收发齐全的私信自动化方案。赞分享后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载相关推荐深入 Simple SMS Messenger 代码架构Kotlin 项目模块划分与设计模式全解析深入 Simple SMS Messenger 代码架构Kotlin 项目模块划分与设计模式全解析 Simple SMS Messenger 是一款无广告、开Instagram私有API终极指南instagram-private-api完整入门教程Instagram私有API终极指南instagram private api完整入门教程 想要完全掌控你的Instagram账户操作吗 instagr后端instagram-private-api TimelineFeed 时间线信息流详解从请求构造到分页消费的完整指南instagram private api TimelineFeed 时间线信息流详解从请求构造到分页消费的完整指南 本文围绕 instagram priva后端上一篇Office-Tool本地化资源合并策略减少网络请求数量下一篇7步打造智能餐厅订单系统基于Fay实现虚拟服务员精准备注管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考