instagram-client-web

Instagram API Client

A robust, feature-rich Instagram API client library for Node.js that emulates browser interactions and provides comprehensive Instagram functionality.

🚀 Features

📱 Messaging

• Send direct messages (text, media)
• Get conversation history
• Mark messages as seen
• Delete messages
• Message encryption support
• Rate limiting and queue system

👥 Groups

• Create group chats
• Send group messages
• Add/remove participants
• Update group names
• Mute/unmute groups
• Leave groups

📸 Stories

• View stories
• Create stories
• React to stories
• Reply to stories
• Share stories
• Get story highlights
• Delete stories

👍 Reactions

• React to posts (like, love, haha, wow, sad, angry, care)
• React to stories and reels
• React to comments
• Remove reactions
• Get reaction lists
• Bulk reactions

🔐 Encryption

• AES-256-GCM encryption
• RSA asymmetric encryption
• ECDH key exchange
• Hybrid encryption
• HMAC integrity checks
• Password-based key derivation
• Signal protocol support

🌐 Browser Emulation

• Realistic browser headers
• Cookie management
• Session handling
• CSRF token management
• Rate limiting
• Error handling
• Retry mechanisms

📦 Installation

npm install instagram-api-client

🔧 Requirements

• Node.js >= 16.0.0
• npm or yarn

🎯 Quick Start

Basic Setup

const InstagramClient = require('instagram-api-client');

const client = new InstagramClient({
    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
    timeout: 30000,
    enableEncryption: true
});

Authentication

// Authenticate with username and password
const sessionData = await client.authenticate('username', 'password', '[e-mail]');
console.log('Logged in as:', sessionData.username);

Send Messages

// Send a direct message
await client.sendDirectMessage('recipient_id', 'Hello!', { encrypt: true });

// Send a media message
await client.sendMediaMessage('recipient_id', 'https://example.com/image.jpg', 'Check this out!');

Create Groups

// Create a group chat
const group = await client.createGroup(['user1_id', 'user2_id'], 'My Group');

// Send a group message
await client.sendGroupMessage(group.id, 'Hello everyone!');

React to Content

// React to a post
await client.sendPostReaction('post_id', 'love');

// React to a story
await client.sendStoryReaction('story_id', 'like');

📖 Detailed Usage

Event Handling

// Listen for events
client.on('authenticated', (sessionData) => {
    console.log('Logged in as:', sessionData.username);
});

client.on('message-received', (message) => {
    console.log('New message:', message.text);
});

client.on('story-created', (story) => {
    console.log('Story created:', story.id);
});

client.on('group-created', (group) => {
    console.log('Group created:', group.name);
});

Messaging Features

// Get conversations
const conversations = await client.getConversations(20);

// Get messages from a specific conversation
const messages = await client.getDirectMessages(50, 'thread_id');

// Mark message as seen
await client.markAsSeen('thread_id', 'item_id');

// Delete a message
await client.deleteMessage('thread_id', 'item_id');

// Queue messages for rate limiting
await client.queueMessage('recipient_id', 'Queued message');

Group Management

// Get all groups
const groups = await client.getGroups(20);

// Add participants to group
await client.addParticipants('group_id', ['user1_id', 'user2_id']);

// Remove participants from group
await client.removeParticipants('group_id', ['user1_id']);

// Update group name
await client.updateGroupName('group_id', 'New Group Name');

// Mute group
await client.muteGroup('group_id', true);

// Leave group
await client.leaveGroup('group_id');

Stories and Reels

// Get stories
const stories = await client.getStories();

// Get reels
const reels = await client.getReels();

// View a story
await client.viewStory('story_id', 'user_id');

// Create a story
const story = await client.createStory('https://example.com/image.jpg', 'My story caption');

// Reply to a story
await client.replyToStory('story_id', 'Great story!');

// Share a story
await client.shareStory('story_id', ['user1_id', 'user2_id']);

// Get story highlights
const highlights = await client.getStoryHighlights('user_id');

// Add story to highlights
await client.addToHighlights('story_id', 'highlight_id');

Reactions

// React to different content types
await client.reactToPost('post_id', 'love');
await client.reactToStory('story_id', 'like');
await client.reactToReel('reel_id', 'haha');
await client.reactToComment('comment_id', 'wow');

// Remove reactions
await client.removeReaction('post_id');
await client.removeStoryReaction('story_id');
await client.removeCommentReaction('comment_id');

