Unipile Instagram SDK#

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#

CredentialAccess LevelRiskUNIPILE_DSNUnipile API endpointIdentifies your Unipile instanceUNIPILE_ACCESS_TOKENFull API access to UnipileCan 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#

VariableRequiredDescriptionUNIPILE_DSN✅API endpoint (e.g., https://api34.unipile.com:16473)UNIPILE_ACCESS_TOKEN✅Token from dashboard.unipile.comUNIPILE_PERMISSIONSOptionalread, 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 wantWhat to saySee 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#

TaskMethodList accountsclient.account.getAll()Get profileclient.users.getProfile({ account_id, identifier })Get own profileclient.users.getOwnProfile(account_id)Get followersclient.users.getAllRelations({ account_id })List postsclient.users.getAllPosts({ account_id, identifier })Get postclient.users.getPost({ account_id, post_id })List chatsclient.messaging.getAllChats({ account_type: 'INSTAGRAM', account_id })Get messagesclient.messaging.getAllMessagesFromChat({ chat_id })

Write Operations#

TaskMethodCreate postclient.users.createPost({ account_id, text })Reactclient.users.sendPostReaction({ account_id, post_id, reaction_type })Commentclient.users.sendPostComment({ account_id, post_id, text })Send DMclient.messaging.sendMessage({ chat_id, text })Start chatclient.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#

TypeMeaningActionerrors/invalid_credentialsWrong passwordReconnect accounterrors/checkpoint_error2FA requiredCall solveCodeCheckpoint``errors/disconnected_accountSession expiredReconnecterrors/resource_not_foundInvalid IDVerify exists

---

Resources#

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