nodejs-insta-private-api-mqtt 1.3.14 → 1.3.16

package/README.md

@@ -262,53 +262,182 @@ startBot().catch(console.error);
 
 ---
 
-## 🖼️ FIXED: Send Media via MQTT (v5.70.0)
 
-The upload issue has been fully resolved. You can now send photos and videos directly through the MQTT protocol. The library now handles raw buffers correctly, matching the Instagram internal protocol for zero "Upload Failed" errors.
+## 🖼️ IMPORTANT: How media actually works (photos & videos)
 
-### Send Media via MQTT (v5.70.0)
+## 🖼️ IMPORTANT: How media actually works (photos & videos) — UPDATED (rupload + MQTT reference)
 
-You can now send photos, videos, voice messages, and more directly through the MQTT protocol. The library handles the upload and linking automatically.
+> **Clarification (APK + client behaviour):**  
+> The mobile app uploads raw media bytes via **HTTP rupload** (rupload_igphoto / rupload_igvideo). After the rupload completes and the app receives an `upload_id`, the app **notifies Instagram's realtime layer (MQTT)** that "there is media with `upload_id` — attach it to thread X".  
+>
+> **Key points**
+> - **Media bytes are uploaded over HTTP (rupload).** MQTT never carries the raw image/video bytes.
+> - **MQTT is used as a realtime *reference/notification* channel**: the client publishes a `send_item` command containing `item_type: "media"` and `upload_id: "<id>"`. That tells the server: "the media exists; attach it to this thread".
+> - In some cases the client also calls HTTP broadcast/configure endpoints. The exact flow can vary by platform/version; the APK shows the pattern `RuploadClient.upload() -> upload_id` then `SendMessage.sendMedia(upload_id)` (MQTT). The hybrid pattern below matches that behavior.
 
-#### 📷 Send a Photo
-```javascript
-const photoBuffer = fs.readFileSync('./image.jpg');
-const upload = await ig.publish.photo({ file: photoBuffer });
+---
 
-await realtime.directCommands.sendMedia({
-  threadId: 'THREAD_ID',
-  mediaId: upload.upload_id,
-  uploadId: upload.upload_id
-});
-```
+### Correct / supported patterns
+
+There are two practical, compatible flows you can use depending on your client helpers and what the server expects:
+
+**A) Hybrid (rupload HTTP -> MQTT reference broadcast)** — matches what the APK does in many versions  
+1. Upload bytes to rupload_igphoto / rupload_igvideo (HTTP) -> receive `upload_id`.  
+2. Publish an MQTT `send_item` with `item_type: "media"` and `upload_id`: this tells the realtime server to attach the previously uploaded media to the thread.  
+   - MQTT payload is **only the metadata** (JSON), typically compressed/deflated by the realtime client before publish.  
+   - This is the recommended **APK-compatible** approach.
+
+**B) Full HTTP (rupload HTTP -> configure/broadcast HTTP)** — always works, server-side creation via REST  
+1. Upload bytes to rupload endpoint (HTTP) -> receive `upload_id`.  
+2. Call the direct broadcast / configure_photo or configure_video HTTP endpoint to create the message server-side. MQTT will then deliver the server-created message to connected clients.  
+   - Use this if you prefer to avoid relying on the realtime command to create messages.
+
+> Summary: **Always rupload via HTTP.** Then either broadcast via HTTP (configure endpoints) or publish an MQTT `send_item` referencing `upload_id`. MQTT does not carry the media bytes, only the reference.
+
+---
+
+### Example: Hybrid flow — Photo (rupload HTTP then MQTT reference)
+
+This example shows the two steps required. It assumes you have `ig.request.send` for HTTP and a `realtime.mqtt.publish()` helper for MQTT. It also shows the `compressDeflate` helper pattern used in this project.
 
