Facebook

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
}

Opens a file someone sent or received in a conversation (chat_id, message_id and attachments[].attachment_id from get_messages). An image (JPEG, PNG, WebP, GIF, at most 3.75 MB) is shown to you, so you can see and describe it; get_messages already shows you a page's most recent images (shown_below: true): use this for the others. A document (PDF, Word .docx, Excel, TXT or CSV, at most 15 MB) comes back as its text, 50,000 characters at a time: next_offset says where to go on with offset. Scanned PDFs have no text. Videos, voice notes and PowerPoint files can't be opened: give the user the attachment's url. LinkedIn, WhatsApp, Telegram, Instagram and Facebook; Instagram Business and Facebook Pages messages give the file's link in get_messages instead.

{
  "chat_id": "6Wx3HyhTVvKmNy2kP9zQ1A",
  "message_id": "3EB0A9C4D2F1E8B7A6C5",
  "attachment_id": "9f3c2a71-4b8e-4d1a-a6f0-2c5e8b7d1e94",
  "mimetype": "image/jpeg",
  "size_bytes": 184312
}

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
}

Message someone you have no conversation with yet. Pick the account (or, with one account per network, the provider). `to`: LinkedIn: the person_id (from linkedin_search_people or get_profile) of a 1st-degree connection, or anyone with inmail=true (needs Premium InMail credits); WhatsApp: a phone number with its country code, like +33 6 12 34 56 78; Telegram, Instagram and Facebook: the user id (a chat's person_id, a group member's or friend's user_id, or from get_profile). New conversations have low daily limits (WhatsApp 10, Telegram 10, Instagram 10, Facebook 10), and networks restrict accounts that message strangers: WhatsApp bans new accounts after 2–3 cold messages; on Instagram and Facebook, people who don't follow or aren't friends get it as a message request. Only message people who expect it. Confirm the exact recipient and final text with the user 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.

{
  "chat_id": "Hs8vR2kLqP4wYt6Nc1dXbA",
  "message_id": "7mKQx2VdTnW8bLr4Yc9ez3",
  "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
}

Accept a Messenger message request (chat_id from list_chats with requests: true). A personal Facebook account accepts it as is (the conversation moves to its inbox; reply with send_message). Confirm with the user first, and show them the exact text of any reply.

{
  "chat_id": "Fb4Req8Lm2Np6Qr0St3Uv",
  "accepted": true
}

Members of a WhatsApp, Telegram or Facebook group chat (chat_id from list_chats, a group), with their user_id for get_profile and start_chat, and on WhatsApp their phone number.

{
  "chat_id": "120363041234567890@g.us",
  "items": [
    {
      "user_id": "33612345678@s.whatsapp.net",
      "name": "Lucas Bernard",
      "phone": "+33612345678",
      "admin": true
    },
    {
      "user_id": "447700900123@s.whatsapp.net",
      "name": "Emma Wilson",
      "phone": "+447700900123",
      "admin": false
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total": 2
}

On a personal Facebook account: the Pages it manages and that were activated when it connected, with their page_id: list_chats with page_id reads a Page's inbox (send_message then answers as the Page), and as_page on create_post, comment and facebook_react_post acts as the Page. A Page missing here was not activated: get a reconnect link (connect_account, provider facebook, mode reconnect); that login offers every Page again.

{
  "pages": [
    {
      "page_id": "104512345678901",
      "name": "Northwind Studio",
      "inbox_id": "PAGE_104512345678901_INBOX",
      "messaging": true
    }
  ]
}

Read someone's profile on a connected account's network. LinkedIn: the full profile (headline, experience, education, skills, contact info when shared) by person_id or public identifier (the part after linkedin.com/in/). WhatsApp: a contact's WhatsApp id (a chat's person_id) or phone number with country code; Telegram: user id; Instagram: user id or username; Facebook: id or vanity name of a person or Page, or me. Name, username, phone when the network shares it, bio, followers and picture. Counts as a profile view.

{
  "person_id": "ACoAAA8BYqEBCVM2yBH2uI6u",
  "public_id": "ada-martin-4b2a1c",
  "name": "Ada Martin",
  "headline": "VP Sales at Northwind Traders",
  "location": "Paris, Île-de-France, France",
  "degree": "FIRST_DEGREE",
  "summary": "Building sales teams that customers like talking to. 12 years in B2B SaaS.",
  "followers": 4820,
  "connections": 500,
  "premium": true,
  "open_profile": false,
  "url": "https://www.linkedin.com/in/ada-martin-4b2a1c",
  "experience": [
    {
      "company": "Northwind Traders",
      "title": "VP Sales",
      "from": "3/2022",
      "to": "present"
    }
  ],
  "education": [
    {
      "school": "ESSEC Business School",
      "degree": "Master in Management"
    }
  ],
  "skills": [
    "B2B Sales",
    "Sales Management",
    "SaaS"
  ],
  "emails": [
    "ada.martin@northwind.example"
  ]
}

The account's Facebook friends (Facebook shows no one else's), up to 50 a page, with their user_id for get_profile and start_chat. With requests: received or sent, the pending friend requests instead, with request_id for facebook_friend_request.

{
  "items": [
    {
      "user_id": "100072345678901",
      "name": "Inès Garcia",
      "username": "ines.garcia",
      "url": "https://www.facebook.com/ines.garcia",
      "picture": "https://scontent.xx.fbcdn.net/v/t39.30808-1/498765432_n.jpg"
    }
  ],
  "next_cursor": "Y3Vyc29yOmZyaWVuZHM6NTA",
  "has_more": true,
  "total": 412
}

send: send a friend request to user_id (Facebook friend requests carry no message; Facebook blocks accounts that send many, so it is limited per day and per week: check account_status first). accept: accept a request the account received. decline: refuse a received request, or cancel one the account sent (request_id from facebook_list_friends with requests). Confirm the exact person with the user first. To follow someone without being friends, use facebook_follow.

{
  "request_id": "100072345678901",
  "user_id": "100072345678901",
  "sent": true
}

Follow a person or Page by Facebook id, to see their public posts without being friends. Counts toward the same daily limit as friend requests. Confirm with the user first.

{
  "user_id": "104512345678901",
  "following": 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). Facebook: text ≤10000, one image (optional). 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
}

Replace the text of a post the account (or one of its Pages) published (post_id from list_posts); it keeps its image and audience. Public: confirm the new text with the user first.

{
  "post_id": "100089123456789_122134567890123456",
  "edited": 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
}

React to a post (post_id from list_posts), or to one of its comments with comment_id (from list_comments): like, love, care, haha, wow, sad or angry. As the personal account or one of its Pages (as_page). remove=true takes the reaction back (same reaction and as_page as when it was added). For Messenger messages use react.

{
  "post_id": "100089123456789_122134567890123456",
  "reaction": "love",
  "reacted": 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"
}