@eryxenx/insta-chat 2.0.11 → 2.1.1

package/src/api/users/getUserID.js

@@ -0,0 +1,31 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// fca.getUserID(idOrUsername, callback) -> the numeric user id (pk) as a string.
+//
+// Resolves an @handle to its id, or passes a numeric id through. Answers from
+// the inbox-learned index first (free), then the logout-safe profile resolver.
+// Returns null when the handle cannot be resolved.
+module.exports = function (client) {
+  return async function getUserID(idOrUsername, callback) {
+    const cb = typeof callback === "function" ? callback : null;
+    const raw = String(idOrUsername == null ? "" : idOrUsername).trim().replace(/^@/, "");
+    if (/^\d+$/.test(raw)) {
+      if (cb) cb(null, raw);
+      return raw;
+    }
+    try {
+      const profile = await client.getProfile(raw).catch(() => null);
+      const id = profile?.id || null;
+      if (cb) cb(null, id);
+      return id;
+    } catch (error) {
+      if (cb) cb(error, null);
+      return null;
+    }
+  };
+};

package/src/api/users/getUserInfoV2.js

@@ -0,0 +1,62 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// fca.getUserInfoV2(id | id[], callback) -> { <id>: <full profile> }.
+//
+// V1 getUserInfo returns the fca-shaped subset (name/firstName/username/
+// profileUrl/thumbSrc/gender). V2 returns the *complete* profile Instagram
+// exposes: id, username, full name, biography, follower/following/media counts,
+// verified/private/business flags, the profile picture (square + HD), external
+// url, category and business contact details.
+//
+// It is logout-safe: every source it reads (the users already learned from the
+// inbox/thread views, web_profile_info, the account's own page) is failure
+// tolerant, so a rate-limited (429) or login-redirected (302) profile endpoint
+// can never be mistaken for an expired session.
+module.exports = function (client) {
+  return async function getUserInfoV2(ids, callback) {
+    const cb = typeof callback === "function" ? callback : null;
+    const list = Array.isArray(ids) ? ids : [ids];
+    try {
+      const out = {};
+      for (const id of list) {
+        const key = String(id);
+        const profile = await client.getProfile(key.replace(/^@/, "")).catch(() => null);
+        out[key] = profile
+          ? {
+              id: profile.id,
+              userID: profile.id,
+              username: profile.username,
+              name: profile.fullName,
+              firstName: (profile.fullName || profile.username || "").split(" ")[0] || null,
+              biography: profile.biography,
+              profileUrl: profile.profilePicUrl,
+              thumbSrc: profile.profilePicUrl,
+              profilePicUrl: profile.profilePicUrl,
+              profilePicUrlHd: profile.profilePicUrlHd,
+              followerCount: profile.followerCount,
+              followingCount: profile.followingCount,
+              mediaCount: profile.mediaCount,
+              isVerified: profile.isVerified,
+              isPrivate: profile.isPrivate,
+              isBusinessAccount: profile.isBusinessAccount,
+              isProfessionalAccount: profile.isProfessionalAccount,
+              externalUrl: profile.externalUrl,
+              category: profile.category,
+              fbid: profile.fbid,
+              gender: null
+            }
+          : null;
+      }
+      if (cb) cb(null, out);
+      return out;
+    } catch (error) {
+      if (cb) cb(error, null);
+      return {};
+    }
+  };
+};

package/src/api/users/getUserProfile.js

@@ -0,0 +1,26 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// fca.getUserProfile(idOrUsername, callback) -> the full normalized profile
+// object (see src/profileParse.js): id, username, fullName, biography, counts,
+// flags, pictures, externalUrl, category and contact details.
+//
+// Thin FCA-shaped wrapper over the native getUserProfile(); returns null (never
+// throws) when nothing resolves, so a caller can fall back safely.
+module.exports = function (client) {
+  return async function getUserProfile(idOrUsername, callback) {
+    const cb = typeof callback === "function" ? callback : null;
+    try {
+      const profile = await client.getProfile(String(idOrUsername).replace(/^@/, ""));
+      if (cb) cb(null, profile);
+      return profile;
+    } catch (error) {
+      if (cb) cb(error, null);
+      return null;
+    }
+  };
+};

package/src/api.js

