Postproxy MCP Server

Postproxy MCP Server

MCP (Model Context Protocol) server for integrating Postproxy API with Claude Code. This server provides tools for publishing posts, checking statuses, and managing social media profiles through Claude Code.

Installation

Global Installation

npm install -g postproxy-mcp

Local Installation

npm install postproxy-mcp

Claude Code stores MCP server configuration under ~/.claude/plugins/. After installing postproxy-mcp, Claude will automatically detect the server on restart.

Configuration

Register MCP Server

After installing postproxy-mcp, register it with Claude Code using the claude mcp add command:

claude mcp add --transport stdio postproxy-mcp --env POSTPROXY_API_KEY=your-api-key --env POSTPROXY_BASE_URL=https://api.postproxy.dev/api -- postproxy-mcp

Replace your-api-key with your actual Postproxy API key.

The configuration will be automatically saved to ~/.claude/plugins/. After running this command:

1. Restart your Claude Code session
2. Test the connection by asking Claude: "Check my Postproxy authentication status"
3. If tools are available, Claude will be able to use them automatically

Alternative: Interactive Setup

For non-technical users, you can use the interactive setup command:

postproxy-mcp setup

or

postproxy-mcp-setup

This will guide you through the setup process step by step and register the server using claude mcp add automatically.

Available Tools

Authentication Tools

auth_status

Check authentication status, API configuration, and workspace information.

Parameters: None

Returns:

{
  "authenticated": true,
  "base_url": "https://api.postproxy.dev/api",
  "profile_groups_count": 2
}

Account Overview

summary_get

Answer "what's the status?" in one call — an activity snapshot for a time window instead of separate history_list / comments_list / dm_chats_list round trips.

Parameters:

• window (string, optional): 24h (default), 7d, or 30d
• from (string, optional): ISO 8601 timestamp or bare date starting an explicit range. Overrides window, and the *_previous counts come back null
• to (string, optional): End of the explicit range. Defaults to now when only from is given
• profile_group_id (string, optional): Report on a single group. Omit to cover every group the key can reach

Returns:

{
  "window": {
    "label": "24h",
    "from": "2026-08-17T09:00:00Z",
    "to": "2026-08-18T09:00:00Z",
    "previous_from": "2026-08-16T09:00:00Z",
    "backlog_from": "2026-07-19T09:00:00Z"
  },
  "posts": {
    "published": 4,
    "published_previous": 3,
    "failed": 1,
    "scheduled_ahead": 6,
    "next_scheduled_at": "2026-08-18T14:00:00Z",
    "by_platform": { "instagram": { "published": 4, "failed": 0 } }
  },
  "engagement": {
    "total": { "impressions": 48210, "likes": 1204 },
    "by_platform": { "instagram": { "impressions": 31002, "likes": 900 } },
    "posts_with_insights": 14
  },
  "comments": { "received": 96, "received_previous": 71, "awaiting_reply": 12, "by_platform": { "instagram": 61 } },
  "reviews": { "received": 7, "received_previous": 4, "awaiting_reply": 3 },
  "dms": { "inbound": 41, "outbound": 33, "chats_awaiting_reply": 5, "reply_window_closing": 2 },
  "api": { "calls": 812, "calls_previous": 640 }
}

Notes:

• Post counts are posts, so a post sent to three networks counts once and a thread counts once. by_platform counts per-network deliveries, so a 3-item X thread is 3 under twitter.
• engagement is lifetime-to-date for posts published in the window, not engagement earned during it — it sums each post's newest stats snapshot. A post published minutes ago may have no snapshot yet and won't be in posts_with_insights. Keys are the normalized metrics listed in Stats Fields by Platform.
• The awaiting_reply counts describe current state, not the window — they don't change when you change window. They look back 30 days, returned as window.backlog_from. A comment counts as replied only when the reply came from you (via Postproxy or the profile itself); chats_awaiting_reply is derived from message timestamps, since Postproxy has no read/unread state.
• reply_window_closing counts chats with under 6 hours of their 24h messaging window left. Networks without a window (Telegram, Bluesky) are excluded.
• engagement is null when insights are off for the account; dms is null when DMs are off.
• Scoped like every other tool: a group-scoped key reports only its group.

