ig-web-node-client

Instagram Web API 🚀

A powerful and comprehensive Node.js library for interacting with Instagram's Web API. Built with modern JavaScript and designed to be simple, reliable, and feature-complete.

✨ Features

• 🔐 Authentication - Login, logout, 2FA support
• 📱 Device Simulation - Realistic device fingerprinting
• 📰 Feeds - Timeline, user posts, hashtags, locations, stories
• 💬 Direct Messages - Send/receive DMs with real-time support
• 👥 User Management - Follow, unfollow, user info, followers/following
• 📸 Media Operations - Upload photos/videos, like, comment, save
• 📚 Stories & Highlights - View and manage stories
• 🔴 Live Streaming - Live video support
• 🎵 Music Integration - Music stickers and audio
• 🏷️ Collections - Save and organize posts
• 🔄 Real-time - MQTT support for instant notifications
• ⚡ Rate Limiting - Built-in rate limiting and error handling

📦 Installation

npm install instagram-web-api

🚀 Quick Start

const { InstagramClient } = require('instagram-web-api');

const client = new InstagramClient();

// Login
async function main() {
    try {
        const user = await client.login('your_username', 'your_password');
        console.log('Logged in as:', user.username);
        
        // Get timeline feed
        const timeline = client.feed.timeline();
        const posts = await timeline.getItems();
        console.log('Timeline posts:', posts.length);
        
        // Send a DM
        await client.direct.sendText('user_id', 'Hello from Instagram API!');
        
    } catch (error) {
        console.error('Error:', error.message);
    }
}

main();

📖 Documentation

Authentication

Basic Login

const client = new InstagramClient();
const user = await client.login('username', 'password');

Two-Factor Authentication

try {
    await client.login('username', 'password');
} catch (error) {
    if (error.name === 'AuthenticationError' && error.details.identifier) {
        // Enter 2FA code
        const code = '123456'; // Get from user input
        const user = await client.twoFactorLogin(code, error.details.identifier);
    }
}

Session Management

// Export session
const sessionData = client.exportState();
localStorage.setItem('instagram_session', sessionData);

// Import session
const sessionData = localStorage.getItem('instagram_session');
client.importState(sessionData);

User Operations

Get User Information

const userInfo = await client.user.getById('user_id');
const userByUsername = await client.user.getByUsername('username');

Follow/Unfollow Users

await client.friendship.follow('user_id');
await client.friendship.unfollow('user_id');

Get Followers/Following

const followers = client.feed.followers('user_id');
const following = client.feed.following('user_id');

const followersList = await followers.getItems();
const followingList = await following.getItems();

Media Operations

Upload Photo

const fs = require('fs');

const photoBuffer = fs.readFileSync('photo.jpg');
const result = await client.upload.photo({
    buffer: photoBuffer,
    caption: 'Check out this amazing photo! 📸'
});

Upload Video

const videoBuffer = fs.readFileSync('video.mp4');
const result = await client.upload.video({
    buffer: videoBuffer,
    caption: 'Cool video! 🎥',
    thumbnail: thumbnailBuffer // Optional
});

Like/Unlike Posts

await client.media.like('media_id');
await client.media.unlike('media_id');

Comment on Posts

await client.media.comment('media_id', 'Great post! 👍');

Feeds

Timeline Feed

const timeline = client.feed.timeline();
const posts = await timeline.getItems();

// Load more posts
const morePosts = await timeline.getItems();

User Feed

const userFeed = client.feed.user('user_id');
const userPosts = await userFeed.getItems();
const taggedPosts = await userFeed.getTaggedPosts();
const reels = await userFeed.getReels();

Hashtag Feed

const hashtagFeed = client.feed.hashtag('nature');
const posts = await hashtagFeed.getItems();

Location Feed

const locationFeed = client.feed.location('location_id');
const posts = await locationFeed.getItems();

Direct Messages

Send Messages

// Text message
await client.direct.sendText('user_id', 'Hello there! 👋');

// Photo message
await client.direct.sendPhoto('user_id', photoBuffer);

// Video message
await client.direct.sendVideo('user_id', videoBuffer);

// Share post
await client.direct.sharePost('user_id', 'media_id');

Get Inbox

const inbox = client.feed.directInbox();
const threads = await inbox.getItems();

Get Thread Messages

const thread = client.feed.directThread('thread_id');
const messages = await thread.getItems();

Stories

View Stories

const stories = client.feed.story();
const storyItems = await stories.getItems();

Upload Story

const storyResult = await client.story.upload({
    buffer: imageBuffer,
    type: 'photo' // or 'video'
});

Real-time Events

// Enable real-time events
await client.startRealtime();

// Listen for new messages
client.on('message', (message) => {
    console.log('New message:', message);
});

// Listen for typing indicators
client.on('typing', (data) => {
    console.log('User typing:', data);
});

// Listen for presence updates
client.on('presence', (data) => {
    console.log('User presence:', data);
});

Error Handling

const { InstagramError, AuthenticationError, RateLimitError } = require('instagram-web-api');

try {
    // Your Instagram API calls
} catch (error) {
    if (error instanceof AuthenticationError) {
        console.log('Authentication failed:', error.message);
    } else if (error instanceof RateLimitError) {
        console.log('Rate limited. Wait before retrying.');
    } else if (error instanceof InstagramError) {
        console.log('Instagram API error:', error.message);
    }
}

🔧 Advanced Configuration

Proxy Support

const client = new InstagramClient({
    proxy: {
        host: 'proxy.example.com',
        port: 8080,
        auth: {
            username: 'proxy_user',
            password: 'proxy_pass'
        }
    }
});

Custom Device

// Generate device for specific username
client.generateDevice('username');

// Or use existing device data
client.device.import({
    deviceId: 'your_device_id',
    uuid: 'your_uuid',
    // ... other device properties
});

🛡️ Rate Limiting

The library includes built-in rate limiting to prevent Instagram from blocking your requests:

• 200 requests per hour
• 10 requests per minute
• 1 second delay between requests

⚠️ Disclaimer

This library is for educational purposes only. Make sure to comply with Instagram's Terms of Service when using this library. The authors are not responsible for any misuse or violations.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see the LICENSE file for details.

🔗 Links

• Instagram Terms of Service
• Node.js Documentation

🐛 Issues

If you encounter any issues, please report them on our GitHub Issues page.

Made with ❤️ for the Instagram developer community