@@ -47,11 +47,46 @@ class InstaAPI {
     this.reaction = new ReactionMethods(this.http);
     this.typing = new TypingMethods(this.http);
     this.thread = new ThreadMethods(this.http);
-    this.user = new UserMethods(this.http);
+    this.user = new UserMethods(this.http, () => ({ id: this.userID, username: this.username }), (key) => this._learnedUser(key));
     this.inbox = new InboxMethods(this.http, () => this.userID, {
-      minPollIntervalMs: options.minPollIntervalMs
+      minPollIntervalMs: options.minPollIntervalMs,
+      identity: this.identity,
+      realtime: options.realtime
     });
     this.media = new MediaMethods(this.http, this.identity);
+
+    // pk / @handle -> user record, learned from inbox/thread introspection. The
+    // profile REST paths rate-limit (429) or 302 to login for a web session, so
+    // a lookup for a user the bot has already seen answers from here for free.
+    this._userIndex = new Map();
+    this._learnInboxUsers();
+  }
+
+  _learnInboxUsers() {
+    const original = this.inbox.getInbox.bind(this.inbox);
+    this.inbox.getInbox = async (...args) => {
+      const result = await original(...args);
+      for (const t of result?.threads || []) {
+        for (const u of t.users || []) this._rememberUser(u);
+        if (t.viewer) this._rememberUser(t.viewer);
+      }
+      return result;
+    };
+  }
+
+  _rememberUser(u) {
+    if (!u || typeof u !== "object") return;
+    const keys = [u.id, u.pk, u.interop_messaging_user_fbid, u.username];
+    for (const key of keys) {
+      if (key) this._userIndex.set(String(key).toLowerCase(), u);
+    }
+  }
+
+  // The user record for a pk, interop fbid or @handle, from data already seen.
+  // Returns null when the user has not been observed yet.
+  _learnedUser(key) {
+    if (key == null) return null;
+    return this._userIndex.get(String(key).replace(/^@/, "").toLowerCase()) || null;
   }
 
   _loadSessionParams(file) {
@@ -122,6 +157,17 @@ class InstaAPI {
     } catch (_) {
       // GraphQL tokens are only needed for sending; polling still works without them.
     }
+    // EP.CURRENT_USER 302s to the login page for a web session, so the handle is
+    // usually still unknown here. The home shell Instagram server-renders embeds
+    // the viewer's own profile, which fills it in without another rate-limited call.
+    if (!this.username && this.userID) {
+      try {
+        const selfProfile = await this.user.getProfile(this.userID);
+        if (selfProfile?.username) this.username = selfProfile.username;
+      } catch (_) {
+        // A missing handle is cosmetic; the id from the cookie is enough.
+      }
+    }
     return { userID: this.userID, username: this.username };
   }
 
@@ -209,6 +255,21 @@ class InstaAPI {
     return this.user.search(query, limit);
   }
 
+  // Full profile (id or @handle) merged from every source a web session can
+  // read. Logout-safe: never throws, returns null when nothing resolves.
+  getUserProfile(idOrUsername, opts) {
+    return this.user.getProfile(idOrUsername, opts);
+  }
+
+  // The best available profile-picture URL. `opts.size` resizes via the CDN.
+  async getProfilePicture(idOrUsername, opts = {}) {
+    const profile = await this.user.getProfile(idOrUsername);
+    const url = profile?.profilePicUrlHd || profile?.profilePicUrl || null;
+    if (!url) return null;
+    const { profilePictureAtSize } = require("./profileParse");
+    return opts && opts.size ? profilePictureAtSize(url, opts.size) : url;
+  }
+
   sendPhoto(threadID, filePath, options) {
     return this.media.sendPhoto(threadID, filePath, options);
   }
