Instagram Business

Conversations across every connected inbox (LinkedIn, WhatsApp, Telegram, Instagram, Instagram Business, Facebook Messenger), merged and sorted most recent first; account or provider narrows it. Use unread=true to triage. Each item has chat_id, its account_id and provider (pass account_id as account to get_messages, send_message and the other conversation tools), and person_id for 1-to-1 chats. Facebook: page_id lists the inbox of one of a personal account's Pages (facebook_list_pages); requests=true the message requests. Accounts that can't be read right now are listed in skipped, with what to do.

{
  "items": [
    {
      "chat_id": "6Wx3HyhTVvKmNy2kP9zQ1A",
      "name": "Lucas Bernard",
      "person_id": "33612345678@s.whatsapp.net",
      "group": false,
      "unread": 1,
      "last_activity": "2026-11-09T08:42:17.000Z",
      "last_message": "See you at 10 tomorrow 👍",
      "read_only": false,
      "account_id": "8d41a7f0-2c6e-4b1a-a3d9-71e5c0b4f826",
      "provider": "whatsapp"
    },
    {
      "chat_id": "gq5Xp3bZUXCt6Zt1Z2rTsA",
      "name": "Ada Martin",
      "person_id": "ACoAAA8BYqEBCVM2yBH2uI6u",
      "group": false,
      "unread": 1,
      "last_activity": "2026-11-09T08:42:17.000Z",
      "last_message": "Thanks for connecting! Do you have 15 minutes next week?",
      "read_only": false,
      "account_id": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c",
      "provider": "linkedin"
    }
  ],
  "next_cursor": "m1.eyJsIjoyMCwidSI6MCwiYSI6eyI4ZDQxYTdmMCI6eyJjIjoiMjAyNiJ9fX0",
  "has_more": true,
  "accounts_read": 2
}