-#### 🎥 Send a Video
 ```javascript
-const videoBuffer = fs.readFileSync('./video.mp4');
-const upload = await ig.publish.video({
-  video: videoBuffer,
-  duration: 10000, // ms
+// 1) RUUPLOAD (HTTP) - upload bytes and get upload_id
+const uploadId = Date.now().toString(); // or use library helper that returns upload_id
+const objectName = `${uploadId}_${Math.floor(Math.random()*1e9)}.jpg`;
+
+const ruploadParams = {
+  upload_id: uploadId,
+  media_type: 1, // photo
+  image_compression: '{"lib_name":"moz","lib_version":"3.1.m","quality":"80"}',
+  xsharing_user_ids: JSON.stringify([]),
+  is_clips_media: false,
+};
+
+const headers = {
+  'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+  'Content-Type': 'image/jpeg',
+  'X-Entity-Type': 'image/jpeg',
+  'X-Entity-Length': String(photoBuffer.length),
+  'Content-Length': String(photoBuffer.length),
+};
+
+// send bytes to /rupload_igphoto/<objectName>
+await ig.request.send({
+  url: `/rupload_igphoto/${objectName}`,
+  method: 'POST',
+  headers,
+  body: photoBuffer,
+  timeout: 120000,
 });
 
-await realtime.directCommands.sendMedia({
-  threadId: 'THREAD_ID',
-  mediaId: upload.upload_id,
-  uploadId: upload.upload_id
+// server should now provide or accept the upload_id (uploadId)
+
+// 2) MQTT publish - tell realtime: "attach upload_id X to thread Y"
+const clientContext = require('uuid').v4();
+const command = {
+  action: 'send_item',
+  thread_id: String(threadId),
+  item_type: 'media',
+  upload_id: String(uploadId),
+  text: caption || '',
+  timestamp: Date.now(),
+  client_context: clientContext
+};
+
+// compress the JSON (match client's compress method)
+const json = JSON.stringify(command);
+const payload = await compressDeflate(json); // project helper
+
+// publish to MQTT send_message topic
+await mqtt.publish({
+  topic: Topics.SEND_MESSAGE.id,
+  qosLevel: 1,
+  payload: payload
 });
 ```
 
-#### 🎤 Send Voice Message
+**Notes**
+- This sends only a *reference* to the server. The bytes were already sent via rupload.
+- The APK calls something equivalent to `RuploadClient.upload()` then `SendMessage.sendMedia(upload_id)` — the second call is an MQTT notification that references `upload_id`.
+
+---
+
+### Example: Hybrid flow — Video (rupload HTTP then MQTT reference)
+
 ```javascript
-const audioBuffer = fs.readFileSync('./voice.mp4');
-const upload = await ig.publish.audio({ file: audioBuffer });
+// 1) RUUPLOAD (video)
+const uploadId = Date.now().toString();
+const objectName = `${uploadId}_${Math.floor(Math.random()*1e9)}.mp4`;
+
+const ruploadParams = {
+  upload_id: uploadId,
+  media_type: 2, // video
+  xsharing_user_ids: JSON.stringify([]),
+  upload_media_duration_ms: Math.round(duration * 1000),
+  upload_media_width: width,
+  upload_media_height: height
+};
+
+const headers = {
+  'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+  'Content-Type': 'video/mp4',
+  'X-Entity-Type': 'video/mp4',
+  'X-Entity-Length': String(videoBuffer.length),
+  'Content-Length': String(videoBuffer.length),
+  'Offset': '0'
+};
+
+await ig.request.send({
+  url: `/rupload_igvideo/${objectName}`,
+  method: 'POST',
+  headers,
+  body: videoBuffer,
+  timeout: 300000
+});
 
-await realtime.directCommands.sendMedia({
-  threadId: 'THREAD_ID',
-  mediaId: upload.upload_id,
-  uploadId: upload.upload_id
+// 2) MQTT publish - notify realtime to attach upload_id to thread
+const command = {
+  action: 'send_item',
+  thread_id: String(threadId),
+  item_type: 'media',
+  upload_id: String(uploadId),
+  text: caption || '',
+  timestamp: Date.now(),
+  client_context: require('uuid').v4()
+};
+
+const payload = await compressDeflate(JSON.stringify(command));
+await mqtt.publish({
+  topic: Topics.SEND_MESSAGE.id,
+  qosLevel: 1,
+  payload: payload
 });
 ```
 