@@ -256,6 +317,59 @@ class InstaAPI {
   stopListening() {
     this.inbox.stopListening();
   }
+
+  // ------------------------------------------------------------- realtime
+  // A standalone MQTT (realtime) connection, for callers that want raw push
+  // events (typing/seen/presence) or to drive their own dispatch, rather than
+  // the inbox callback listen() wires up. listen({ realtime: true }) uses the
+  // same RealtimeClient under the hood.
+  _realtimeContext() {
+    return {
+      sessionid: this.http.getCookie("sessionid"),
+      userId: this.userID,
+      deviceId: this.identity.deviceId,
+      uuid: this.identity.uuid
+    };
+  }
+
+  realtimeClient(options = {}) {
+    const { RealtimeClient } = require("./realtime/client");
+    return new RealtimeClient(this._realtimeContext(), options);
+  }
+
+  async realtimeConnect(options = {}) {
+    if (!this._realtime) this._realtime = this.realtimeClient(options);
+    await this._realtime.connect();
+    return this._realtime;
+  }
+
+  realtimeOn(event, handler) {
+    if (!this._realtime) this._realtime = this.realtimeClient();
+    this._realtime.on(event, handler);
+    return this;
+  }
+
+  // Subscribes the connected realtime client to the Direct message-sync stream,
+  // reading the cursor (seq_id/snapshot_at_ms) from the inbox query.
+  async realtimeSubscribe() {
+    if (!this._realtime) throw new Error("realtimeSubscribe: call realtimeConnect() first");
+    const state = await this.inbox.fetchRealtimeState();
+    if (!state) throw new Error("realtimeSubscribe: Instagram did not return a realtime sync cursor");
+    await this._realtime.irisSubscribe(state.seqId, state.snapshotAtMs);
+    return state;
+  }
+
+  async realtimePing() {
+    if (!this._realtime) throw new Error("realtimePing: call realtimeConnect() first");
+    return this._realtime.ping();
+  }
+
+  realtimeDisconnect() {
+    if (this._realtime) {
+      this._realtime.disconnect();
+      this._realtime = null;
+    }
+  }
 }
 
 module.exports = InstaAPI;

package/src/app/InstaClient.js

@@ -319,6 +319,29 @@ class InstaClient {
     return this._igPictureForUser(key, /^\d+$/.test(key) ? "id" : "username");
   }
 
+  // Full profile (id or @handle) from the native resolver. Merges the record
+  // learned from the inbox/thread views with web_profile_info and the account's
+  // own page, so it answers even when the profile REST paths rate-limit (429) or
+  // 302 to the login page. Never throws; returns null when nothing resolves.
+  async getProfile(idOrUsername, opts) {
+    if (typeof this.api.getUserProfile !== "function") return null;
+    const profile = await this.api.getUserProfile(idOrUsername, opts).catch(() => null);
+    if (profile) this._rememberProfile(profile);
+    return profile;
+  }
+
+  // Seeds the FCA caches (picture + user index) from a normalized profile so
+  // later getUserInfo / graph-bridge lookups are a cache hit.
+  _rememberProfile(profile) {
+    if (!profile) return;
+    const url = profile.profilePicUrlHd || profile.profilePicUrl;
+    for (const key of [profile.id, profile.pk, profile.username, profile.fbid]) {
+      if (!key) continue;
+      if (url) this._picCache.set(String(key), url);
+      if (profile.username) this._picCache.set(`name:${String(key)}`, profile.username);
+    }
+  }
+
   // Frozen commands (pp.js) call the fca name `getPictureUrl(id, type)` and
   // guard with `typeof api.getPictureUrl === "function"`; without it the call
   // is skipped and the avatar is blank. `type` mirrors fca's optional

package/src/app/createFcaClient.js

