Unipile Instagram Sdk

Access Instagram messaging, profiles, posts, and interactions via Unipile's official Node.js SDK for automation and content management.

Instagram API via official unipile-node-sdk for messaging, profiles, posts, and interactions.

📸 Send DMs, view profiles, list posts, and interact with Instagram content — all through natural conversation with OpenClaw.

---

⚠️ Security & Privacy

This skill requires credentials that grant API-level access to your connected Instagram accounts through Unipile.

What You're Granting

Credential	Access Level	Risk
UNIPILE_DSN	Unipile API endpoint	Identifies your Unipile instance
UNIPILE_ACCESS_TOKEN	Full API access to Unipile	Can read/write all connected social accounts

What This Means

• Unipile gets your data — Your Instagram messages, posts, and profile data flow through Unipile's servers
• API-level control — Anyone with these credentials can send DMs, create posts, and interact as you
• Connected accounts — If you connect Instagram via Unipile's dashboard, your Instagram session is stored on their servers

Higher-Risk: Connecting Instagram Accounts

To connect a new Instagram account, you may need to provide:

• Instagram username and password
• 2FA verification codes

This gives Unipile direct access to your Instagram account. Only do this if you trust Unipile with your social media credentials.

Recommendations

1. Use a dedicated Instagram account — Don't use your personal main account for automation
2. Review Unipile's security — Read their privacy policy and terms of service
3. Audit the SDK — The unipile-node-sdk is open source and auditable
4. Use least privilege — Set UNIPILE_PERMISSIONS=read unless you need write access
5. Rotate tokens — Regularly regenerate your access token from the Unipile dashboard
6. Monitor activity — Check your Unipile dashboard for unexpected API usage

If You're Unsure

Don't install this skill. This is intended for users who:

• Already use Unipile for social media automation
• Understand the risks of third-party API access
• Have reviewed Unipile's security practices

---

Installation

bash

npx clawhub install unipile-instagram-sdk

Then install dependencies:

bash

cd ~/.openclaw/workspace/skills/unipile-instagram-sdk
npm install

---

Setup

Environment Variables