Profile Management

profile_groups_list

List all profile groups accessible with your API key. Profile groups are organizational containers (e.g. per brand or client) that hold related profiles. Use a group's id to filter profiles_list by profile_group_id.

Parameters: None

Returns:

{
  "profile_groups": [
    {
      "id": "grp123abc",
      "name": "Main Brand",
      "profiles_count": 4
    }
  ]
}

profile_groups_initialize_connection

Generate a connect URL for a new profile in a profile group. The user opens the URL to finish the OAuth flow.

Parameters:

• profile_group_id (string, required): Profile group ID
• platform (string, required): Platform to connect (e.g. instagram, linkedin, whatsapp)
• onboarding (string, optional): Instagram and WhatsApp only. Instagram: instagram (default) uses Instagram Login; facebook uses Facebook Login, for an Instagram professional account linked to a Facebook Page you manage. The profile is platform: "instagram" either way, and reconnecting with the other method updates the existing profile in place. WhatsApp: api or business_app (see WhatsApp Business Management).
• identifier + app_password (Bluesky) / bot_token (Telegram): credentials, local server only

profiles_list

List all available social media profiles for posting.

Parameters:

• profile_group_id (string, optional): If provided, only profiles in this group are returned (use profile_groups_list to find group IDs)

Returns:

{
  "profiles": [
    {
      "id": "profile-123",
      "name": "My Twitter Account",
      "platform": "twitter",
      "profile_group_id": "group-abc"
    }
  ]
}

profiles_placements

List available placements for a profile. For Facebook profiles, placements are business pages. For LinkedIn profiles, placements include the personal profile and organizations. For Pinterest profiles, placements are boards. For Telegram profiles, placements are channels the bot can post to. For Google Business profiles, placements are locations, returned as full resource paths (accounts/X/locations/Y) to pass as location_id. For WhatsApp profiles, placements are the phone numbers on the Business Account — the placement id is the phone_number_id every whatsapp_* tool and dm_chat_create take. Available for facebook, linkedin, pinterest, telegram, google_business, and whatsapp profiles.

Parameters:

• profile_id (string, required): Profile hashid

Returns (LinkedIn example):

{
  "placements": [
    {
      "id": null,
      "name": "Personal Profile"
    },
    {
      "id": "108520199",
      "name": "Acme Marketing"
    }
  ]
}

Notes:

• If no placement is specified when creating a post:
  • LinkedIn: defaults to the personal profile
  • Facebook: defaults to a random connected page (if only one page is connected, no need to set a placement ID)
  • Pinterest: it fails
  • Telegram: it fails — chat_id is required on every post
  • Google Business: it fails — location_id is required on every post and on every google_business_* tool

profiles_stats

Get the follower/engagement timeseries for a profile. Snapshots are captured roughly every 23 hours, so you can plot follower growth and other trends over time. The stats fields are platform-native (not normalized) — see Stats Fields by Platform in the post_stats section for shape and add-on profile-level keys (followers_count, followersCount, etc.) per network.

Parameters:

• profile_id (string, required): Profile hashid
• placement_id (string, conditional): Required for facebook, linkedin, telegram, and google_business profiles. Get it from profiles_placements. Omit for instagram, threads, youtube, twitter, tiktok, pinterest, and bluesky.
• from (string, optional): ISO 8601 timestamp — only include snapshots recorded at or after this time
• to (string, optional): ISO 8601 timestamp — only include snapshots recorded at or before this time

Returns (LinkedIn example):

{
  "data": {
    "profile_id": "prof_li_001",
    "platform": "linkedin",
    "placement_id": "108520199",
    "records": [
      { "stats": { "followerCount": 4500, "shareCount": 8, "likeCount": 80 }, "recorded_at": "2026-05-09T08:00:00Z" },
      { "stats": { "followerCount": 4520, "shareCount": 9, "likeCount": 90 }, "recorded_at": "2026-05-10T08:00:00Z" }
    ]
  }
}