@@ -41,19 +41,31 @@ function createFcaClient(client) {
     }),
     users: compact({
       getInfo: bindOptionalMethod(client, "getUserInfo"),
+      getInfoV2: bindOptionalMethod(client, "getUserInfoV2"),
+      getProfile: bindOptionalMethod(client, "getUserProfile"),
+      getProfilePicture: bindOptionalMethod(client, "getProfilePictureV2"),
+      getBio: bindOptionalMethod(client, "getProfileBio"),
+      getFriendship: bindOptionalMethod(client, "getUserFriendship"),
+      getID: bindOptionalMethod(client, "getUserID"),
       getUID: bindOptionalMethod(client, "getUID"),
       getByUsername: bindOptionalMethod(client, "getUserByUsername"),
       getPictureUrl: bindOptionalMethod(client, "getProfilePictureUrl")
     }),
     account: compact({
       getCurrentUserID: bindOptionalMethod(client, "getCurrentUserID"),
+      getSelfInfo: bindOptionalMethod(client, "getSelfInfo"),
       getAppState: bindOptionalMethod(client, "getAppState"),
       getCookies: bindOptionalMethod(client, "getCookies"),
       setOptions: bindOptionalMethod(client, "setOptions")
     }),
     realtime: compact({
       listen: bindOptionalMethod(client, "listen"),
-      stop: bindOptionalMethod(client, "stopListening")
+      stop: bindOptionalMethod(client, "stopListening"),
+      connect: bindOptionalMethod(client, "realtimeConnect"),
+      on: bindOptionalMethod(client, "realtimeOn"),
+      subscribe: bindOptionalMethod(client, "realtimeSubscribe"),
+      ping: bindOptionalMethod(client, "realtimePing"),
+      disconnect: bindOptionalMethod(client, "realtimeDisconnect")
     }),
     http: compact({
       get: bindOptionalMethod(client, "httpGet"),

package/src/constants.js

@@ -26,7 +26,12 @@ const DOC_ID = {
   MARK_THREAD_READ: "27399783383056109",
   THREAD_DETAIL: "29619996517588618",
   INBOX: "27909866362025854",
-  UNSEND_MESSAGE: "26948700068153789"
+  UNSEND_MESSAGE: "26948700068153789",
+  // Profile Relay operations. PolarisProfilePageContentQuery is the one the
+  // profile page itself issues; PolarisUserRootQuery is its fallback. Both take
+  // a `username` variable and return the full `data.user` profile.
+  PROFILE_PAGE_CONTENT: "7898261790222653",
+  PROFILE_USER_ROOT: "25317500992033585"
 };
 
 const EP = {
@@ -49,6 +54,10 @@ const EP = {
   USER_INFO: (userID) => `${BASE}/users/${userID}/info/`,
   USER_BY_USERNAME: (username) => `${BASE}/users/${username}/usernameinfo/`,
   USER_SEARCH: (query, count) => `${BASE}/users/search/?q=${encodeURIComponent(query)}&count=${count}`,
+  // The canonical profile JSON a logged-in web session reads. Unlike the
+  // /users/<id>/info/ and usernameinfo REST paths, it is not 302'd to the login
+  // page, and it carries follower/media counts, biography and the account flags.
+  WEB_PROFILE_INFO: (username) => `${BASE}/users/web_profile_info/?username=${encodeURIComponent(username)}`,
   TOPSEARCH: (query) => `${WEB}/web/search/topsearch/?query=${encodeURIComponent(query)}&context=blended`,
   RUPLOAD_PHOTO: (uploadName) => `https://i.instagram.com/rupload_igphoto/${uploadName}`,
   RUPLOAD_VIDEO: (uploadName) => `https://i.instagram.com/rupload_igvideo/${uploadName}`,

package/src/methods/inbox.js

@@ -27,6 +27,10 @@ class InboxMethods {
   constructor(http, getUserID, options = {}) {
     this.http = http;
     this.getUserID = getUserID;
+    // The device identity (deviceId/uuid) the realtime MQTT connection needs.
+    this.identity = options.identity || {};
+    // { enabled, fallback } — realtime is opt-in via listen(); see listen().
+    this.realtimeOptions = options.realtime || null;
     // Lowest poll interval listen() will honour, in ms. Instagram has no DM
     // push, so reply latency is bounded by one poll cycle. The 15000 default is
     // the conservative safe floor for a personal account; operators on a
@@ -327,7 +331,82 @@ class InboxMethods {
     return out;
   }
 
-  listen(callback, intervalMs = 20000) {
+  // Starts the realtime (MQTT) listener, falling back to the inbox poller when
+  // the broker is unreachable and options.realtime.fallback !== false. Realtime
+  // is push (sub-second); the poller is the always-works safety net.
+  listen(callback, intervalMs) {
+    const rtOpts = this.realtimeOptions;
+    if (rtOpts && rtOpts.enabled) {
+      const { RealtimeListener } = require("../realtime/listener");
+      const allowFallback = rtOpts.fallback !== false;
+      let stopped = false;
+      let stopPoll = null;
+      const listener = new RealtimeListener(
+        {
+          sessionid: this.http.getCookie("sessionid"),
+          userId: this.getUserID(),
+          deviceId: this.identity.deviceId,
+          uuid: this.identity.uuid,
+          userAgent: rtOpts.userAgent,
+          appVersion: rtOpts.appVersion
+        },
+        {
+          host: rtOpts.host,
+          transport: rtOpts.transport,
+          keepAliveMs: rtOpts.keepAliveMs,
+          seqId: rtOpts.seqId,
+          snapshotAtMs: rtOpts.snapshotAtMs,
+          getRealtimeState: rtOpts.getRealtimeState || (() => this.fetchRealtimeState()),
+          onReady: rtOpts.onReady,
+          onError: (err) => {
+            // Before the subscription is confirmed a failure means realtime is
+            // not usable; degrade to polling so the bot still gets events.
+            if (allowFallback && !listener._subscribed && !stopped) {
+              stopPoll = this._startPolling(callback, intervalMs);
+            } else {
+              callback(err, null);
+            }
+          }
+        }
+      );
+      listener.start(callback).catch((err) => {
+        if (allowFallback && !stopped) stopPoll = this._startPolling(callback, intervalMs);
+        else callback(err, null);
+      });
+      const stop = () => {
+        stopped = true;
+        listener.stop();
+        if (stopPoll) stopPoll();
+      };
+      this._realtimeListener = listener;
+      this._stopListen = stop;
+      return stop;
+    }
+    this._stopListen = this._startPolling(callback, intervalMs);
+    return this._stopListen;
+  }
+
+  // The iris (Direct message-sync) subscription cursor: seq_id + snapshot time.
+  // Read from the inbox query when it exposes them; otherwise the listener
+  // connects without a subscription (a live message still opens the stream).
+  async fetchRealtimeState() {
+    try {
+      const res = await this.http.postGraphQL(
+        "PolarisDirectInboxQuery",
+        DOC_ID.INBOX,
+        { ...INBOX_VARIABLES, device_id_for_iris_subscription: this.http.session?.__hsi || this.http.uuid() },
+        "https://www.instagram.com/direct/inbox/"
+      );
+      const box = res?.data?.get_slide_mailbox_for_iris_subscription || {};
+      const seqId = box.iris_inactive_subscription_uq_seq_id;
+      if (seqId == null) return null;
+      return { seqId: Number(seqId), snapshotAtMs: Date.now() };
+    } catch (_) {
+      return null;
+    }
+  }
+
+  _startPolling(callback, intervalMs = 20000) {
     const MIN_INTERVAL_MS = this.minPollIntervalMs;
     const BASE_INTERVAL_MS = Math.max(Number(intervalMs) || 20000, MIN_INTERVAL_MS);
     const BACKOFF_START_MS = 30000;
@@ -482,6 +561,8 @@ class InboxMethods {
   }
 
   stopListening() {
+    if (typeof this._stopListen === "function") this._stopListen();
+    this._stopListen = null;
     if (this._pollTimer) clearInterval(this._pollTimer);
   }
 }

package/src/methods/media.js

@@ -78,20 +78,34 @@ class MediaMethods {
   }
 
   async _commitMedia(threadID, attachmentFbid, options = {}) {
-    return this.http.postGraphQL(
-      "IGDirectMediaSendMutation",
-      DOC_ID.MEDIA_SEND,
-      {
-        attachment_fbid: String(attachmentFbid),
-        thread_id: String(threadID),
-        offline_threading_id: this._offlineThreadingId(),
-        reply_to_message_id: options.replyToMessageId || null,
-        forwarded_from_thread_id: null,
-        is_forwarded_from_own_message: null
-      },
-      this._threadReferer(threadID),
-      { throwOnError: true }
-    );
+    // Instagram intermittently answers IGDirectMediaSendMutation with a
+    // transient `field_exception` even though the upload already succeeded; a
+    // short backoff retry (same attachment fbid, fresh offline_threading_id)
+    // commits it. Without this a media send fails once and the caller sees a
+    // hard error while the bytes are already uploaded.
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await this.http.postGraphQL(
+          "IGDirectMediaSendMutation",
+          DOC_ID.MEDIA_SEND,
+          {
+            attachment_fbid: String(attachmentFbid),
+            thread_id: String(threadID),
+            offline_threading_id: this._offlineThreadingId(),
+            reply_to_message_id: options.replyToMessageId || null,
+            forwarded_from_thread_id: null,
+            is_forwarded_from_own_message: null
+          },
+          this._threadReferer(threadID),
+          { throwOnError: true }
+        );
+      } catch (error) {
+        const msg = String((error && error.message) || "");
+        const retriable = /field_exception|field exception|temporary failure|internal server error/i.test(msg);
+        if (!retriable || attempt >= 2) throw error;
+        await new Promise((r) => setTimeout(r, 1200 * (attempt + 1)));
+      }
+    }
   }
 
   async _send(threadID, uploadOptions, options) {