+---
+
+### Short FAQ & Troubleshooting
+
+- **Q:** *Can I send the raw image through MQTT?*  
+  **A:** No — MQTT is not used for large raw bytes. The app uploads bytes via rupload HTTP.
+
+- **Q:** *If I publish the MQTT `send_item` with `upload_id`, will the message appear in the thread?*  
+  **A:** Yes — the realtime server accepts an MQTT `send_item` referencing a valid `upload_id`. The server will attempt to create/attach the media message and then propagate the message via MESSAGE_SYNC to other clients. The exact behavior can differ between server versions, so keep fallback to HTTP broadcast if reliability is essential.
+
+- **Q:** *Do I need to call `/direct_v2/threads/broadcast/...` if I published MQTT?*  
+  **A:** Often not — the APK pattern uses MQTT for the attach request. However, for absolute compatibility or for older server behavior, the HTTP configure/broadcast endpoints are a safe fallback.
+
+---
+
+### Security & Best Practices
+
+- Ensure `upload_id` you publish via MQTT is the one returned by rupload; otherwise servers will reject or ignore it.
+- Keep rupload headers accurate (`X-Entity-Length`, `X-Instagram-Rupload-Params`, etc.).
+- Use `client_context` (UUID) per message to track mutations.
+- Implement retries and exponential backoff for both rupload and MQTT publish.
+- Log both the rupload response and the MQTT publish result for debugging.
+
+---
 
 We've completely overhauled how the MQTT connection works. You no longer need to manually manage connection states every time your bot restarts. Just like **Baileys**, if a session is present in the default folder, the library takes care of everything for you.
 
@@ -1359,6 +1488,205 @@ const fs = require('fs');
 
 ---
 