For non-placement networks (e.g. Bluesky), omit placement_id:

{
  "data": {
    "profile_id": "prof_bsky_001",
    "platform": "bluesky",
    "placement_id": null,
    "records": [
      { "stats": { "followersCount": 8800, "postsCount": 40 }, "recorded_at": "2026-05-09T08:00:00Z" }
    ]
  }
}

Post Management

post_publish

Publish a post to specified social media profiles.

Parameters:

• content (string, required): Post content text

• profiles (string[], required): Array of profile IDs (hashids) or platform names (e.g., "linkedin", "instagram", "twitter"). When using platform names, posts to the first connected profile for that platform.

• schedule (string, optional): ISO 8601 scheduled time

• media (string[], optional): Array of media URLs or local file paths

• idempotency_key (string, optional): Idempotency key for deduplication

• require_confirmation (boolean, optional): If true, return summary without publishing

• draft (boolean, optional): If true, creates a draft post that won't publish automatically

• queue_id (string, optional): Queue ID to add the post to. The queue will automatically assign a timeslot. Do not use together with schedule.

• queue_priority (string, optional): Priority when adding to a queue: high, medium (default), or low

• platforms (object, optional): Platform-specific parameters. Key is platform name (e.g., "instagram", "youtube", "tiktok"), value is object with platform-specific options. See Platform Parameters Reference for full documentation.

  Example:

  {
    "instagram": {
      "format": "reel",
      "collaborators": ["username1", "username2"],
      "first_comment": "Link in bio!"
    },
    "youtube": {
      "title": "My Video Title",
      "privacy_status": "public"
    },
    "tiktok": {
      "privacy_status": "PUBLIC_TO_EVERYONE",
      "auto_add_music": true
    }
  }
  

Returns:

{
  "post_id": "job-123",
  "accepted_at": "2024-01-01T12:00:00Z",
  "status": "pending",
  "draft": true
}

Note on draft posts: If you request a draft post (draft: true) but the API returns draft: false, a warning field will be included in the response indicating that the API may have ignored the draft parameter. This can happen if the API does not support drafts with certain parameters (e.g., media attachments) or under specific conditions. Check the warning field in the response for details.

post_status

Get status of a published post by job ID.

Parameters:

• post_id (string, required): Post ID from post.publish response

Returns:

{
  "post_id": "job-123",
  "overall_status": "complete",
  "draft": false,
  "status": "processed",
  "content": "Full post body as submitted...",
  "scheduled_at": "2024-01-02T09:00:00Z",
  "created_at": "2024-01-01T12:00:00Z",
  "source": "postproxy",
  "queue_id": null,
  "platforms": [
    {
      "platform": "twitter",
      "status": "published",
      "url": "https://twitter.com/status/123",
      "post_id": "123",
      "error": null,
      "attempted_at": "2024-01-01T12:00:00Z"
    }
  ]
}

scheduled_at is null for posts published immediately. Platform url is the published permalink (null until published).

Status values:

• overall_status: "draft", "pending", "processing", "complete", "failed"
• Platform status: "pending", "processing", "published", "failed", "deleted"
• Platform error: Error message if publishing failed (null if successful)

post_publish_draft

Publish a draft post. Only posts with draft: true status can be published using this endpoint.

Parameters:

• post_id (string, required): Post ID of the draft post to publish

Returns:

{
  "post_id": "job-123",
  "status": "processed",
  "draft": false,
  "scheduled_at": null,
  "created_at": "2024-01-01T12:00:00Z",
  "message": "Draft post published successfully"
}

post_delete

Delete a post by job ID.

Parameters:

• post_id (string, required): Post ID to delete

Returns:

{
  "post_id": "job-123",
  "deleted": true
}

post_stats

Get stats snapshots for one or more posts. Returns all matching snapshots so you can see trends over time. Supports filtering by profiles/networks and timespan.