// Get reaction lists
const postReactions = await client.getPostReactions('post_id');
const storyReactions = await client.getStoryReactions('story_id');
const commentReactions = await client.getCommentReactions('comment_id');

// Bulk reactions
const postIds = ['post1', 'post2', 'post3'];
await client.bulkReactToPosts(postIds, 'like');

const storyIds = ['story1', 'story2', 'story3'];
await client.bulkReactToStories(storyIds, 'love');

User Management

// Search for users
const users = await client.searchUsers('username', 20);

// Get user information
const userInfo = await client.getUserInfo('user_id');

Encryption

const { InstagramEncryption } = require('instagram-api-client');
const encryption = new InstagramEncryption();

// Generate RSA key pair
const keys = encryption.generateRSAKeyPair(2048);

// Hybrid encryption (AES + RSA)
const encrypted = encryption.hybridEncrypt('secret message', keys.publicKey);
const decrypted = encryption.hybridDecrypt(encrypted, keys.privateKey);

// Generate ECDH key pair
const ecdhKeys = encryption.generateECDHKeyPair('secp256k1');

// Derive shared secret
const sharedSecret = encryption.deriveSharedSecret(
    ecdhKeys.privateKey, 
    'other_public_key', 
    'secp256k1'
);

// Encrypt with integrity check
const encryptedWithIntegrity = encryption.encryptWithIntegrity('message', 'key');
const decryptedWithIntegrity = encryption.decryptWithIntegrity(encryptedWithIntegrity, 'key');

⚙️ Configuration Options

const client = new InstagramClient({
    // Browser emulation
    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
    
    // Network settings
    timeout: 30000,
    retryAttempts: 3,
    proxy: 'http://proxy.example.com:8080',
    
    // Security
    enableEncryption: true,
    
    // Rate limiting
    rateLimitDelay: 1000,
    maxConcurrentRequests: 5
});

🔒 Security Features

• AES-256-GCM Encryption: Military-grade symmetric encryption
• RSA Asymmetric Encryption: Secure key exchange
• ECDH Key Exchange: Perfect forward secrecy
• HMAC Integrity: Tamper detection
• PBKDF2 Key Derivation: Secure password handling
• Signal Protocol Support: End-to-end encryption

🌐 Browser Emulation

The library emulates a real browser with:

• Realistic User-Agent strings
• Proper HTTP headers
• Cookie management
• Session persistence
• CSRF token handling
• Rate limiting
• Error recovery

📊 Error Handling

client.on('error', (error) => {
    console.error('Client error:', error);
});

client.on('auth-error', (error) => {
    console.error('Authentication error:', error);
});

client.on('message-error', (error) => {
    console.error('Message error:', error);
});

// Handle specific errors
try {
    await client.sendDirectMessage('invalid_id', 'Hello');
} catch (error) {
    if (error.message.includes('not found')) {
        console.log('User not found');
    } else if (error.message.includes('rate limit')) {
        console.log('Rate limited, waiting...');
    }
}

🧪 Testing

Run the test suite:

npm test

Or run the demo:

node test/test.js

📁 Project Structure

instagram-api-client/
├── src/
│   ├── client/
│   │   └── InstagramClient.js      # Main client class
│   ├── auth/
│   │   └── InstagramAuth.js        # Authentication system
│   ├── messaging/
│   │   └── InstagramMessaging.js   # Direct messaging
│   ├── groups/
│   │   └── InstagramGroups.js      # Group management
│   ├── stories/
│   │   └── InstagramStories.js     # Stories and reels
│   ├── reactions/
│   │   └── InstagramReactions.js   # Reactions system
│   ├── encryption/
│   │   └── InstagramEncryption.js  # Encryption utilities
│   └── utils/
│       └── BrowserEmulator.js      # Browser emulation
├── test/
│   └── test.js                     # Test suite
├── package.json
└── README.md

🤝 Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests
• Submit a pull request

📄 License

MIT License - see LICENSE file for details

⚠️ Disclaimer

This library is for educational and legitimate use only. Please respect Instagram's Terms of Service and use responsibly. The authors are not responsible for any misuse of this library.

🆘 Support

• Create an issue on GitHub
• Check the documentation
• Review the test examples

🔄 Updates

Stay updated with the latest features and security patches by regularly updating the library:

npm update instagram-api-client

Made with ❤️ for the Instagram developer community