+
+---
+
+### Example 3: CLI Photo Sender (upload HTTP + broadcast HTTP, with MQTT sync)
+
+This example is a ready-to-run CLI script that demonstrates the correct flow to **send a photo** to one or more threads:
+1. upload the photo to Instagram's rupload endpoint (HTTP),
+2. broadcast (configure) the photo to the target thread(s) using the Direct API (HTTP),
+3. use MQTT (RealtimeClient) only for realtime sync and confirmation.
+
+Save this as `examples/send-photo-cli.js`.
+
+```javascript
+#!/usr/bin/env node
+// examples/send-photo-cli.js
+// Node 18+, install nodejs-insta-private-api-mqtt in the project
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline/promises');
+const { stdin: input, stdout: output } = require('process');
+const { v4: uuidv4 } = require('uuid');
+
+(async () => {
+  const rl = readline.createInterface({ input, output });
+  try {
+    console.log('\\n--- Instagram Photo Sender (HTTP + broadcast) ---\\n');
+    const username = (await rl.question('Enter your Instagram username: ')).trim();
+    const password = (await rl.question('Enter your Instagram password: ')).trim();
+    if (!username || !password) {
+      console.error('username & password required'); process.exit(1);
+    }
+
+    const { IgApiClient, RealtimeClient, useMultiFileAuthState } = require('nodejs-insta-private-api-mqtt');
+    const AUTH_FOLDER = path.resolve(process.cwd(), './auth_info_instagram');
+
+    const authState = await useMultiFileAuthState(AUTH_FOLDER);
+    const ig = new IgApiClient();
+    ig.state.generateDevice?.(username);
+
+    // load saved credentials if available
+    if (authState.hasSession && authState.hasSession()) {
+      try { await authState.loadCreds?.(ig); console.log('[*] Loaded saved creds'); } catch(e){}
+    }
+
+    // login if needed
+    if (!authState.hasSession || (typeof authState.hasSession === 'function' && !authState.hasSession())) {
+      await ig.login({ username, password });
+      await authState.saveCreds?.(ig);
+      console.log('[+] Logged in and saved creds');
+    }
+
+    // start realtime client (optional, helps sync)
+    const realtime = new RealtimeClient(ig);
+    realtime.on?.('connected', () => console.log('✅ MQTT connected (realtime)'));
+
+    // fetch inbox and list threads
+    const inbox = await ig.direct.getInbox();
+    const threads = inbox.threads || inbox.items || inbox.threads_response?.threads || [];
+    if (!threads || threads.length === 0) {
+      console.error('No threads found in inbox. Exiting.'); process.exit(1);
+    }
+
+    console.log('\\nAvailable threads:');
+    const indexToThread = [];
+    threads.slice(0, 50).forEach((t, i) => {
+      const id = String(t.thread_id || t.threadId || t.id || t.thread_id_str || (t.thread && t.thread.thread_id) || '');
+      const title = t.thread_title || t.title || t.item_title || (t.users || t.participants || []).map(u => u.username || u.full_name).slice(0,3).join(', ') || 'Unnamed';
+      indexToThread.push({ id, title });
+      console.log(`${i+1}. ${title} (thread_id: ${id})`);
+    });
+
+    const pick = (await rl.question('\\nSelect thread numbers (e.g. "1 2 3"): ')).trim();
+    const picks = pick.split(/[\s,]+/).map(x => parseInt(x,10)).filter(n => Number.isFinite(n) && n >= 1 && n <= indexToThread.length);
+    const selected = picks.map(p => indexToThread[p-1].id);
+
+    const photoPath = (await rl.question('\\nEnter your Photo path here (absolute or relative): ')).trim();
+    const resolved = path.isAbsolute(photoPath) ? photoPath : path.resolve(process.cwd(), photoPath);
+    if (!fs.existsSync(resolved)) { console.error('File not found', resolved); process.exit(1); }
+    const buffer = fs.readFileSync(resolved);
+    console.log('Photo size (MB):', (buffer.length/(1024*1024)).toFixed(2));
+
+    // RUUPLOAD (HTTP) - try to use ig.publish.photo helper if available
+    let uploadId;
+    try {
+      if (typeof ig.publish?.photo === 'function') {
+        const up = await ig.publish.photo({ file: buffer });
+        uploadId = up.upload_id || up.uploadId || up;
+      } else {
+        // manual rupload via request
+        uploadId = Date.now().toString();
+        const objectName = `${uploadId}_0_${Math.floor(Math.random() * 1e10)}`;
+        const ruploadParams = {
+          retry_context: JSON.stringify({ num_step_auto_retry: 0, num_reupload: 0, num_step_manual_retry: 0 }),
+          media_type: '1',
+          upload_id: uploadId,
+          xsharing_user_ids: JSON.stringify([]),
+          image_compression: JSON.stringify({ lib_name: 'moz', lib_version: '3.1.m', quality: '80' })
+        };
+        const headers = {
+          'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+          'Content-Type': 'application/octet-stream',
+          'X-Entity-Type': 'image/jpeg',
+          'Offset': '0',
+          'X-Entity-Name': objectName,
+          'X-Entity-Length': String(buffer.length),
+          'Content-Length': String(buffer.length),
+        };
+        await ig.request.send({
+          url: `/rupload_igphoto/${objectName}`,
+          method: 'POST',
+          headers,
+          body: buffer,
+          timeout: 120000,
+        });
+      }
+      console.log('[+] Upload completed. upload_id =', uploadId);
+    } catch (err) {
+      console.error('Upload failed:', err?.message || err); process.exit(1);
+    }
+
+    // BROADCAST (HTTP) - create message on server
+    try {
+      const mutationToken = uuidv4();
+      const payload = {
+        action: 'configure_photo',
+        upload_id: String(uploadId),
+        thread_ids: JSON.stringify(selected),
+        client_context: mutationToken,
+        mutation_token: mutationToken,
+        _csrftoken: ig.state.cookieCsrfToken || '',
+        _uuid: ig.state.uuid || '',
+        device_id: ig.state.deviceId || ''
+      };
+      const resp = await ig.request.send({
+        url: '/api/v1/direct_v2/threads/broadcast/configure_photo/',
+        method: 'POST',
+        form: payload,
+        timeout: 60000,
+      });
+      console.log('✅ Broadcast response received:', resp && (resp.status || resp.body || resp.data) ? 'OK' : JSON.stringify(resp).slice(0,120));
+    } catch (err) {
+      console.error('Broadcast failed:', err?.message || err);
+      process.exit(1);
+    }
+
+    console.log('\\nDone. MQTT will sync and you should see the message in the app.');
+    rl.close();
+    process.exit(0);
+  } catch (e) {
+    console.error('Fatal:', e);
+    process.exit(1);
+  }
+})();
+```
+
+---
+
+### Example 4: Video Sender (upload + broadcast)
+
+This is similar to the photo sender but uses the video upload flow and longer timeouts. Use `ig.publish.video()` if available; otherwise rupload manually and call `/api/v1/direct_v2/threads/broadcast/configure_video/`.
+
+```javascript
+// pseudo-code outline
+const videoBuffer = fs.readFileSync('./video.mp4');
+const upload = await ig.publish.video({ video: videoBuffer, duration: 12000 });
+// upload.upload_id -> then broadcast with configure_video payload similar to the photo flow
+```
+
+**Notes:** video uploads often require multipart/segmented upload and longer timeouts; prefer library helper `ig.publish.video()`.
+
+---
+
+### Example 5: Share a file / document (workaround)
+
+Instagram DM does not provide a simple "attach arbitrary file" endpoint. Common workarounds:
+
+1. Upload the file to a hosting service (S3, Dropbox, your own server), then send the link as a text message via MQTT (or HTTP direct send).  
+2. If the file is an image or video, use the rupload + broadcast flow above.
+
+Example (send link message):
+
+```javascript
+// send link as text via realtime (MQTT)
+await realtime.directCommands.sendTextViaRealtime(threadId, 'Download the file here: https://myhost.example.com/myfile.pdf');
+```
+
+---
+
+### Tips for bots sending media
+
+- Always **upload first**, then **broadcast**. Do not rely on MQTT-only calls for media.
+- Use retries and exponential backoff for both rupload and broadcast steps (Instagram can return transient 503).
+- Save `upload_id` and broadcast responses for debugging.
+- If you need to send the same file to many threads, upload once, reuse the same `upload_id` in multiple broadcast calls.
+
+---
+
+
 ## API Reference
 
 ### IgApiClient