Parameters:

• post_ids (string[], required): Array of post hashids (max 50)
• profiles (string, optional): Comma-separated list of profile hashids or network names (e.g. instagram,twitter or abc123,def456 or mixed)
• from (string, optional): ISO 8601 timestamp — only include snapshots recorded at or after this time
• to (string, optional): ISO 8601 timestamp — only include snapshots recorded at or before this time

Returns:

{
  "data": {
    "abc123": {
      "platforms": [
        {
          "profile_id": "prof_abc",
          "platform": "instagram",
          "records": [
            {
              "stats": {
                "impressions": 1200,
                "likes": 85,
                "comments": 12,
                "saved": 8
              },
              "recorded_at": "2026-02-20T12:00:00Z"
            }
          ]
        }
      ]
    }
  }
}

Stats fields by platform:

Notes: Instagram stories do not return stats. TikTok stats require the post to have a public ID.

Queue Management

queues_list

List all posting queues. Queues automatically schedule posts into recurring weekly timeslots with priority-based ordering.

Parameters:

• profile_group_id (string, optional): Filter queues by profile group

Returns:

{
  "queues": [
    {
      "id": "q1abc",
      "name": "Morning Posts",
      "description": "Daily morning content",
      "timezone": "America/New_York",
      "enabled": true,
      "jitter": 10,
      "profile_group_id": "pg123",
      "timeslots": ["Monday at 09:00 (id: 1)", "Wednesday at 09:00 (id: 2)"],
      "posts_count": 5
    }
  ]
}

queues_get

Get details of a single posting queue including its timeslots and post count.

Parameters:

• queue_id (string, required): Queue ID

queues_create

Create a new posting queue with weekly timeslots.

Parameters:

• profile_group_id (string, required): Profile group ID to connect the queue to (use profiles_list to find this)
• name (string, required): Queue name
• description (string, optional): Optional description
• timezone (string, optional): IANA timezone name (e.g. America/New_York). Default: UTC
• jitter (number, optional): Random offset in minutes (0–60) applied to scheduled times for natural posting patterns. Default: 0
• timeslots (array, optional): Initial weekly timeslots. Each object has day (0=Sunday through 6=Saturday) and time (24-hour HH:MM format)

Example:

{
  "profile_group_id": "pg123",
  "name": "Weekday Mornings",
  "timezone": "America/New_York",
  "jitter": 10,
  "timeslots": [
    { "day": 1, "time": "09:00" },
    { "day": 2, "time": "09:00" },
    { "day": 3, "time": "09:00" },
    { "day": 4, "time": "09:00" },
    { "day": 5, "time": "09:00" }
  ]
}

queues_update

Update a queue's settings, timeslots, or pause/unpause it. Changes to timezone or timeslots trigger rearrangement of all queued posts.

Parameters:

• queue_id (string, required): Queue ID to update
• name (string, optional): New queue name
• description (string, optional): New description
• timezone (string, optional): IANA timezone name
• enabled (boolean, optional): Set to false to pause the queue, true to unpause
• jitter (number, optional): Random offset in minutes (0–60)
• timeslots (array, optional): Timeslots to add or remove. To add: { "day": 1, "time": "09:00" }. To remove: { "id": 42, "_destroy": true }.

queues_delete

Delete a posting queue. Posts in the queue will have their queue reference removed but will not be deleted.

Parameters:

• queue_id (string, required): Queue ID to delete

queues_next_slot

Get the next available timeslot for a queue.

Parameters:

• queue_id (string, required): Queue ID

Returns:

{
  "next_slot": "2026-03-11T14:00:00Z"
}

Adding Posts to a Queue

When publishing a post with post_publish, you can add it to a queue instead of scheduling it manually:

• queue_id (string, optional): Queue ID to add the post to. The queue will automatically assign a timeslot. Do not use together with schedule.
• queue_priority (string, optional): Priority level: high, medium (default), or low. Higher priority posts get earlier timeslots.

