Skip to content

Latest commit

 

History

History
648 lines (503 loc) · 13.5 KB

API_REFERENCE.md

File metadata and controls

648 lines (503 loc) · 13.5 KB

Instagram API Reference

Complete API reference for n8n-nodes-instagram-integrations operations.

Table of Contents

Instagram Node

The main Instagram node provides messaging and user management capabilities.

Message Operations

Send Text Message

Send a plain text message to an Instagram user.

Parameters:

Parameter Type Required Description
Recipient ID string Yes Instagram-scoped user ID (IGSID)
Message Text string Yes Text content (max 1000 characters)

Example:

{
  "recipientId": "1234567890",
  "messageText": "Hello! Thanks for reaching out."
}

API Endpoint: POST /me/messages

Request Body:

{
  "recipient": { "id": "1234567890" },
  "message": { "text": "Hello! Thanks for reaching out." }
}

Response:

{
  "recipient_id": "1234567890",
  "message_id": "mid.abc123def456"
}

Send Image Message

Send an image via public HTTPS URL.

Parameters:

Parameter Type Required Description
Recipient ID string Yes Instagram-scoped user ID
Image URL string Yes Public HTTPS URL of image (JPG, PNG)
Is Reusable boolean No Make attachment reusable (default: false)

Example:

{
  "recipientId": "1234567890",
  "imageUrl": "https://example.com/image.jpg",
  "isReusable": true
}

API Endpoint: POST /me/messages

Request Body:

{
  "recipient": { "id": "1234567890" },
  "message": {
    "attachment": {
      "type": "image",
      "payload": {
        "url": "https://example.com/image.jpg",
        "is_reusable": true
      }
    }
  }
}

Constraints:

  • Must be HTTPS
  • Max file size: 8MB
  • Supported formats: JPG, PNG, GIF
  • Dimensions: Up to 8192x8192 pixels

Send Audio Message

Send an audio file via public HTTPS URL.

Parameters:

Parameter Type Required Description
Recipient ID string Yes Instagram-scoped user ID
Audio URL string Yes Public HTTPS URL of audio file
Is Reusable boolean No Make attachment reusable (default: false)

Example:

{
  "recipientId": "1234567890",
  "audioUrl": "https://example.com/audio.mp3",
  "isReusable": false
}

API Endpoint: POST /me/messages

Constraints:

  • Must be HTTPS
  • Max file size: 25MB
  • Supported formats: MP3, WAV, M4A

Send Video Message

Send a video file via public HTTPS URL.

Parameters:

Parameter Type Required Description
Recipient ID string Yes Instagram-scoped user ID
Video URL string Yes Public HTTPS URL of video file
Is Reusable boolean No Make attachment reusable (default: false)

Example:

{
  "recipientId": "1234567890",
  "videoUrl": "https://example.com/video.mp4",
  "isReusable": false
}

API Endpoint: POST /me/messages

Constraints:

  • Must be HTTPS
  • Max file size: 25MB
  • Supported formats: MP4, MOV
  • Max duration: 60 seconds
  • Aspect ratio: 16:9 or 9:16 recommended

Send Button Template

Send an interactive button template message.

Parameters:

Parameter Type Required Description
Recipient ID string Yes Instagram-scoped user ID
Message Text string Yes Text to display (max 640 characters)
Buttons array Yes Array of buttons (max 3)

Button Types:

Web URL Button:

{
  "type": "web_url",
  "title": "Visit Website",
  "url": "https://example.com"
}

Postback Button:

{
  "type": "postback",
  "title": "Get Started",
  "payload": "GET_STARTED_PAYLOAD"
}

Complete Example:

{
  "recipientId": "1234567890",
  "messageText": "How can we help you today?",
  "buttons": [
    {
      "type": "web_url",
      "title": "Visit Shop",
      "url": "https://shop.example.com"
    },
    {
      "type": "postback",
      "title": "Contact Support",
      "payload": "CONTACT_SUPPORT"
    },
    {
      "type": "postback",
      "title": "Track Order",
      "payload": "TRACK_ORDER"
    }
  ]
}