Messages in one conversation (chat_id from list_chats), most recent first. 'from' is 'me' (the account owner, or the Page in a Facebook Page's chat) or 'them'; message_id values work with react. The 3 most recent images on the page come with the result for you to see (their attachments say shown_below: true); open any other, or read a document's text (PDF, Word, Excel…), with get_attachment. Every attachment has a url the user can open or download for 24 hours. Instagram Business: without cursor, reply_window says whether a reply can go out (open, user_written_only or closed). Facebook personal chats are end-to-end encrypted: older messages show only if the user unlocked their history when connecting.

{
  "chat_id": "gq5Xp3bZUXCt6Zt1Z2rTsA",
  "items": [
    {
      "message_id": "7mKQx2VdTnW8bLr4Yc9eFg",
      "from": "them",
      "text": "Thanks for connecting! Do you have 15 minutes next week?",
      "at": "2026-11-09T08:42:17.000Z"
    },
    {
      "message_id": "7mKQx2VdTnW8bLr4Yc9ex1",
      "from": "me",
      "text": "Hi! Happy to send over the deck.",
      "at": "2026-11-08T16:05:41.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Reply in an existing conversation (chat_id from list_chats), on any network: 1-to-1, group, or a Facebook Page's chat (answered as the Page). Plain text. Show the user the exact text (and which file) before calling this. One file can go with the text: image_url (an https link to an image), file_url (an https link to a document) or media_id (from upload_media, for an image or a document the user has on their device or attached in the chat). Documents: PDF, Word, Excel, PowerPoint (docx, xlsx, pptx, doc, xls, ppt), TXT or CSV, at most 15 MB; WhatsApp, Telegram, LinkedIn and Facebook Messenger take PDF, Word, Excel, PowerPoint, TXT and CSV files; Instagram takes PDFs only; Instagram Business takes PDFs only and Facebook Pages any of them. Instagram Business allow replies within 24 hours of the person's last message (Instagram: at most 1000 characters, JPEG or PNG); up to 7 days after it, only a reply the user wrote or approved word for word, with user_written: true (never for text you wrote on your own).

{
  "chat_id": "gq5Xp3bZUXCt6Zt1Z2rTsA",
  "message_id": "7mKQx2VdTnW8bLr4Yc9ey7",
  "sent": true
}

Marks a conversation read (or unread with read=false), on any network. Reading a conversation doesn't mark it read.

{
  "chat_id": "gq5Xp3bZUXCt6Zt1Z2rTsA",
  "read": true
}

Add an emoji reaction to a message (chat_id and message_id from get_messages) on WhatsApp (any emoji), Telegram (its standard reactions only: 👍 ❤️ 🔥 🎉 😁 👏 …), Instagram, Facebook Messenger or Instagram Business (within 24 hours of the person's last message; remove=true takes the account's reaction back). A new reaction replaces the account's previous one. For Facebook posts and comments use facebook_react_post.

{
  "chat_id": "6Wx3HyhTVvKmNy2kP9zQ1A",
  "message_id": "3EB0A9C4D2F1E8B7A6C5",
  "reaction": "👍",
  "reacted": true
}

Publish a post on one connected account, right away or at publish_at (then it's scheduled: returns a scheduled_post_id for list_scheduled_posts and cancel_scheduled_post). Instagram Business: text ≤2200, up to 20 images or 1 video (required). Instagram Business: one image (a feed post), several (a carousel), one video (a Reel), or with story: true a Story. Call post_options first for an account you haven't posted to in this conversation. Media: media_ids from upload_media (files the user has, or one you made), or public https links (image_urls, video_url); for a scheduled post, links must keep working until publish_at, uploads are kept with the post. Public and irreversible: confirm the account, final text, media, audience and time (with the user's time zone) with the user first.

{
  "url": "https://www.threads.net/@ada.martin/post/DQ3kF8sDk2L",
  "post_id": "18063215523019873",
  "published": true
}

{
  "published": false,
  "status": "publishing",
  "post_id": "6914b2c8e4a1f0d3c2b5a7e9"
}

What create_post accepts on one connected account: the network's limits (characters, title, media) and fields, and the account's own choices: TikTok privacy levels and which interactions the creator allows, Pinterest boards and the default one, the WordPress site, YouTube visibilities, Google Business Profile buttons. Call it before composing a post for an account you haven't posted to in this conversation.

{
  "account_id": "a4c6e8f0-2b4d-4f6a-9c1e-3d5f7b9a1c72",
  "provider": "pinterest",
  "network": "Pinterest",
  "limits": {
    "max_chars": 800,
    "title_max": 100,
    "title_required": false,
    "media": "required",
    "max_images": 1,
    "video": true
  },
  "fields": [
    "board_id",
    "link",
    "thumbnail_url"
  ],
  "boards": [
    {
      "id": "987654321098765432",
      "name": "Ceramics",
      "privacy": "PUBLIC"
    },
    {
      "id": "987654321098765433",
      "name": "Studio life",
      "privacy": "PUBLIC"
    }
  ],
  "default_board": {
    "id": "987654321098765432",
    "name": "Ceramics"
  }
}

Returns a link where the user uploads an image, a video or a document from their device, and the media_id to pass to create_post (media_ids), comment or a message (send_message, start_chat: media_id). Use it when the user wants a photo, video or document (a PDF, say) in a post or message and it isn't already online: files attached in the chat can't reach Pluggzy, so ask them to upload it here. If you made the file yourself in a sandbox or terminal with internet access, upload it yourself with the upload_command it returns. Images: JPEG, PNG or WebP, at most 8 MB. Videos: MP4, MOV or WebM, at most 5 GB on the page (upload_command sends at most 100 MB), for create_post on publishing accounts only (LinkedIn, Instagram, Facebook posts, comments and messages take images). Documents (PDF, Word, Excel, PowerPoint (docx, xlsx, pptx, doc, xls, ppt), TXT or CSV, at most 15 MB) for send_message and start_chat only. Each link takes one file: for another one (each image of a carousel, say), call upload_media again. The file can be used for 24 hours, in as many posts and messages as needed; a scheduled post keeps its own copy until it goes out.

{
  "url": "https://pluggzy.com/go/upload?t=eyJwIjoiY29ubmVjdCIsImV4cCI6MTc2MjY4MDAwMH0.k3Qm8ZrT0vX2bN5pL7wY1cA4dF6gH9jE",
  "media_id": "9b7d5f3a-1c2e-4a6b-8d0f-2e4c6a8b0d19",
  "upload_command": "curl -sS -T FILE_PATH -H 'X-File-Name: FILE_NAME' 'https://pluggzy.com/go/upload?t=eyJwIjoiY29ubmVjdCIsImV4cCI6MTc2MjY4MDAwMH0.k3Qm8ZrT0vX2bN5pL7wY1cA4dF6gH9jE'",
  "expires_in_minutes": 30,
  "usable_for_hours": 24,
  "max_image_mb": 8,
  "max_video_mb": 5000,
  "max_document_mb": 15
}

Posts of an account, most recent first, with post_id for list_comments, comment and instagrambusiness_get_insights: caption or text, link, date, likes and comments. Instagram (logged in): the account's own, or anyone's by user_id. Facebook: the account's own, one of its Pages (page_id) or anyone's (id or vanity name); at most 3 a page, follow next_cursor. Instagram Business: the account's own posts, at most the 25 most recent (made outside Pluggzy too).

{
  "items": [
    {
      "post_id": "3489012345678901234",
      "text": "New mugs are in the shop today ☕️",
      "url": "https://www.instagram.com/p/DQ3kF8sDk2L/",
      "at": "2026-11-06T17:30:00.000Z",
      "media": [
        "img"
      ],
      "likes": 412,
      "comments": 23
    }
  ],
  "next_cursor": "QVFIUnE4bW1Gd2hYc2Z4X0JfZ1",
  "has_more": true
}

Comments on a post (post_id from list_posts), most recent first, or with comment_id the replies to that comment, each with its comment_id for comment (reply_to), moderate_comment and private_reply. Facebook: at most 10 a page. Instagram Business: on the account's own posts; hidden comments show hidden: true, new ones can take 10 minutes to show.

{
  "post_id": "100089123456789_122134567890123456",
  "items": [
    {
      "comment_id": "122134567890123456_987654321098765",
      "text": "Still available? What size is the frame?",
      "at": "2026-11-04T14:02:11.000Z",
      "author": "Inès Garcia",
      "author_id": "100072345678901",
      "likes": 1,
      "replies": 1
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total": 1
}

Comment on a post (post_id from list_posts), or reply to one of its comments with reply_to (comment_id from list_comments). Facebook: as the personal account or one of its Pages (as_page), text and optionally one image (image_url, or media_id from upload_media); mention someone with @ and their id or vanity name. Instagram Business: on the account's own posts, as the account, text only; to answer a commenter privately use private_reply. Public: show the user the exact text first.

{
  "post_id": "100089123456789_122134567890123456",
  "comment_id": "122134567890123456_987654321098799",
  "sent": true
}

Moderate a comment on one of the Instagram Business account's posts (post_id and comment_id from list_comments). hide: only its author (and on Facebook their friends) and the account still see it, and the author isn't told; unhide: show it again; delete: remove it for good (anyone's comment, or the account's own). Hiding is the gentler choice. Confirm the exact comment and action with the user first: delete is irreversible.

{
  "post_id": "18063215523019873",
  "comment_id": "17912345678901234",
  "hidden": true
}

Send a direct message from the Instagram Business account to the author of a comment on one of its posts (the way to answer a commenter who never messaged the account). One per comment, within 7 days of the comment, and a failed try can use it up: show the user the exact text first and don't retry on your own. Their answers arrive in list_chats.

{
  "post_id": "18063215523019873",
  "comment_id": "17912345678901234",
  "message_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQ0",
  "sent": true
}

Posts scheduled with create_post (publish_at) or on the Pluggzy dashboard's calendar, on the accounts this connection can use: when, where, status, the text (and title, options and media links), and once published the post's URL. Posts scheduled before the calendar existed have no text here, only its length (chars).

{
  "items": [
    {
      "scheduled_post_id": "7c1e9a3f-5b2d-4e8a-9f0c-6d4b2a8e1c35",
      "account_id": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f0a1b2c",
      "provider": "linkedin",
      "publish_at": "2026-11-12T08:30:00.000Z",
      "status": "scheduled",
      "chars": 212,
      "text": "Three things we learned building a partner program from scratch 🧵"
    },
    {
      "scheduled_post_id": "2a4c6e8f-0b1d-4f3a-8c5e-7d9b1f3a5c84",
      "account_id": "0d2f4b6a-8c1e-4a3d-b5f7-9e1c3a5d7f60",
      "provider": "threads",
      "publish_at": "2026-11-12T16:00:00.000Z",
      "status": "scheduled",
      "chars": 64,
      "text": "New glazes drop Friday. Which one goes in the shop first?",
      "media_kind": "image",
      "media": [
        {
          "url": "https://cdn.northwind.example/glazes.jpg",
          "type": "image"
        }
      ]
    }
  ]
}

Cancel a scheduled post (scheduled_post_id from create_post or list_scheduled_posts) that hasn't gone out yet, or a draft saved on the calendar. To change a post, cancel it and schedule the new version, or the user can edit it on the calendar in the Pluggzy dashboard.

{
  "scheduled_post_id": "7c1e9a3f-5b2d-4e8a-9f0c-6d4b2a8e1c35",
  "status": "cancelled"
}

How an account is doing, as its network reports it (Instagram Business, TikTok, YouTube, Pinterest, Google Business Profile, Threads). report: overview (default): the account's figures over the last `days` (views, reach, engagement, followers… as the network reports them, plus a comparable headline); without account, every analytics account side by side; followers: the follower (YouTube: subscriber) count day by day, with gained and lost; audience: followers by country, city, age and gender, as far as the network reports them; top_posts: the best posts of the last `days` by `sort` (engagement by default), with their figures; without account, across every analytics account; timing: when to post, from the account's own posts (best weekday × hour slots in UTC, posts per week vs engagement, how fast posts reach their final engagement; Instagram: when followers are online); inbox: messages received and sent, median time to first reply and the busiest hours; search_keywords: the Google searches that showed the Business Profile, by month; post: one post's figures (post_id from list_posts, top_posts or create_post); details=true adds its day-by-day curve and the network's extras (Facebook earnings, YouTube retention and daily views). Not every network has every report (followers: Instagram Business, TikTok, YouTube, Pinterest; audience: Instagram Business, TikTok, YouTube; inbox: Instagram Business; search_keywords: Google Business Profile). LinkedIn, WhatsApp, Telegram and the personal Instagram and Facebook logins have no insights here. Read-only.

{
  "report": "overview",
  "from": "2026-10-11",
  "to": "2026-11-09",
  "accounts": [
    {
      "account_id": "e2c4a6b8-1d3f-4a5c-9e7b-2f4d6a8c0e13",
      "provider": "instagrambusiness",
      "name": "Northwind Studio",
      "source": "account",
      "metrics": {
        "reach": 12480,
        "views": 48210,
        "accounts_engaged": 1034,
        "total_interactions": 2876,
        "likes": 2310,
        "comments": 184,
        "saves": 212,
        "shares": 97,
        "profile_views": 1920,
        "website_clicks": 61
      },
      "headline": {
        "views": 48210,
        "reach": 12480,
        "engagement": 2876,
        "followers": null,
        "followers_gained": null,
        "followers_lost": null
      }
    },
    {
      "account_id": "f1a3c5e7-9b2d-4f6a-8c0e-5d7b9f1a3c48",
      "provider": "facebookpages",
      "name": "Northwind Studio",
      "source": "account",
      "metrics": {
        "page_media_view": 21340,
        "page_total_media_view_unique": 8120,
        "page_views_total": 640,
        "page_post_engagements": 1120,
        "page_video_views": 3010,
        "page_follows": 3420,
        "followers_gained": 58,
        "followers_lost": 9
      },
      "headline": {
        "views": 21340,
        "reach": 8120,
        "engagement": 1120,
        "followers": 3420,
        "followers_gained": 58,
        "followers_lost": 9
      }
    },
    {
      "account_id": "a4c6e8f0-2b4d-4f6a-9c1e-3d5f7b9a1c72",
      "provider": "pinterest",
      "name": "Northwind Studio",
      "source": "account",
      "metrics": {
        "impressions": 30900,
        "engagements": 1460,
        "saves": 380,
        "pin_clicks": 610,
        "outbound_clicks": 205,
        "follower_count": 1288,
        "followers_gained": 41,
        "followers_lost": 6
      },
      "headline": {
        "views": 30900,
        "reach": null,
        "engagement": 1460,
        "followers": 1288,
        "followers_gained": 41,
        "followers_lost": 6
      }
    }
  ]
}