Example:

{
  "content": "Queued post content",
  "profiles": ["twitter", "linkedin"],
  "queue_id": "q1abc",
  "queue_priority": "high"
}

Comment Management

comments_list

List comments on a published post. Returns paginated top-level comments with nested replies.

Parameters:

• post_id (string, required): Post ID
• profile_id (string, required): Profile ID to identify which platform's comments to retrieve
• page (number, optional): Page number, zero-indexed (default: 0)
• per_page (number, optional): Number of top-level comments per page (default: 20)
• from (string, optional): ISO 8601 date/time — only comments received at or after this point
• to (string, optional): ISO 8601 date/time — only comments received at or before this point

from/to filter on when Postproxy received the comment, not the platform's posted_at (which isn't always populated). A bare date such as 2026-03-25 means that date's start of day. The filter applies to top-level comments only — a comment in range still returns its full replies array.

Returns:

{
  "total": 42,
  "page": 0,
  "per_page": 20,
  "data": [
    {
      "id": "cmt_abc123",
      "external_id": "17858893269123456",
      "body": "Great post!",
      "status": "synced",
      "author_username": "someuser",
      "like_count": 3,
      "is_hidden": false,
      "posted_at": "2026-03-25T10:00:00.000Z",
      "replies": [
        {
          "id": "cmt_def456",
          "body": "Thanks!",
          "author_username": "author",
          "parent_external_id": "17858893269123456"
        }
      ]
    }
  ]
}

Comment objects may also include an attachments array (media on the comment — image, video, audio, gif, external, file), each with id, type, url, status, and external_id. Populated for Facebook, Threads, and Bluesky; Instagram, YouTube, and LinkedIn comments are text-only. The array is empty when there is no media.

comments_get

Get a single comment with its replies.

Parameters:

• post_id (string, required): Post ID
• comment_id (string, required): Comment ID (Postproxy ID or platform external ID)
• profile_id (string, required): Profile ID

comments_create

Create a comment or reply on a published post. The comment is published to the platform asynchronously.

Parameters:

• post_id (string, required): Post ID
• profile_id (string, required): Profile ID
• text (string, required): Comment text content
• parent_id (string, optional): ID of comment to reply to (Postproxy ID or external ID). Omit to comment on the post itself.

Returns:

{
  "id": "cmt_ghi789",
  "body": "Thanks for the feedback everyone!",
  "status": "pending",
  "external_id": null
}

The comment is created with status: "pending". Once published to the platform, it becomes "published". If publishing fails, it becomes "failed".

comments_delete

Delete a comment from the platform asynchronously. Supported on Instagram, Facebook, YouTube, and LinkedIn. Not supported on Threads.

Parameters:

• post_id (string, required): Post ID
• comment_id (string, required): Comment ID (Postproxy ID or external ID)
• profile_id (string, required): Profile ID

comments_edit

Edit the text of a comment you published, asynchronously. Supported on Facebook and YouTube only. Returns { accepted: true }; the outcome arrives via comment.edited / comment.edit_failed webhooks.

Parameters:

• post_id (string, required): Post ID
• comment_id (string, required): Comment ID (Postproxy ID or external ID)
• profile_id (string, required): Profile ID
• body (string, required): New comment text

comments_hide

Hide a comment on the platform asynchronously. Supported on Instagram, Facebook, and Threads.

Parameters:

• post_id (string, required): Post ID
• comment_id (string, required): Comment ID
• profile_id (string, required): Profile ID

comments_unhide

Unhide a previously hidden comment. Supported on Instagram, Facebook, and Threads.

Parameters:

• post_id (string, required): Post ID
• comment_id (string, required): Comment ID
• profile_id (string, required): Profile ID

comments_like

Like a comment on the platform asynchronously. Currently only supported on Facebook.

Parameters:

• post_id (string, required): Post ID
• comment_id (string, required): Comment ID
• profile_id (string, required): Profile ID

comments_unlike

Remove a like from a comment. Currently only supported on Facebook.