API Endpoint: POST /me/messages

Constraints:

  • Max 3 buttons per template
  • Button title: Max 20 characters
  • Postback payload: Max 1000 characters
  • URLs must be HTTPS

Send Generic Template

Send a carousel of cards with images and buttons.

Parameters:

Parameter Type Required Description
Recipient ID string Yes Instagram-scoped user ID
Elements array Yes Array of template elements (max 10)

Element Structure:

{
  "title": "Product Name",
  "subtitle": "Product description",
  "image_url": "https://example.com/product.jpg",
  "default_action": {
    "type": "web_url",
    "url": "https://example.com/product"
  },
  "buttons": [
    {
      "type": "web_url",
      "title": "Buy Now",
      "url": "https://example.com/buy"
    },
    {
      "type": "postback",
      "title": "Add to Cart",
      "payload": "ADD_TO_CART_123"
    }
  ]
}

Complete Example:

{
  "recipientId": "1234567890",
  "elements": [
    {
      "title": "Summer Collection",
      "subtitle": "New arrivals for summer 2025",
      "image_url": "https://example.com/summer.jpg",
      "buttons": [
        {
          "type": "web_url",
          "title": "Shop Now",
          "url": "https://shop.example.com/summer"
        }
      ]
    },
    {
      "title": "Winter Sale",
      "subtitle": "Up to 50% off",
      "image_url": "https://example.com/winter.jpg",
      "buttons": [
        {
          "type": "web_url",
          "title": "View Deals",
          "url": "https://shop.example.com/winter"
        }
      ]
    }
  ]
}

Constraints:

  • Max 10 elements (cards)
  • Title: Max 80 characters
  • Subtitle: Max 80 characters
  • Max 3 buttons per element
  • Image aspect ratio: 1.91:1 recommended
  • Image size: Min 600x315 pixels

Send Quick Replies

Send a message with quick reply options.

Parameters:

Parameter Type Required Description
Recipient ID string Yes Instagram-scoped user ID
Message Text string Yes Text message content
Quick Replies array Yes Array of quick reply options (max 13)

Quick Reply Structure:

{
  "content_type": "text",
  "title": "Option 1",
  "payload": "OPTION_1_PAYLOAD",
  "image_url": "https://example.com/icon.png"
}

Complete Example:

{
  "recipientId": "1234567890",
  "messageText": "What's your favorite color?",
  "quickReplies": [
    {
      "content_type": "text",
      "title": "Red",
      "payload": "COLOR_RED"
    },
    {
      "content_type": "text",
      "title": "Blue",
      "payload": "COLOR_BLUE"
    },
    {
      "content_type": "text",
      "title": "Green",
      "payload": "COLOR_GREEN"
    }
  ]
}

Constraints:

  • Max 13 quick replies
  • Title: Max 20 characters
  • Payload: Max 1000 characters
  • Image URL optional

Upload Media

Upload media for publishing to Instagram feed, reels, or stories.

Parameters:

Parameter Type Required Description
Media Type options Yes Type: image, video, reels, stories
Media URL string Yes Public HTTPS URL of media file
Caption string No Caption for the media post

Example:

{
  "mediaType": "image",
  "mediaUrl": "https://example.com/photo.jpg",
  "caption": "Check out our new product! #Launch"
}

API Endpoint: POST /{ig-user-id}/media (container creation)
Publish Endpoint: POST /{ig-user-id}/media_publish

Process:

  1. Create media container
  2. Wait for processing
  3. Publish container

Constraints:

  • Images: JPG/PNG, max 8MB, min 320px
  • Videos: MP4/MOV, max 100MB, 3-60 seconds
  • Reels: 9:16 aspect ratio, max 90 seconds
  • Stories: 9:16 aspect ratio, 24-hour duration

User Operations

Get User Profile

Retrieve Instagram user profile information.

Parameters:

Parameter Type Required Description
User ID string Yes Instagram-scoped user ID (IGSID)
Fields multi-options No Fields to retrieve (default: all)

