instagram-private-api

The sticker-builder module provides a suite of classes to construct various types of Instagram story stickers. You can use the StickerBuilder class along with specific sticker classes to build complex sticker configurations for stories.

Available sticker classes include:

• AttachmentSticker
• ChatSticker
• CountdownSticker
• HashtagSticker
• InstaSticker
• LocationSticker
• MentionSticker
• PollSticker
• QuestionSticker
• QuizSticker
• SliderSticker

The library is organized into three main architectural layers:

Repositories

Repositories implement low-level atomic operations. Every method in a repository sends exactly one API request. You access them on the IgApiClient instance using their lower-case (camelCase) name without the Repository suffix. Example: ig.addressBook accesses the AddressBookRepository.

Feeds

Feeds represent paginated endpoints (e.g., a user's feed). They act as async-iterators/streams and are accessible via ig.feed.feedName() (camelCase). Most feeds require initialization parameters like a user PK.

Services

Services provide high-level abstractions to perform complex actions that involve multiple repository calls, such as simulating pre/post-login flows or publishing photos/videos.

The ChallengeRepository is used to handle security challenges (like unusual login attempts or two-factor authentication) encountered during API operations.

Important: All methods in this repository require State.checkpoint to be populated with a CheckpointResponse. This checkpoint is automatically filled when an IgCheckpointError occurs during an API call.

For segmented video uploads, use the following sequence of methods:

1. startSegmentedVideo(ruploadParams): Initiates the segmented upload process.
2. videoSegmentInit(options): Initializes a specific video segment using UploadVideoSegmentInitOptions.
3. videoSegmentTransfer(options): Transfers the segment data using UploadVideoSegmentTransferOptions.
4. endSegmentedVideo(__namedParameters): Finalizes the segmented video upload.

The repositories layer in this library is designed for low-level, atomic operations. Each method in a repository must perform at most one API request.

To perform complex actions that require multiple steps (e.g., publishing a post), you should not attempt to combine multiple requests into a single repository method. Instead, follow this pattern:

1. Implement Repository Methods: Create individual methods for each atomic API request (e.g., upload.photo and media.configure).
2. Implement a Service: Create a method in a service layer (e.g., publish) that orchestrates the sequence of repository calls (e.g., calling upload.photo() first, then using the resulting uploadId to call media.configure()).

You can install the library via npm or directly from GitHub.

Security Note: This package uses url-regex-safe to check for links in direct messages. It is highly recommended to manually install re2 to avoid vulnerability to CVE-2020-7661.

npm install instagram-private-api
npm install re2

To view debug information provided by the library, set the DEBUG environment variable in your Node.js environment. The library uses the ig namespace. To see all debug logs, use the ig:* pattern.

Example:

DEBUG=ig:* node your-app.js

When attempting to log in, Instagram may require two-factor authentication (2FA). If this is the case, the library will throw an IgLoginTwoFactorRequiredError.

This error is a subclass of IgResponseError and contains a response property of type AccountRepositoryLoginErrorResponse. You should catch this error to initiate your 2FA verification flow (e.g., by requesting a code or using a TOTP token).

The IgUserHasLoggedOutError is thrown when an API request indicates that the user has been logged out or a login is required. This error inherits from IgResponseError and LoginRequiredResponse.

When catching this error, you can access the response property to inspect the underlying LoginRequiredResponse data provided by Instagram.

The IgRequestsLimitError is a specific error type thrown when the Instagram API rate limits your requests. It inherits from IgClientError. When building automation, you should catch this error to implement backoff strategies or pause execution to avoid further rate limiting or account flagging.

Hierarchy

• IgClientError
  • IgRequestsLimitError