Parameters:

• post_id (string, required): Post ID
• comment_id (string, required): Comment ID
• profile_id (string, required): Profile ID

Platform Support

Direct Messages

1:1 messaging (chats and messages) on DM-capable profiles. Supported on Facebook (Messenger), Instagram (DMs), Telegram (Bot DMs), Bluesky, and WhatsApp. Outbound sends are processed asynchronously (returned with status: "pending"). Meta's 24h messaging window applies to Facebook/Instagram — a human replying to the participant's own inquiry can pass tag: "HUMAN_AGENT" to send outside it (up to 7 days, never for promotional or automated content); Telegram and Bluesky have no window. On WhatsApp the window is re-opened only by sending an approved template (template) or a category: "utility" text — see WhatsApp Business Management for the rest of the WhatsApp surface.

dm_chats_list

List chats for a profile, ordered by most recent activity.

Parameters:

• profile_id (string, required): Profile ID (Facebook, Instagram, Telegram, Bluesky, or WhatsApp)
• page (number, optional): Page number, zero-indexed (default: 0)
• per_page (number, optional): Items per page (default: 20)
• before / after (string, optional): ISO 8601 timestamp filters on last_message_at

WhatsApp chats also carry external_placement_id (the phone number the chat belongs to), group (true for group chats) and within_messaging_window.

dm_chat_create

Find or create a chat for a participant (idempotent — returns the existing chat if one exists). Use before messaging a participant the profile hasn't messaged yet.

Parameters:

• profile_id (string, required): Profile ID
• participant_external_id (string, required): Platform participant ID (IG-scoped user ID, Facebook PSID, Telegram user id, Bluesky DID, or a WhatsApp phone number with country code — non-digits are stripped)
• placement_id (string, optional): Placement id from profiles_placements. Required on WhatsApp (the phone number the chat is on); optional on Facebook (page id)
• participant_username (string, optional)
• participant_name (string, optional)

A brand-new WhatsApp conversation has no open messaging window, so the first send into it must be a template (see dm_message_send).

dm_chat_get

Get a single chat by Postproxy ID or platform external_conversation_id.

Parameters:

• chat_id (string, required): Chat ID or external conversation ID

dm_messages_list

List messages in a chat, most recent first.

Parameters:

• chat_id (string, required): Chat ID or external conversation ID
• page (number, optional): Page number, zero-indexed (default: 0)
• per_page (number, optional): Items per page (default: 20)
• direction (string, optional): inbound or outbound
• status (string, optional): Filter by message status

dm_message_send

Send an outbound message. Provide exactly one of body (text), media (a single attachment), or — on WhatsApp — template, interactive, location or contacts.

Parameters:

• chat_id (string, required): Chat ID or external conversation ID
• body (string, optional): Message text (required when nothing else is sent; on WhatsApp it may also accompany media as the caption)
• media (string[], optional): Up to one attachment as a URL or local file path. Not supported on Bluesky. (The remote/Worker MCP accepts URLs only.) WhatsApp limits: image 5MB jpeg/png, video 16MB mp4/3gpp, audio 16MB, document 100MB.
• tag (string, optional): HUMAN_AGENT to send outside the 24h window — extends it to 7 days from the participant's last inbound message (Facebook/Instagram only). Meta restricts it to a human replying to the participant's own inquiry; using it for marketing, offers, or automated re-engagement can get that Page / Instagram account's messaging capability suspended. Past 7 days Meta rejects the send and the message lands in status: failed with the platform error in error_details.
• reply_to_external_id (string, optional): Telegram & WhatsApp — platform message id (Telegram message_id, WhatsApp wamid) to quote / thread under
• reply_markup (object, optional): Telegram only — inline/reply keyboard payload
• quick_replies (object[], optional): Facebook & Instagram only — up to 13 tappable chips above the participant's composer. Each { title, payload }.
• buttons (object[], optional): Facebook & Instagram only — up to 3 buttons attached to the message. Each { type: "web_url", title, url } or { type: "postback", title, payload }.
• card (object, optional): Facebook & Instagram only — extra fields for the card carrying buttons (subtitle, image_url, default_action). Requires buttons.
• template (object, optional): WhatsApp only — send an approved template: { id | name, language, variables[], button_params[], header_media, header_location }. The only way to message outside the 24h window or to open a new conversation.
• interactive (object, optional): WhatsApp only — Meta-shaped interactive message (reply buttons, list, cta_url, product, flow, location request), passed through unchanged
• location (object, optional): WhatsApp only — { latitude, longitude, name, address }
• contacts (object[], optional): WhatsApp only — contact cards in Meta's contacts shape
• category (string, optional): WhatsApp only — "utility" marks a plain text send as a utility Direct Send that may go outside the window without a template
• link_preview (boolean, optional): WhatsApp only — false suppresses the URL preview on a text message
• voice_note (boolean, optional): WhatsApp only — deliver an OGG/Opus audio attachment as a voice note
• filename (string, optional): WhatsApp only — display name for a document attachment