Variable	Required	Description
UNIPILE_DSN	✅	API endpoint (e.g., https://api34.unipile.com:16473)
UNIPILE_ACCESS_TOKEN	✅	Token from dashboard.unipile.com
UNIPILE_PERMISSIONS	Optional	read, write, or read,write (default: read,write)

Get Credentials

1. Sign up at dashboard.unipile.com
2. Get your DSN and generate an access token
3. Connect an Instagram account via dashboard or API

Or just ask OpenClaw:

"Set up my Unipile Instagram credentials"

---

Quick Reference

What you want	What to say
See accounts	"Show my Instagram accounts"
Get a profile	"Get Instagram profile for @username"
View posts	"Show Instagram posts from @username"
Read DMs	"Show my Instagram messages with [name]"
Send DM	"Send '[message]' to [name] on Instagram"
Create post	"Post '[text]' to my Instagram"
Like/Comment	"Like that post" / "Comment '[text]' on that post"

---

💬 How to Use

Once configured, just talk to OpenClaw naturally:

Account & Profiles

"Show me my connected Instagram accounts"

"Get the Instagram profile for @nasa"

"What's my own Instagram profile info?"

"Who am I following on Instagram?"

Posts & Content

"Show me the last 5 posts from @nasa on Instagram"

"Get details for Instagram post ID 123456"

"Create an Instagram post saying 'Hello from OpenClaw!'"

"Like that last post from @nasa"

"Comment 'Amazing shot! 🔥' on the post"

Direct Messages

"List my recent Instagram DM chats"

"Show me my last 20 messages with Yashpreet"

"Send 'Hey, how are you?' to Yashpreet on Instagram"

"Start a new Instagram conversation with @username saying 'Hi there!'"

"Send this photo to Yashpreet on Instagram" (with image attached)

---

🛡️ Permission Modes

By default, the skill operates in read-only mode for safety.

Read-only (UNIPILE_PERMISSIONS=read):

• View profiles, posts, chats, messages
• No sending, posting, or interactions

Read + Write (UNIPILE_PERMISSIONS=read,write):

• Send messages
• Create posts
• React and comment

Just tell OpenClaw:

"Set my Unipile permissions to read-only"

Or when you need write access:

"Enable write permissions for Unipile so I can send messages"

---

CLI Tool

For direct operations, use the included CLI:

bash

# Set environment
export UNIPILE_DSN="https://api33.unipile.com:16376"
export UNIPILE_ACCESS_TOKEN="your_token"

# Read operations
node scripts/instagram.mjs accounts
node scripts/instagram.mjs my-profile <account_id>
node scripts/instagram.mjs profile <account_id> <username>
node scripts/instagram.mjs posts <account_id> <username> --limit=5
node scripts/instagram.mjs chats --account_id=<id>
node scripts/instagram.mjs messages <chat_id> --limit=10

# Write operations (require UNIPILE_PERMISSIONS=write)
node scripts/instagram.mjs send <chat_id> "Hello"
node scripts/instagram.mjs start-chat <account_id> "Hi" --to=<provider_id>
node scripts/instagram.mjs create-post <account_id> "Post text"
node scripts/instagram.mjs comment <account_id> <post_id> "Nice!"
node scripts/instagram.mjs react <account_id> <post_id> --type=like

---

API Reference

Client Initialization

javascript

import { UnipileClient } from 'unipile-node-sdk';

const client = new UnipileClient(
  process.env.UNIPILE_DSN,
  process.env.UNIPILE_ACCESS_TOKEN
);

Account Connection

javascript

// Connect Instagram account
await client.account.connectInstagram({
  username: 'your_username',
  password: 'your_password',
});

// Hosted Auth (multi-user apps)
const link = await client.account.createHostedAuthLink({
  type: 'create',
  providers: ['INSTAGRAM'],
  success_redirect_url: 'https://yourapp.com/success',
});

// Handle 2FA
await client.account.solveCodeCheckpoint({
  account_id: accountId,
  provider: 'INSTAGRAM',
  code: '123456'
});

Get Account ID

All operations require an account ID:

javascript

const accounts = await client.account.getAll();
const instagram = accounts.items.find(a => a.type === 'INSTAGRAM');
const accountId = instagram.id;

Read Operations

Task	Method
List accounts	client.account.getAll()
Get profile	client.users.getProfile({ account_id, identifier })
Get own profile	client.users.getOwnProfile(account_id)
Get followers	client.users.getAllRelations({ account_id })
List posts	client.users.getAllPosts({ account_id, identifier })
Get post	client.users.getPost({ account_id, post_id })
List chats	client.messaging.getAllChats({ account_type: 'INSTAGRAM', account_id })
Get messages	client.messaging.getAllMessagesFromChat({ chat_id })

Write Operations

Task	Method
Create post	client.users.createPost({ account_id, text })
React	client.users.sendPostReaction({ account_id, post_id, reaction_type })
Comment	client.users.sendPostComment({ account_id, post_id, text })
Send DM	client.messaging.sendMessage({ chat_id, text })
Start chat	client.messaging.startNewChat({ account_id, attendees_ids, text })

Attachments

javascript

import { readFile } from 'fs/promises';

const fileBuffer = await readFile('./photo.jpg');
await client.messaging.sendMessage({
  chat_id: 'chat_id',
  text: 'Check this out!',
  attachments: [['photo.jpg', fileBuffer]],
});

---

Error Handling

javascript

import { UnsuccessfulRequestError } from 'unipile-node-sdk';

try {
  await client.users.getProfile({ account_id, identifier });
} catch (err) {
  if (err instanceof UnsuccessfulRequestError) {
    const { status, type } = err.body;
    // type: 'errors/invalid_credentials', 'errors/checkpoint_error', etc.
  }
}

Common Errors

Type	Meaning	Action
errors/invalid_credentials	Wrong password	Reconnect account
errors/checkpoint_error	2FA required	Call solveCodeCheckpoint
errors/disconnected_account	Session expired	Reconnect
errors/resource_not_found	Invalid ID	Verify exists

---

Resources

• Unipile SDK Repository
• Unipile Documentation
• Unipile Dashboard
• Unipile Privacy Policy
• ClawHub Skill Page