⚡ What is this?

@eryxenx/insta-chat is a standalone Instagram Direct Message API — the Instagram sibling of an FCA package. It talks to the same web endpoints www.instagram.com uses (Relay GraphQL + rupload), so you can build a bot on your own personal account:

• ✅ Send text, photos, videos, voice notes
• ✅ React, edit and unsend messages
• ✅ Listen for incoming DMs — realtime MQTT push or polling — and dispatch them to your own commands
• ✅ Typing indicators, mark-seen, mute/unmute, hide
• ✅ Users — lookup by id / username, search
• ✅ Pure HTTP at runtime — no Puppeteer, no browser, no native build

⚠️ Unofficial. Not affiliated with Instagram or Meta. Use only on accounts you own and at your own risk. This package automates a personal account, not the official Instagram Business API.

📦 Installation

npm install @eryxenx/insta-chat

Requires Node.js >= 18.

🚀 Quick start

const login = require("@eryxenx/insta-chat");

// `cookie` is your browser cookie string (needs at least `sessionid`).
login(cookie, (err, api) => {
  if (err) return console.error("Login error:", err.message);
  console.log("Logged in as", api.username || api.userID);

  // send a DM
  api.sendMessage("Hello from my bot 👋", "340282366841710300949128138275732109616");
});

Promise style works too:

const api = await login(cookie);
await api.sendMessage("hi", threadID);

Getting the cookie

Log in to https://www.instagram.com in a browser, open DevTools → Network → copy the Cookie request header (it contains sessionid, ds_user_id, csrftoken, ig_did). Paste the whole string; only sessionid is mandatory.

🧠 Session params (important)

Instagram's web API rejects requests that do not carry the browser session params (__dyn, __csr, __hs, __hsi, __s, fb_dtsg, jazoest, ...). They are produced by Instagram's own JS bundle but are session-scoped, so one real browser page load is enough — capture once, reuse until it expires.

const { harvestSessionParams, findChromium } = require("@eryxenx/insta-chat");

const params = await harvestSessionParams({ /* cookie jar */ });
// -> { __dyn, __csr, __hs, fb_dtsg, lsd, ... }

harvestSessionParams drives a system Chrome/Chromium through puppeteer-core (optional dependency, no browser download). Pass the result to login:

const api = await login(cookie, { sessionParams: params });

If you skip this, the package still tries to bootstrap the minimum tokens (fb_dtsg, lsd) from the Instagram home page automatically. When the params go stale use api.refreshSession().

📚 API

Login

options: { native, sessionParams, sessionParamsFile, deviceFile, pollInterval, minPollIntervalMs, realtime }.

To make listen() push instead of poll, opt into realtime MQTT:

const api = await login(cookie, { realtime: { enabled: true } });

realtime is { enabled, fallback, host, keepAliveMs }. With fallback !== false (the default) a broker that will not connect degrades to the inbox poller, so the bot still gets events. keepAliveMs is the PINGREQ interval; it must stay below the CONNECT keep-alive (60 s) and defaults to 25 s. See Listening.

Two layers

The FCA methods are one file each under src/api/<group>/<method>.js; adding a method is adding a file. createFcaClient(client) gives a namespaced view (messages.send(), threads.getInfo()); new InstaContext(client, threadID) binds a thread. EventNormalizer maps raw inbox events to the FCA event shape.

Messaging (FCA surface)

Messaging (native InstaAPI)

Media

opts: { filename, text }.

Threads & users

Full profiles (getUserInfoV2 / getUserProfile)

V1 getUserInfo returns a small fca-shaped subset. V2 returns every detail a web session can read, and it is logout-safe: profile lookups go through a resolver that tries several sources and never turns a rate-limit (429) or a login redirect (302) into a dead-session error - the bug that used to log the bot out whenever a command looked up a profile.

Sources, merged in order (a field a source cannot supply stays null):

1. Inbox/thread record - the users the client has already seen in the DM views. Free, needs no request, and the only source that still answers once the profile REST paths 429. getInbox() populates it automatically.
2. web_profile_info REST - canonical counts (followers/following/media), biography, verified/private/business flags, external url, category.
3. Profile GraphQL (PolarisProfilePageContentQuery) - richest payload when Instagram answers it.
4. The account's own page - the home shell Instagram server-renders embeds the logged-in account's full profile, so self always resolves.

const info = await api.getUserInfoV2("32715034217");
// info["32715034217"] => { id, username, name, biography, followerCount,
//   followingCount, mediaCount, isVerified, isPrivate, isBusinessAccount,
//   externalUrl, category, profilePicUrl, profilePicUrlHd, fbid, ... }

const profile = await api.getUserProfile("@someuser");   // the raw merged object
const pic     = await api.getProfilePictureV2("someuser", { size: 640 });
// pic => { url, hd, thumb, sizes: { "150": ..., "320": ..., "640": ..., "1080": ... } }

Listening

const stop = api.listen((err, event) => {
  if (err) return console.error(err.message);
  console.log(event.senderID, "->", event.body);
  // event = { type, threadID, senderID, messageID, body, attachments, timestamp }
});

// later
stop();

listen uses the realtime MQTT stream when you pass { realtime: { enabled: true } } to login — Instagram pushes each new DM over the broker, so replies are near-instant. Without it, listen polls the inbox (default every 15s, override with options.pollInterval). Either way the callback and event shape are identical, and a realtime connection that fails falls back to polling unless you set realtime: { enabled: true, fallback: false }.

Realtime (MQTT)

Instagram's realtime broker (edge-mqtt.facebook.com) is an MQTToT connection authenticated by the same sessionid cookie — no app login. listen() drives it when realtime is enabled; you can also use it directly:

const api = await login(cookie, { native: true });

api.realtimeOn("message", (e) => console.log(e.message));
api.realtimeOn("typing", (e) => console.log(e.threadID, "is typing"));
api.realtimeOn("seen", (e) => console.log(e.threadID, "read"));
api.realtimeOn("presence", (e) => console.log(e.value));

await api.realtimeConnect();
await api.realtimeSubscribe();   // reads seq_id/snapshot_at_ms from the inbox query
// ...later
api.realtimeDisconnect();

realtimeConnect() reuses the client only while it is connected; after a drop it builds a fresh one, so attach your handlers to the client it returns and re-attach whenever it differs from the last one you saw:

let client = await api.realtimeConnect();
if (client !== previous) {
  client.on("direct", onRealtimeDirect);
  client.on("disconnected", () => reconnectLater());
  previous = client;
}

RealtimeClient (the raw client) and RealtimeListener (the listen() wrapper) are exported too, for callers that want to drive the socket themselves.

🧩 Example — a tiny DM bot

const login = require("@eryxenx/insta-chat");

(async () => {
  const api = await login(process.env.IG_COOKIE);

  api.listen(async (err, event) => {
    if (err || !event || !event.body) return;
    if (event.body === "/ping") await api.sendMessage("pong 🏓", event.threadID);
    await api.sendReaction(event.threadID, event.messageID, "✅");
  });
})();

🗂️ Project structure

See DOCS.md for the full protocol notes (GraphQL doc_ids, send / upload / reaction flows).

📋 Changelog

See CHANGELOG.md.

📄 License

Apache-2.0 © EryXenX

Credit required: you may use and modify this library, but you must keep the original copyright headers, the NOTICE file and the author credit (EryXenX), and clearly state your changes. Removing or replacing the credit violates the license.