nodejs-insta-private-api
Advanced tools
A pure JavaScript Instagram Private API client inspired by instagram-private-api
VERSION 3.3.1 Update library for latest Instagram Version
A pure JavaScript Instagram Private API client written in CommonJS without TypeScript.
Repository: Kunboruto20/nodejs-insta-private-api
npm install nodejs-insta-private-api
const { IgApiClient } = require('nodejs-insta-private-api');
async function main() {
const ig = new IgApiClient();
try {
await ig.login({
username: 'your_username',
password: 'your_password',
email: 'your_email@example.com'
});
console.log('✅ Logged in successfully!');
await ig.dm.send({
to: 'friend_username',
message: 'Hello from the API!'
});
console.log('✅ Message sent!');
} catch (error) {
console.error('❌ Error:', error.message);
}
}
main();
This library can be extended with instagram_mqttt to add Realtime and FBNS (Push Notifications) support.
npm install instagram_mqttt
import { IgApiClient } from 'nodejs-insta-private-api';
import { withFbnsAndRealtime, withFbns, withRealtime } from 'instagram_mqttt';
// wrap the client
// ig is now IgApiClientMQTT for typescript users
const ig = withFbnsAndRealtime(new IgApiClient());
// OR if you only want fbns/realtime
const igFbns = withFbns(new IgApiClient());
const igRealtime = withRealtime(new IgApiClient());
// login like you usually do or load the state
// use ig.realtime and ig.fbns
FBNS is for notifications (readonly). You can subscribe to any notification:
ig.fbns.on('push', (data) => {
console.log('Push notification:', data);
});
Or subscribe to a specific event:
ig.fbns.on('collapseKey', (data) => {
console.log('Specific notification:', data);
});
const { IgApiClient } = require('nodejs-insta-private-api');
const ig = new IgApiClient();
// Login with username and password
await ig.login({
username: 'your_username',
password: 'your_password',
email: 'your_email@example.com' // Optional but recommended
});
// Check if logged in
if (ig.isLoggedIn()) {
console.log('Successfully logged in!');
}
try {
await ig.login({ username, password, email });
} catch (error) {
if (error.name === 'IgLoginTwoFactorRequiredError') {
// Handle 2FA
const code = '123456'; // Get from user input
await ig.account.twoFactorLogin({
username,
verificationCode: code,
twoFactorIdentifier: error.response.data.two_factor_info.two_factor_identifier
});
}
}
const fs = require('fs');
// Save session after login
const session = await ig.saveSession();
fs.writeFileSync('session.json', JSON.stringify(session));
// Load session later
const loaded = JSON.parse(fs.readFileSync('session.json'));
await ig.loadSession(loaded);
// Check if session is still valid
if (await ig.isSessionValid()) {
console.log('Session is valid!');
} else {
console.log('Need to login again');
}
// Send to a single user
await ig.dm.send({
to: 'username',
message: 'Hello! 👋'
});
// Send to multiple users
await ig.dm.send({
to: ['user1', 'user2', 'user3'],
message: 'Group message!'
});
// Send to existing group by thread ID
await ig.dm.sendToGroup({
threadId: 'group_thread_id',
message: 'Hello group!'
});
// Create new group and send message
const group = await ig.direct.createGroupThread(
['user1', 'user2', 'user3'],
'My Group Name'
);
await ig.dm.sendToGroup({
threadId: group.thread_id,
message: 'Welcome to the group!'
});
// Send image
await ig.dm.sendImage({
to: 'username',
imagePath: './photo.jpg'
});
// Send video
await ig.dm.sendVideo({
to: 'username',
videoPath: './video.mp4'
});
// Get inbox
const inbox = await ig.dm.getInbox();
console.log(`You have ${inbox.inbox.threads.length} conversations`);
// Get specific thread
const thread = await ig.dm.getThread('thread_id');
// Mark messages as seen
for (const item of thread.thread.items) {
await ig.directThread.markItemSeen(thread.thread.thread_id, item.item_id);
}
// React with emoji
await ig.story.react({
storyId: 'story_media_id',
reaction: '❤️'
});
// React with different emojis
await ig.story.react({
storyId: 'story_media_id',
reaction: '🔥'
});
// Get story feed (stories tray)
const storyFeed = await ig.story.getFeed();
// Get specific user's stories
const userStories = await ig.story.getUser('user_id');
// Mark stories as seen
await ig.story.seen(userStories.reel.items);
// Upload photo story
await ig.story.upload({
imagePath: './story.jpg',
caption: 'My story! #instagram'
});
// Upload video story
await ig.story.uploadVideo({
videoPath: './story.mp4',
caption: 'Video story!',
duration_ms: 15000
});
// Get user's highlights
const highlights = await ig.story.getHighlights('user_id');
// Get specific highlight
const highlight = await ig.story.getHighlight('highlight_id');
// Upload photo
await ig.feed.upload({
imagePath: './photo.jpg',
caption: 'My awesome photo! #photography #instagram'
});
// Upload video
await ig.feed.uploadVideo({
videoPath: './video.mp4',
caption: 'Check out this video! 🎥',
duration_ms: 30000,
width: 720,
height: 1280
});
await ig.feed.uploadCarousel({
items: [
{ type: 'photo', path: './photo1.jpg' },
{ type: 'photo', path: './photo2.jpg' },
{ type: 'video', path: './video1.mp4', duration_ms: 15000 }
],
caption: 'My carousel post! Swipe to see more 👆'
});
// Get timeline feed
const timeline = await ig.feed.getFeed();
// Get user's posts
const userFeed = await ig.feed.getUserFeed('user_id');
// Get hashtag feed
const hashtagFeed = await ig.feed.getTag('photography');
// Get location feed
const locationFeed = await ig.feed.getLocation('location_id');
// Get explore feed
const exploreFeed = await ig.feed.getExploreFeed();
// Get liked posts
const likedPosts = await ig.feed.getLiked();
// Get saved posts
const savedPosts = await ig.feed.getSaved();
// Get user by username
const userByName = await ig.user.infoByUsername('instagram');
// Get user by ID
const userById = await ig.user.info('user_id');
// Search users
const users = await ig.user.search('john');
// Follow user
await ig.user.follow('user_id');
// Unfollow user
await ig.user.unfollow('user_id');
// Get followers
const followers = await ig.user.getFollowers('user_id');
// Get following
const following = await ig.user.getFollowing('user_id');
// Like a post
await ig.media.like('media_id');
// Unlike a post
await ig.media.unlike('media_id');
// Comment on a post
await ig.media.comment('media_id', 'Great post! 👍');
// Get post information
const mediaInfo = await ig.media.info('media_id');
// Get post likers
const likers = await ig.media.likers('media_id');
// Get post comments
const comments = await ig.media.comments('media_id');
// Edit post caption
await ig.media.edit('media_id', 'New caption text');
// Delete post
await ig.media.delete('media_id');
// Delete comment
await ig.media.deleteComment('media_id', 'comment_id');
const { IgApiClient } = require('nodejs-insta-private-api');
const Utils = require('nodejs-insta-private-api/dist/utils');
try {
await ig.login({ username, password, email });
} catch (error) {
console.log('Error type:', error.name);
console.log('Human readable:', Utils.humanizeError(error));
// Handle specific errors
switch (error.name) {
case 'IgLoginBadPasswordError':
console.log('Wrong password!');
break;
case 'IgLoginTwoFactorRequiredError':
console.log('2FA required');
break;
case 'IgCheckpointError':
console.log('Account verification required');
break;
case 'IgActionSpamError':
console.log('Action blocked - wait before retrying');
break;
default:
console.log('Unknown error:', error.message);
}
}
const Utils = require('nodejs-insta-private-api/dist/utils');
// Retry failed operations
await Utils.retryOperation(async () => {
return await ig.dm.send({ to: 'username', message: 'Hello!' });
}, 3, 2000); // 3 retries, 2 second delay
const Utils = require('nodejs-insta-private-api/dist/utils');
// Add delays between requests
await ig.dm.send({ to: 'user1', message: 'Hello!' });
await Utils.randomDelay(1000, 3000); // Wait 1-3 seconds
await ig.dm.send({ to: 'user2', message: 'Hello!' });
// Send messages to multiple users with delays
const users = ['user1', 'user2', 'user3'];
const message = 'Hello from the API!';
for (const user of users) {
try {
await ig.dm.send({ to: user, message });
console.log(`✅ Message sent to ${user}`);
// Wait between requests to avoid rate limiting
await Utils.randomDelay(2000, 5000);
} catch (error) {
console.log(`❌ Failed to send to ${user}:`, error.message);
}
}
const Utils = require('nodejs-insta-private-api/dist/utils');
// Validate files before uploading
if (Utils.isImageFile('./photo.jpg') && Utils.validateFileSize('./photo.jpg', 8 * 1024 * 1024)) {
await ig.feed.upload({
imagePath: './photo.jpg',
caption: 'Valid image!'
});
} else {
console.log('Invalid file!');
}
Main client class for interacting with Instagram.
const ig = new IgApiClient();
login(credentials) - Login with username/passwordlogout() - Logout and clear sessionisLoggedIn() - Check if currently logged insaveSession() - Save current sessionloadSession(session) - Load saved sessionisSessionValid() - Check if session is validdestroy() - Cleanup resourcesconnectRealtime() - Connect to MQTT brokerdisconnectRealtime() - Disconnect from MQTT brokerisRealtimeConnected() - Check connection statuspingRealtime() - Send ping to brokergetRealtimeStats() - Get connection statisticssetRealtimeReconnectOptions(options) - Configure reconnection behaviorAll repositories are accessible through the main client:
ig.account - Account operationsig.user - User operationsig.direct - Direct message operationsig.directThread - Thread managementig.media - Media operationsig.upload - File uploadsig.story - Story operationsig.feed - Feed operationsig.dm - Shortcut for common DM operations
send(options) - Send messagesendToGroup(options) - Send to groupsendImage(options) - Send imagesendVideo(options) - Send videogetInbox() - Get inboxgetThread(id) - Get threadaxios - HTTP clienttough-cookie - Cookie managementform-data - Form data handlingchance - Random data generationlodash - Utility functionsRepository: Kunboruto20/nodejs-insta-private-api
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
This library is for educational purposes only. Use at your own risk and in compliance with Instagram's Terms of Service. The authors are not responsible for any misuse of this library.
If you find this library useful, please consider:
FAQs
A pure JavaScript Instagram Private API client inspired by instagram-private-api
The npm package nodejs-insta-private-api receives a total of 753 weekly downloads. As such, nodejs-insta-private-api popularity was classified as not popular.
We found that nodejs-insta-private-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious Chrome extension posing as an Ethereum wallet steals seed phrases by encoding them into Sui transactions, enabling full wallet takeover.
Security News
Socket is heading to London! Stop by our booth or schedule a meeting to see what we've been working on.
Security News
OWASP’s 2025 Top 10 introduces Software Supply Chain Failures as a new category, reflecting rising concern over dependency and build system risks.