@innovatespace/ig-business

A TypeScript library for Instagram Business API integration, providing OAuth authentication and content publishing capabilities.

Features

• 🔐 OAuth Authentication - Complete Instagram OAuth flow implementation
• 📸 Content Publishing - Publish images, videos, and carousel posts
• 👤 Account Information - Retrieve Instagram Business account details and metrics
• 🎯 TypeScript Support - Fully typed for better development experience
• 🚀 Modern ESM - Built with ES modules for optimal tree-shaking
• ⚡ Zero Dependencies - Lightweight with no external dependencies

Installation

npm install @innovatespace/ig-business

yarn add @innovatespace/ig-business

pnpm add @innovatespace/ig-business

Quick Start

OAuth Authentication

import { OAuthInstagram } from '@innovatespace/ig-business';

const oauth = new OAuthInstagram('your-client-id', 'your-client-secret');

// Step 1: Generate OAuth redirect URL
const redirectUrl = OAuthInstagram.getRedirectUri({
  scope: ['instagram_business_basic', 'instagram_business_content_publish'],
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  state: 'optional-state-parameter',
});

// Step 2: Exchange authorization code for short-lived token
const shortLivedToken = await oauth.getShortLivedInstagramAccessToken(
  'https://your-app.com/callback',
  'authorization-code-from-callback'
);

// Step 3: Convert to long-lived token (60 days)
const longLivedToken = await oauth.getLongLivedInstagramAccessToken(
  shortLivedToken.access_token
);

// Step 4: Refresh token when needed
const refreshedToken = await oauth.refreshInstagramAccessToken(
  longLivedToken.access_token
);

Content Publishing

import { InstagramPublish } from '@innovatespace/ig-business';

const publisher = new InstagramPublish(
  'your-access-token',
  'instagram-business-account-id'
);

// Publish a single image
const imageContainer = await publisher.createContainer({
  image_url: 'https://example.com/image.jpg',
});

const publishedImage = await publisher.publishContainer(imageContainer.id);

// Publish a video
const videoContainer = await publisher.createContainer({
  video_url: 'https://example.com/video.mp4',
  media_type: 'VIDEO',
});

const publishedVideo = await publisher.publishContainer(videoContainer.id);

// Publish a carousel post
const carouselItems = [
  await publisher.createContainer({
    image_url: 'https://example.com/image1.jpg',
    is_carousel_item: true,
  }),
  await publisher.createContainer({
    image_url: 'https://example.com/image2.jpg',
    is_carousel_item: true,
  }),
];

const carouselContainer = await publisher.createCarouselContainer({
  children: carouselItems.map((item) => item.id),
  media_type: 'CAROUSEL',
});

const publishedCarousel = await publisher.publishContainer(
  carouselContainer.id
);

Account Information

import { InstagramAccount } from '@innovatespace/ig-business';

const account = new InstagramAccount('your-access-token');

// Get user account data with specific fields
const userData = await account.getUserData([
  'id',
  'username',
  'account_type',
  'media_count',
  'followers_count',
  'follows_count',
  'profile_picture_url',
  'biography',
]);

// Or get specific field as a string
const username = await account.getUserData('username');

console.log('Account info:', userData);

API Reference

OAuthInstagram

Handles Instagram OAuth authentication flow.

Constructor

new OAuthInstagram(clientId: string, clientSecret: string)

Methods

getRedirectUri(params: RedirectParam): string

Generates the OAuth authorization URL.

Parameters:

• scope: Array of Instagram Business API scopes
• clientId: Your Instagram app client ID
• redirectUri: Your app's callback URL
• force_reauth?: Force re-authentication (optional)
• state?: Custom state parameter (optional)

Available Scopes:

• instagram_business_basic
• instagram_business_manage_messages
• instagram_business_manage_comments
• instagram_business_content_publish

getShortLivedInstagramAccessToken(redirectUri: string, code: string): Promise<CodeExchangeResponse>

Exchanges authorization code for a short-lived access token.

getLongLivedInstagramAccessToken(shortLivedToken: string): Promise<TokenExchangeResponse>

Converts short-lived token to long-lived token (60 days).

refreshInstagramAccessToken(longLivedToken: string): Promise<TokenExchangeResponse>

Refreshes an expired long-lived access token.

InstagramAccount

Handles Instagram Business account information retrieval.

InstagramAccount Constructor

new InstagramAccount(accessToken: string, version?: string)

Parameters:

• accessToken: Instagram access token
• version: API version (default: 'v23.0')

Account Methods

getUserData<T>(fields: string[] | string): Promise<T>

Retrieves Instagram Business account information.

Parameters:

• fields: Field(s) to retrieve. Can be a string or array of strings.

Available Fields:

• id - Instagram Business Account ID
• user_id - Instagram User ID
• username - Instagram username
• account_type - Account type (BUSINESS, CREATOR, etc.)
• media_count - Number of media objects
• followers_count - Number of followers
• follows_count - Number of accounts followed
• profile_picture_url - Profile picture URL
• biography - Account biography
• website - Website URL
• name - Display name

Example:

// Get multiple fields
const accountInfo = await account.getUserData([
  'id',
  'username',
  'followers_count',
  'media_count',
]);

// Get single field
const username = await account.getUserData('username');

InstagramPublish

Handles Instagram content publishing.

InstagramPublish Constructor

new InstagramPublish(accessToken: string, accountId: string, version?: string)

Parameters:

• accessToken: Instagram access token
• accountId: Instagram Business account ID
• version: API version (default: 'v23.0')

Publishing Methods

createContainer(params: CreateContainerParam): Promise<CreateContainerResponse>

Creates a media container for publishing.

Parameters:

• image_url?: URL of the image to publish
• video_url?: URL of the video to publish
• media_type?: Media type ('VIDEO', 'REELS', 'STORIES')
• is_carousel_item?: Whether this is part of a carousel
• upload_type?: Upload type ('resumable' for large files)

createCarouselContainer(params: CreateCarouselContainerParam): Promise<CreateContainerResponse>

Creates a carousel container.

Parameters:

• children: Array of container IDs or single container ID
• media_type?: Should be 'CAROUSEL'

publishContainer(containerId: string): Promise<PublishContainerResponse>

Publishes a created container to Instagram.

Error Handling

try {
  const container = await publisher.createContainer({
    image_url: 'https://example.com/image.jpg',
  });

  const result = await publisher.publishContainer(container.id);
  console.log('Published successfully:', result.id);
} catch (error) {
  console.error('Publishing failed:', error.message);
}

Requirements

• Node.js 14 or higher
• Instagram Business Account
• Facebook App with Instagram Basic Display and Instagram API permissions
• Valid Instagram Business API access token

Getting Instagram API Credentials

1. Create a Facebook App at Facebook Developers
2. Add Instagram Basic Display and Instagram API products to your app
3. Connect your Instagram Business Account to the Facebook App
4. Configure OAuth redirect URIs in your app settings
5. Get your Client ID and Client Secret from the app dashboard
6. Users authenticate using their Instagram Business account credentials
7. Follow the OAuth flow to exchange authorization codes for access tokens

Note: While you create the app through Facebook Developers (since Instagram is owned by Meta), users will log in with their Instagram Business account credentials during the OAuth flow.

For detailed setup instructions, visit the Instagram Basic Display API documentation.

TypeScript Support

This library is written in TypeScript and includes full type definitions. All API responses and parameters are properly typed for better development experience.

import type {
  CreateContainerParam,
  CreateContainerResponse,
  TokenExchangeResponse,
  InstagramAccount,
} from '@innovatespace/ig-business';

License

MIT

Contributing

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

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.