Available Fields:

  • id - User's Instagram-scoped ID
  • name - User's full name
  • username - Instagram username
  • profile_pic - Profile picture URL

Example:

{
  "userId": "1234567890",
  "fields": ["id", "name", "username", "profile_pic"]
}

API Endpoint: GET /{ig-user-id}?fields=...

Response:

{
  "id": "1234567890",
  "name": "John Doe",
  "username": "johndoe",
  "profile_pic": "https://scontent.cdninstagram.com/..."
}

Instagram Trigger Node

Webhook-based trigger for Instagram events.

Webhook Events

Messages

Triggered when a user sends a message to your Instagram Business Account.

Event Data:

{
  "eventType": "message",
  "senderId": "1234567890",
  "recipientId": "0987654321",
  "timestamp": 1696435200000,
  "messageId": "mid.abc123",
  "text": "Hello!",
  "attachments": []
}

Attachment Structure:

{
  "type": "image",
  "payload": {
    "url": "https://scontent.cdninstagram.com/..."
  }
}

Quick Reply Response:

{
  "eventType": "message",
  "senderId": "1234567890",
  "text": "Red",
  "quick_reply": {
    "payload": "COLOR_RED"
  }
}

Postbacks

Triggered when a user clicks a button in a template.

Event Data:

{
  "eventType": "postback",
  "senderId": "1234567890",
  "recipientId": "0987654321",
  "timestamp": 1696435200000,
  "payload": "GET_STARTED",
  "title": "Get Started"
}

Opt-ins

Triggered when a user grants permissions or subscribes.

Event Data:

{
  "eventType": "optin",
  "senderId": "1234567890",
  "recipientId": "0987654321",
  "timestamp": 1696435200000,
  "ref": "NEWSLETTER_SIGNUP"
}

Error Codes

Instagram API Errors

Code Type Description Solution
190 OAuthException Invalid access token Re-authenticate or refresh token
200 PermissionsError Permission denied Request required permissions
551 APIException User cannot receive messages Wait for user to initiate conversation
613 APIException Rate limit exceeded Implement exponential backoff
10 OAuthException Permission not granted Check app permissions in Meta console
100 InvalidParameter Invalid parameter Verify request payload
2 APIException Service temporarily unavailable Retry after delay

n8n Node Errors

Error Description Solution
Missing Credential No credential selected Select credential in node settings
Invalid Recipient ID Recipient ID format invalid Use Instagram-scoped ID (IGSID)
URL Not HTTPS Media URL not secure Use HTTPS URLs only
Webhook Verification Failed Verify token mismatch Check token in credential matches Meta app

Rate Limits

API Rate Limits

Endpoint Limit Window
Messaging API 200 calls Per hour per user
Media Upload 50 calls Per hour per user
User Profile 200 calls Per hour per app

Webhook Limits

  • Events: Unlimited receives
  • Response Time: Must respond within 20 seconds
  • Batch Size: Up to 1000 events per batch
  • Retry: 3 attempts with exponential backoff

Best Practices

  1. Implement Retry Logic: Use exponential backoff for failed requests
  2. Cache Data: Store user profiles to reduce API calls
  3. Batch Operations: Group operations when possible
  4. Monitor Usage: Track API call consumption
  5. Handle Errors: Gracefully handle rate limit responses

Rate Limit Headers

X-Business-Use-Case-Usage: {"business_id":{"call_count":15,"total_cputime":25,"total_time":25}}
X-App-Usage: {"call_count":15,"total_cputime":25,"total_time":25}

Response When Exceeded:

{
  "error": {
    "message": "Application request limit reached",
    "type": "OAuthException",
    "code": 4,
    "fbtrace_id": "..."
  }
}

Recommended Retry Delay:

  • 1st retry: 1 second
  • 2nd retry: 2 seconds
  • 3rd retry: 4 seconds
  • 4th retry: 8 seconds
  • Max retries: 5

Additional Resources

Instagram Graph API

Testing Tools

Support

Last Updated: October 4, 2025
API Version: Instagram Graph API v23.0
Package Version: 1.2.11