@@ -1710,3 +2038,241 @@ For issues, bugs, or feature requests: https://github.com/Kunboruto20/nodejs-ins
 Documentation: https://github.com/Kunboruto20/nodejs-insta-private-api
 
 Examples: See repository examples/ directory for working implementations
+
+
+---
+
+## Examples using `ig.request.send` wrapper (photo & video, MQTT *reference* + REST broadcast)
+
+Below are practical code snippets that use the `ig.request.send` wrapper (the same request helper used inside the Instagram client).  
+Each example shows **two flows** so you can pick the behavior you want:
+
+1. **MQTT reference flow** — upload via `rupload` (HTTP) to obtain `upload_id` then **publish an MQTT `send_item` that contains only the `upload_id`** (Instagram attaches the already-uploaded file to the thread). This matches the APK behavior: MQTT only carries a reference, not the binary.
+2. **REST broadcast flow** — upload via `rupload` (HTTP) and then call the `direct_v2` broadcast REST endpoint to attach the uploaded media to a thread (alternate, server-side broadcast).
+
+> Note: these examples assume your runtime has access to:
+> - `ig` (Instagram client wrapper) and `ig.request.send` method,
+> - `mqtt` connected client exposing `.publish({ topic, qosLevel, payload })`,
+> - `compressDeflate` helper (same as in project `shared`),
+> - `uuid` (for `client_context` generation), and
+> - `constants.Topics.SEND_MESSAGE.id` for the MQTT send topic.
+
+### Photo — MQTT reference example (rupload via `ig.request.send` then MQTT reference)
+```javascript
+// Photo upload -> get upload_id (rupload) -> publish MQTT 'send_item' with upload_id
+const { v4: uuidv4 } = require('uuid');
+
+async function sendPhotoAsMqttReference({ ig, mqtt, photoBuffer, threadId, caption = '' }) {
+  if (!ig || !ig.request) throw new Error('ig.request not available');
+  if (!mqtt || typeof mqtt.publish !== 'function') throw new Error('mqtt client not available');
+  if (!Buffer.isBuffer(photoBuffer)) throw new Error('photoBuffer must be a Buffer');
+
+  // 1) perform rupload via ig.request.send
+  const uploadId = Date.now().toString();
+  const objectName = `${uuidv4()}.jpg`;
+  const ruploadParams = {
+    upload_id: uploadId,
+    media_type: 1,
+    image_compression: '{"lib_name":"moz","lib_version":"3.1.m","quality":"80"}',
+    xsharing_user_ids: JSON.stringify([]),
+  };
+
+  const uploadHeaders = {
+    'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+    'Content-Type': 'image/jpeg',
+    'X-Entity-Type': 'image/jpeg',
+    'X-Entity-Length': String(photoBuffer.length),
+    'Content-Length': String(photoBuffer.length),
+  };
+
+  const uploadUrl = `/rupload_igphoto/${objectName}`;
+
+  const uploadResponse = await ig.request.send({
+    url: uploadUrl,
+    method: 'POST',
+    headers: uploadHeaders,
+    body: photoBuffer,
+  });
+
+  const serverUploadId = (uploadResponse && uploadResponse.upload_id) ? uploadResponse.upload_id : uploadId;
+
+  // 2) publish MQTT reference telling server "attach upload_id X to thread Y"
+  const clientContext = uuidv4();
+  const command = {
+    action: 'send_item',
+    thread_id: String(threadId),
+    item_type: 'media',
+    upload_id: serverUploadId,
+    text: caption || '',
+    client_context: clientContext,
+    timestamp: Date.now(),
+  };
+
+  const json = JSON.stringify(command);
+  const payload = await compressDeflate(json); // reuse shared helper
+  await mqtt.publish({
+    topic: constants.Topics.SEND_MESSAGE.id,
+    qosLevel: 1,
+    payload,
+  });
+
+  return { upload_id: serverUploadId };
+}
+```
+
+### Photo — REST broadcast example (rupload via `ig.request.send` then direct_v2 broadcast)
+```javascript
+// Photo upload -> rupload via ig.request.send -> REST broadcast to the thread
+async function sendPhotoViaRestBroadcast({ ig, photoBuffer, threadId, caption = '' }) {
+  const uploadId = Date.now().toString();
+  const objectName = `${uuidv4()}.jpg`;
+
+  const ruploadParams = {
+    upload_id: uploadId,
+    media_type: 1,
+    image_compression: '{"lib_name":"moz","lib_version":"3.1.m","quality":"80"}',
+    xsharing_user_ids: JSON.stringify([]),
+  };
+
+  const uploadResponse = await ig.request.send({
+    url: `/rupload_igphoto/${objectName}`,
+    method: 'POST',
+    headers: {
+      'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+      'Content-Type': 'image/jpeg',
+      'X-Entity-Type': 'image/jpeg',
+      'X-Entity-Length': String(photoBuffer.length),
+      'Content-Length': String(photoBuffer.length),
+    },
+    body: photoBuffer,
+  });
+
+  const serverUploadId = (uploadResponse && uploadResponse.upload_id) ? uploadResponse.upload_id : uploadId;
+
+  // Broadcast attach via REST endpoint
+  const broadcastResponse = await ig.request.send({
+    url: '/direct_v2/threads/broadcast/upload_photo/',
+    method: 'POST',
+    form: {
+      upload_id: serverUploadId,
+      action: 'send_item',
+      thread_ids: JSON.stringify([String(threadId)]),
+      caption: caption || '',
+    },
+  });
+
+  return { upload_id: serverUploadId, broadcastResponse };
+}
+```
+
+### Video — MQTT reference example (rupload video + MQTT reference)
+```javascript
+// Video upload -> rupload video via ig.request.send -> MQTT reference
+async function sendVideoAsMqttReference({ ig, mqtt, videoBuffer, threadId, caption = '', duration = 0, width = 720, height = 1280 }) {
+  const uploadId = Date.now().toString();
+  const objectName = `${uuidv4()}.mp4`;
+
+  const ruploadParams = {
+    upload_id: uploadId,
+    media_type: 2, // video
+    xsharing_user_ids: JSON.stringify([]),
+    upload_media_duration_ms: Math.round(duration * 1000),
+    upload_media_width: width,
+    upload_media_height: height,
+  };
+
+  const uploadResponse = await ig.request.send({
+    url: `/rupload_igvideo/${objectName}`,
+    method: 'POST',
+    headers: {
+      'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+      'Content-Type': 'video/mp4',
+      'X-Entity-Type': 'video/mp4',
+      'X-Entity-Length': String(videoBuffer.length),
+      'Content-Length': String(videoBuffer.length),
+      'Offset': '0',
+    },
+    body: videoBuffer,
+  });
+
+  const serverUploadId = (uploadResponse && uploadResponse.upload_id) ? uploadResponse.upload_id : uploadId;
+
+  // Publish MQTT reference
+  const clientContext = uuidv4();
+  const command = {
+    action: 'send_item',
+    thread_id: String(threadId),
+    item_type: 'media',
+    upload_id: serverUploadId,
+    text: caption || '',
+    client_context: clientContext,
+    timestamp: Date.now(),
+  };
+
+  const json = JSON.stringify(command);
+  const payload = await compressDeflate(json);
+  await mqtt.publish({
+    topic: constants.Topics.SEND_MESSAGE.id,
+    qosLevel: 1,
+    payload,
+  });
+
+  return { upload_id: serverUploadId };
+}
+```
+
+### Video — REST broadcast example (rupload video + direct_v2 broadcast)
+```javascript
+async function sendVideoViaRestBroadcast({ ig, videoBuffer, threadId, caption = '', duration = 0, width = 720, height = 1280 }) {
+  const uploadId = Date.now().toString();
+  const objectName = `${uuidv4()}.mp4`;
+
+  const ruploadParams = {
+    upload_id: uploadId,
+    media_type: 2,
+    xsharing_user_ids: JSON.stringify([]),
+    upload_media_duration_ms: Math.round(duration * 1000),
+    upload_media_width: width,
+    upload_media_height: height,
+  };
+
+  const uploadResponse = await ig.request.send({
+    url: `/rupload_igvideo/${objectName}`,
+    method: 'POST',
+    headers: {
+      'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+      'Content-Type': 'video/mp4',
+      'X-Entity-Type': 'video/mp4',
+      'X-Entity-Length': String(videoBuffer.length),
+      'Content-Length': String(videoBuffer.length),
+      'Offset': '0',
+    },
+    body: videoBuffer,
+  });
+
+  const serverUploadId = (uploadResponse && uploadResponse.upload_id) ? uploadResponse.upload_id : uploadId;
+
+  const broadcastResponse = await ig.request.send({
+    url: '/direct_v2/threads/broadcast/upload_video/',
+    method: 'POST',
+    form: {
+      upload_id: serverUploadId,
+      action: 'send_item',
+      thread_ids: JSON.stringify([String(threadId)]),
+      video_result: '',
+      caption: caption || '',
+    },
+  });
+
+  return { upload_id: serverUploadId, broadcastResponse };
+}
+```
+
+### FAQ notes
+- **Does MQTT send the file?** No — MQTT only transports the JSON reference (`upload_id`) telling the server to attach that already-uploaded file into the thread.
+- **Why use MQTT for reference instead of REST broadcast?** MQTT gives near-realtime messaging semantics; the server applies the `upload_id` to the thread (same result), but the heavy binary upload must be done via HTTP `rupload`.
+- **Can you skip rupload and only send MQTT?** No — server needs the binary available under the `upload_id`. If you send only MQTT without previously uploading, the server won't have the file to attach.
+
+---
+
+(Section added programmatically: `Examples using ig.request.send` — appended to the existing README content.)