Quick replies and buttons

Facebook Messenger and Instagram Direct only — on Telegram use reply_markup instead (passing these returns a 422). Quick replies are ephemeral chips that vanish once one is tapped; buttons stay attached to the message in the thread.

{
  "chat_id": "chat_xyz789",
  "body": "What can I help with?",
  "quick_replies": [
    { "title": "Track order", "payload": "TRACK" },
    { "title": "Talk to support", "payload": "HELP" }
  ]
}

{
  "chat_id": "chat_xyz789",
  "body": "Nike Air Max",
  "card": { "subtitle": "$129 · Arriving Friday", "image_url": "https://cdn.example.com/shoe.png" },
  "buttons": [
    { "type": "web_url", "title": "Buy now", "url": "https://shop.example.com/p/air-max" },
    { "type": "postback", "title": "Notify me", "payload": "NOTIFY:air-max" }
  ]
}

Buttons are delivered as a Meta generic template whose element title is your body — that's where the 80-character cap comes from. Instagram is stricter than Messenger: it delivers quick replies only on a plain-text message, so quick_replies with media or with buttons returns 422 there.

Receiving taps: a tapped chip or button postback arrives as an inbound message carrying tapped_action: { "kind": "quick_reply" | "postback" | "callback_query", "payload": "...", "title": "..." }. Read it from dm_messages_list / dm_message_get instead of digging through platform_data. Instagram ice-breaker taps and Telegram callback queries normalize to the same field.

WhatsApp templates and interactive messages

A WhatsApp number can only send free-form text, media, interactive, location and contacts while the participant's 24h window is open (within_messaging_window on the chat). Outside it — including a conversation you start yourself — send an approved template. variables fill the placeholders in order (header text vars first, then body vars, then dynamic URL button vars) and must match the template's variable_count from whatsapp_templates_list; the rendered body is stored on the message.

{
  "chat_id": "chat_wa1",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "variables": ["Ana", "ORD-12345"]
  }
}

Templates with a media header take header_media: { "link": "https://..." }; a location header takes header_location; URL / copy-code / flow buttons take button_params: [{ "index": 0, "sub_type": "url", "parameters": [{ "type": "text", "text": "12345" }] }].

Inside the window, interactive is Meta's own object — reply buttons (up to 3), a list (up to 10 rows), a CTA URL, a product card, a flow or a location request:

{
  "chat_id": "chat_wa1",
  "interactive": {
    "type": "button",
    "body": { "text": "Ready to confirm your booking?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "confirm", "title": "Confirm" } },
        { "type": "reply", "reply": { "id": "reschedule", "title": "Reschedule" } }
      ]
    }
  }
}

A tap comes back as an inbound message whose body is the tapped title, with the reply id under platform_data.interactive. Facebook/Instagram quick_replies / buttons return 422 on WhatsApp, and template / interactive / location / contacts / category return 422 on every other network.

dm_message_get

Get a single message by Postproxy ID or platform external_id.

Parameters:

• message_id (string, required): Message ID or external ID

dm_message_edit

Edit a previously-sent outbound message. Telegram only. Provide body and/or reply_markup (pass {} to clear the keyboard); at least one is required.

Parameters:

• message_id (string, required): Message ID or external ID
• body (string, optional): New text/caption
• reply_markup (object, optional): New keyboard (or {} to remove)

dm_message_react / dm_message_unreact

Add or remove your business account's reaction on a message. Facebook Messenger, Instagram Direct and WhatsApp.

Parameters (dm_message_react):

• message_id (string, required): Message ID or external ID
• reaction (string, optional): Named reaction (default love). Ignored on WhatsApp
• emoji (string, optional): Unicode emoji. Required on WhatsApp (any emoji)

Parameters (dm_message_unreact):

• message_id (string, required)

dm_chat_archive / dm_chat_unarchive

Archive (mute) or unarchive (unmute) a chat. Bluesky only. Returns the chat with archived set.

Parameters:

• chat_id (string, required): Chat ID or external conversation ID

dm_chat_mark_read

Mark a chat as read. On WhatsApp this sends the read receipt (blue ticks) for the newest inbound message; on other networks it only stamps metadata.read_at. Returns the chat.

Parameters:

• chat_id (string, required): Chat ID or external conversation ID

dm_comment_private_reply

Send a DM to the author of a comment, in reply to that comment (Meta "Private Replies"). Bypasses the 24h window (comments up to 7 days old) and creates/reuses a chat automatically. One private reply per comment, ever. Instagram and Facebook only.

Parameters:

• post_id (string, required): Post ID
• comment_id (string, required): Comment ID or external ID
• profile_id (string, required): Profile ID (Instagram or Facebook)
• text (string, required): DM text
• quick_replies (array, optional): Up to 13 chips — same shape as dm_message_send
• buttons (array, optional): Up to 3 buttons — same shape as dm_message_send; caps text at 80 characters
• card (object, optional): Card styling for buttons (subtitle, image_url, default_action)

Interactive elements follow the same rules as dm_message_send — on Instagram, quick_replies and buttons are mutually exclusive. Media attachments are not available on private replies.

Platform Support

History

history_list

List recent post jobs.

Parameters:

• limit (number, optional): Maximum number of jobs to return (default: 10)

Returns:

{
  "jobs": [
    {
      "post_id": "job-123",
      "content": "Full post body as submitted...",
      "content_preview": "Post content preview...",
      "created_at": "2024-01-01T12:00:00Z",
      "overall_status": "complete",
      "status": "processed",
      "scheduled_at": "2024-01-02T09:00:00Z",
      "draft": false,
      "source": "postproxy",
      "queue_id": null,
      "platforms_count": 2,
      "platforms": [
        {
          "platform": "twitter",
          "status": "published",
          "url": "https://x.com/user/status/123"
        }
      ]
    }
  ]
}

scheduled_at is null for posts that were published immediately. status is the raw API status (draft, scheduled, processing, processed, …), while overall_status folds platform outcomes into a single verdict.

Note: Postproxy's /posts API does not return profile identity (profile ID or name) per platform — only the network. Use profiles_list to map networks to connected profiles.

Google Business Profile Management

These edit the Google business listing itself — hours, attributes, services, food menus, action links and profile photos — as opposed to publishing local posts to it (that's post_publish with platform google_business).

Three rules apply to every tool in this group:

1. location_id is always required. It's the full Google resource path accounts/X/locations/Y, returned by profiles_placements.
2. Updates are field-masked. Each write takes a fields array naming exactly what's being replaced. Anything named in fields but absent from the payload is cleared, and nested objects are replaced wholesale rather than merged. Always read before you patch.
3. Availability varies by category and region. Attributes, service lists, food menus and action link types differ per listing. List what's available first; a location that isn't eligible returns 422.

Payloads use Google's own shapes and camelCased keys in both directions, so a response can be sent straight back as a request body.

Documentation truncated — see the full README on GitHub.