SocialAPI Post Scheduler Inbox

View saved version →

---
name: comment-automations
description: Set up and monitor Instagram and Facebook Automations with the SocialAPI app. Comment-to-DM lead magnets ("comment LINK to get it"), follow-gated links, keyword auto-replies to comments and DMs, and FAQ answers, then check how each run went. Use when the user says "auto reply", "automation", "comment to DM", "send the link to everyone who comments", "keyword reply", "follow to unlock", "lead magnet", or wants replies to go out without them.
---

# Comment and DM Automations

Requires the SocialAPI app in ChatGPT. Every tool name starts with `social_api_`. The `socialapi` skill's Automations section holds the full `create_automation` format: follow it for every call.

Automations work on Instagram and Facebook accounts only, up to 50 per account. On any other platform, say so and stop.

## 1. Goal

Get the trigger (a comment, or a DM), the keywords, what to send, which posts it covers, and whether each person gets it only once (`once_per_person`). Ask only for what is missing.

## 2. Account and posts

- `list_accounts` for the Instagram or Facebook account `id`.
- To limit it to some posts, `list_inbox_posts` for that account and use each post's `id` in `post_ids` (up to 100). Leave `post_ids` out to cover every post.

## 3. Build it

- Keyword filter: `{"type": "keyword", "keyword": {"keywords": [...], "match": "contains"}}`. It matches whole words and ignores case and accents.
- Comment trigger, `start` step: prefer `private_reply` (free) to send the link by DM. `reply_comment` costs 1 credit per run, `hide_comment` is free.
- DM trigger, `start` step: `send_dm`, 1 credit per run. It answers the same person at most 5 times an hour.
- Give 3 to 5 `texts` variants so replies do not all look identical. Up to 1000 characters each, or 640 when the step has buttons.
- Buttons: up to 3, titles up to 20 characters. A `postback` button leads to a later step, which may only send DMs. On Facebook, buttons on a `send_dm` step are not shown.
- "Follow to get the link" on Instagram: use `follow_gate` with `"steps": []`.

## 4. Confirm, then create

Show the Automation in plain words (when it fires, what it sends, what it costs per run) and the JSON. Call `create_automation` only after an explicit yes.

## 5. Test and monitor

- Ask the user to trigger it from another account (comment the keyword, or send the DM), then `list_automation_firings` to show each action's outcome and error code.
- `list_automations` shows fired, sent and failed counts. Pause with `update_automation` and `status: paused`, resume with `active`.
- Deleting an Automation also deletes its run history: confirm before `delete_automation`.

View saved version →

---
name: failed-post-troubleshooting
description: Find out why a social media post failed or only partly published with the SocialAPI app, explain it in plain words, fix the cause and retry the platforms that failed. Use when the user says "my post failed", "didn't publish", "post not showing on Instagram", "scheduled post didn't go out", "partial", "publishing error", "retry my post", "why did it fail", or shares an error code.
---

# Failed post troubleshooting

Requires the SocialAPI app in ChatGPT. Every tool name starts with `social_api_`. The `socialapi` skill holds the error code table, platform support and `create_post` fields: follow it for every call.

## 1. Find the post

- The user named it or gave an id: `get_post` with that `post_id`.
- Otherwise: `list_posts` with `status: failed`, then `status: partial`, with `sort: created_desc`. Narrow with `platform`, `from`, `to` or `search`. A scheduled post that never went out also shows here.
- Several candidates: list them (date, platforms, start of the text) and ask which one.

## 2. Read what happened

`get_post` returns one entry per platform in `targets`, each with its `platform`, `account_id`, `status` and, when it failed, an `error` with `code`, `message` and `caused_by`.

- `partial` means some platforms published and others failed: name both.
- `caused_by: user` means the content or the account needs a change. `platform` means the platform refused or was unavailable. `system` means a problem on SocialAPI's side: retry once, and if it fails again, tell the user to contact contact@social-api.ai with the post id.
- For more detail, `list_events` with `resource_id` set to the post id and `category: post` shows what each platform answered.

## 3. Explain and fix

Explain each failed platform in one plain sentence, then the fix. The usual causes:

| Cause | Fix |
|---|---|
| `account.reconnection_required`, `platform.<name>.auth`, `platform.<name>.insufficient_scope`, or the account's `status` in `list_accounts` is not `active` | Reconnect with `connect_account`, then retry. |
| Instagram post without image or video, or no `platform_data.instagram.content_type` | Add media and a content type. |
| TikTok `privacy_level` refused | `get_creator_info`, then use one of the levels it lists. |
| Pinterest target without `board_id` | `list_pinterest_boards`, then set the board. |
| Media URL refused or not reachable | Ask for a public `https` link to the file. |
| `validation.*` | The `message` and `field` say what to change. Run `validate_post` on the corrected content. |
| `publishing.velocity_limit`, `platform.<name>.rate_limit`, `platform.<name>.throttled` | Too many posts in a short time. Wait `retry_after_seconds` when given, then retry. |
| `resource.not_supported` | The platform cannot do this. Retrying never helps: offer another format or platform. |
| `validation.post_limit_exhausted` | Monthly plan limit reached. `get_usage` shows when it resets. |

When the content must change, `update_post` works on `failed` posts only (and on drafts and scheduled posts). A `partial` post cannot be edited: create a new post for the failed platforms instead, with `create_post` targeting only those accounts.

## 4. Retry

- Ask before retrying: `retry_post` costs 1 post credit. It resends only the failed platforms of a `failed` or `partial` post, never the ones already published.
- Then poll `get_post` until it reads `published`, `partial` or `failed`, and report each platform's result. Never say it worked before that.
- If the same error comes back, do not retry again in a loop: explain what is still wrong and what the user needs to do.

View saved version →

---
name: google-reviews
description: Answer Google Business Profile reviews with the SocialAPI app. Find the reviews that have no reply yet, sort them by star rating, draft a reply for each in the business's voice, and post only the replies the user approves. Use when the user says "reply to my reviews", "Google reviews", "answer reviews", "unanswered reviews", "bad review", "1 star review", "review responses", "reputation", or asks about the rating of their business on Google.
---

# Google reviews

Requires the SocialAPI app in ChatGPT. Every tool name starts with `social_api_`. The `socialapi` skill holds the parameters, ids and error codes: follow it for every call.

Reviews work on Google Business Profile only. For any other platform, say so.

## 1. Find the locations

`list_review_accounts` with `platform: google`. These review tools return capitalised keys (`AccountID`, `Name`, `Status`, `Summary`).

- Use the accounts whose `Status` is `ok`.
- `reconnection_required`: say that location must be reconnected and offer `connect_account` for `google`.
- No account: say no Business Profile is connected and offer `connect_account`.
- Several locations: cover all of them, one section per location, unless the user named one.

## 2. Collect the reviews

`get_reviews` with `account_id` set to the `AccountID`:

- `order: newest` for "what came in", `rating_asc` to start with the worst.
- Up to 50 per page. Follow `next_cursor` until it is empty or the reviews are older than the period the user asked about.
- Each review has `ID`, `Rating` (1 to 5), `Text`, `Author`, `CreatedAt` and `Reply`. `Reply: null` means the business has not answered.
- The top-level `summary` holds `AverageRating`, `TotalCount` and `LastReviewAt`: open the report with them.

## 3. Sort

1. **1 and 2 stars, unanswered**: answer first.
2. **3 stars, unanswered**.
3. **4 and 5 stars, unanswered**.
4. **Already answered**: list them only when the user asks, or when the existing reply looks wrong.

A review with a rating and no text still deserves a short thank-you.

## 4. Draft

- Address the reviewer by the name in `Author`, mention one specific thing they wrote, and keep it short.
- Negative review: thank them, acknowledge the problem without arguing or admitting legal fault, and invite them to continue privately (`[phone or email]` placeholder unless the user gave one).
- Never invent facts, offer refunds or discounts, or quote prices the user did not give. Put a `[placeholder]` instead and point it out.
- Never put a customer's private details in a public reply.
- Up to 2200 characters, but most replies should fit in 2 to 4 sentences.

Show the review, its rating and the draft side by side, and wait for approval.

## 5. Post

- Call `reply_to_review` (`account_id`, `review_id` set to the review `ID`, `text`) once per approved reply. Each reply costs 1 interaction credit: when there are many, check `get_usage` first.
- `state: PENDING` means Google is checking the reply. That is a success: say it will appear once Google approves it. `REJECTED` means Google refused it: offer to rewrite it.
- A review has one business reply. Replying again replaces the existing reply and costs another credit, so warn before replacing one.
- A reply cannot be deleted with these tools.

Finish with what was posted, what is pending and what was left unanswered.

View saved version →

---
name: inbox-triage
description: Triage the social inbox with the SocialAPI app. Collect new comments, DMs, Google reviews and mentions across every connected account, rank what still needs a reply, draft answers in the brand's voice, and send only the replies the user approves. Use when the user says "what came in", "what needs a reply", "check my inbox", "answer my comments", "reply to my reviews", "any new DMs", "overnight", "today's messages", "clear my inbox", or asks for customer replies on social media.
---

# Inbox triage

Requires the SocialAPI app in ChatGPT. Every tool name starts with `social_api_`. The `socialapi` skill holds the parameters, ids, pagination rules, platform support and error codes: follow it for every call.

## 1. Set the scope

- Turn the user's window into an RFC3339 start time. With no window given, use the last 24 hours and say so.
- `list_accounts`. No account: say nothing is connected, offer `connect_account`, and stop. An account whose `status` is not `active` goes in the report as "needs reconnecting" and is skipped.
- Several brands: cover all of them, grouped by brand, unless the user named one.

## 2. Collect

Follow the `socialapi` skill's "What came in, and what still needs a reply" and "Reviews" sections:

- Comments: `list_inbox_posts` with `min_comments: 1`, then `list_post_comments` per post, filtered on `created_at` and `is_owner: false`.
- DMs: `list_conversations`, then `list_messages`. A conversation needs a reply when its newest message is `incoming`.
- Reviews: `list_review_accounts`, then `get_reviews` with `order: newest`. `Reply: null` means unanswered.
- Mentions: `get_mentions` with `since` on Instagram, Facebook, Threads, Bluesky and X.

Skip platforms that have no comments or DMs (see the platform table in the `socialapi` skill) without reporting them as errors.

## 3. Rank

Sort every item that needs a reply into one of three groups:

1. **Reply now**: complaints, 1 or 2 star reviews, order, booking or payment problems, and Instagram, Facebook or WhatsApp DMs whose last incoming message is more than 20 hours old (those platforms refuse a reply 24 hours after the person's last message; on Instagram, `message_tag: HUMAN_AGENT` extends that to 7 days).
2. **Needs a reply**: questions, unanswered positive reviews, leads asking about price or availability.
3. **No reply needed**: praise with no question, emoji-only comments, and spam (offer to hide spam, which is free).

## 4. Report

Start with the totals per group, then one table per account: platform, who, what they wrote (quoted), when, group, and a draft reply. Never invent an item: an empty inbox is a valid answer.

## 5. Draft and send

- Write in the account's voice. When unsure, read the account's own earlier replies (comments with `is_owner: true`, `outgoing` messages) and match them.
- Never promise a refund, discount, date or fact the user has not given. Leave a `[placeholder]` instead and point it out.
- Limits: comment and review replies up to 2200 characters, DMs and private replies up to 1000.
- Send nothing until the user approves a specific text. Then send each approved reply with its own call (`reply_to_comment`, `send_dm`, `reply_to_review`, `reply_to_mention`). Each costs 1 interaction credit, a private reply is free. Before sending many, check `get_usage`.
- Afterwards, list what was sent and what failed, with the meaning of each error code.

View saved version →

---
name: performance-report
description: Build social media performance reports with the SocialAPI app. Account, brand and post analytics over a period, follower growth and reach, top posts by engagement and comments, what commenters talk about, and next steps backed by the numbers. Use when the user asks "how did my account perform", "monthly report", "social analytics", "which posts did best", "follower growth", "engagement rate", "compare my platforms", or needs a report for a client.
---

# Performance report

Requires the SocialAPI app in ChatGPT. Every tool name starts with `social_api_`. The `socialapi` skill holds the analytics parameters, series format and error codes: follow it for every call.

## 1. Period and scope

- Dates are `YYYY-MM-DD`, at most 400 days. With no period given, use the last 30 days and state the dates. For a comparison, run the same call on the previous period of equal length.
- One account: `get_account_analytics` (with `page_id` for one Facebook or LinkedIn Page). A client or business with several accounts: `get_brand_analytics` with `brand_id`.

## 2. Read the numbers correctly

- A `gauge` (such as followers) is a level: growth is last value minus first value.
- A `flow` (such as reach) is a per-day count: sum it over the period.
- On a brand, a day with a lower `subjects_counted` had fewer accounts reporting. Call it a gap in the data, not a drop.
- No history yet: say so. Never fill in numbers.

## 3. Posts

- Posts published through SocialAPI: `list_posts` with `from`, `to` and `status: published`, then `get_post_metrics` for each post's current numbers and `get_post_analytics` for its history.
- Posts by comment count, including ones published elsewhere: `list_inbox_posts` with `sort_by: comments`.
- For the top 3 posts, read the comments with `list_post_comments` and sum up the main themes, quoting a few.

## 4. Report

1. Headline numbers with the change against the previous period, in percent.
2. A table per platform or account.
3. Top and bottom posts with their `permalink` and the metric they are ranked on.
4. What the audience talks about.
5. Three next steps, each tied to a number in the report (format, day, topic). Describe correlations, never claim one caused the other.

## 5. Spreadsheet

When the user wants a file, `create_export` for the account, then poll `get_export`. Its download link lasts 15 minutes, so share it as soon as it is ready. The free plan allows 2 exports a month.

View saved version →

---
name: post-scheduling
description: Plan, write and schedule social media posts with the SocialAPI app. Turn a brief or a week of themes into posts adapted to each platform, check them against each platform's rules, save drafts, and schedule or publish only after approval. Use when the user says "schedule a post", "plan my posts for the week", "content calendar", "cross-post this", "post to Instagram and LinkedIn", "draft a post", "publish now", or shares an announcement to put on social media.
---

# Post scheduling

Requires the SocialAPI app in ChatGPT. Every tool name starts with `social_api_`. The `socialapi` skill holds the full `create_post` fields, media rules, platform support and error codes: follow it for every call.

## 1. Brief

Get the message, the platforms, the dates and times with a timezone, and the media as public links. Ask only for what is missing. Without a timezone, ask before scheduling anything.

## 2. Accounts and per-platform ids

- `list_accounts` and map each platform the user named to its account `id`.
- Facebook Page or LinkedIn Page: `list_account_pages` for the `page_id`.
- Pinterest: `list_pinterest_boards` for the `board_id`, required on every Pinterest target.
- TikTok: `get_creator_info` before every post, and use one of the privacy levels it lists in `platform_data.tiktok.privacy_level`.

## 3. Write one variant per platform

Put the shared text in `text` and each platform's version in its target's own `text`. Adapt length, tone and hashtags to each network:

- Instagram: caption with hashtags. Every post needs an image or video and `platform_data.instagram.content_type` (`feed`, `carousel`, `reel` or `stories`).
- X: short. A longer message becomes a thread with `segments`.
- LinkedIn: longer and professional. A link preview goes in `platform_data.linkedin.article_url`.
- YouTube and Pinterest: set `title`.
- Google Business Profile: a short local update.

For exact limits, call `get_constraints` rather than guessing.

## 4. Check

`validate_post` with `account_ids`, the text, the media and the same `platform_data`. Fix every `errors` entry, report `warnings`. `validate_post` does not catch a missing Instagram image or video, so check that yourself.

## 5. Show the calendar

One table: date and time (user's timezone and UTC), platform, final text, media, check result. Wait for approval.

## 6. Save, schedule or publish

- By default, save drafts: `create_post` with neither `publish_now` nor `scheduled_at`. Drafts are free.
- After an explicit yes: `scheduled_at` (RFC3339) to schedule, or `publish_now: true`. Publishing or scheduling costs a post credit, so check `get_usage` first when there are many. One `create_post` per time slot; a target may carry its own `scheduled_at`.
- The same content posted again within 24 hours is refused unless `skip_duplicate_check: true`. Ask before setting it.
- After publishing, poll `get_post` until it reads `published`, `partial` or `failed` before saying it worked. Offer `retry_post` for failed targets.

View saved version →

---
name: socialapi
description: Operates the SocialAPI MCP tools (social_api_*) to read and answer comments, DMs, reviews and mentions, and to draft, validate, schedule and publish posts across Instagram, Facebook, Threads, TikTok, X, YouTube, LinkedIn, Google Business Profile, Pinterest, WhatsApp, Telegram, Zalo and Bluesky. Use when the user asks what came into their social inbox, which comments, DMs or reviews still need a reply, wants to answer one, check mentions, write, check or schedule a post, look at post or account analytics, set up comment or DM Automations, manage brands and connected accounts, or debug webhook deliveries.
---

# SocialAPI

Every tool name starts with `social_api_`. The short names below drop that prefix.

## First call: list_accounts

`list_accounts` returns each connected account: `id` (the `account_id` almost every other tool needs), `platform`, `username`, `brand_id`, `status`. Never guess an id or reuse one from an earlier conversation.

- **No accounts**: say plainly that no social account is connected yet, so there is nothing to read, and offer `connect_account`. Never invent comments, messages, reviews or posts.
- **`status` other than `active`**: that account needs reconnecting before anything works on it. Say so and offer `connect_account` for its platform.
- `connect_account` returns an `auth_url` for the user to open. The account connects by itself once they approve, no further call needed.
- Several businesses or clients: `list_brands`, then pass `brand_id` to `list_accounts`, `list_inbox_posts`, `list_conversations` and `list_posts`.

## What came in, and what still needs a reply

Turn the user's window ("overnight", "today") into an RFC3339 start time such as `2026-10-12T18:00:00Z`, and compare it with each comment's or message's own timestamp.

Comments:
1. `list_inbox_posts` with `min_comments: 1` and `limit: 100` (add `account_id` or `platform` to narrow it). It returns the most recently published posts that have comments. Do not pass `since` here: it filters on the post's publish date, so it would hide new comments on older posts. Each post `id` is a platform post id.
2. For each post, `list_post_comments` with `inbox_post_id` (that `id`) and `account_id`. The order depends on the platform, so follow `next_cursor` until it is empty and filter on `created_at`.
3. Keep comments with `created_at` inside the window and `is_owner: false`. `has_replies: false` means nobody has answered. When `has_replies` is true, a reply row (`parent_id` set to that comment) or `get_comment_replies` shows whether one of the replies is the account's own (`Author.IsOwner`).

DMs:
1. `list_conversations` lists the most recently active first. Stop paging once `last_message_at` is before the window.
2. A conversation needs a reply when its newest message is from the other person: `list_messages` returns newest first, so check the first message's `direction` (`incoming` or `outgoing`). `unread_count` above 0 is a quick hint.

Report by account, quote what people wrote, and draft replies. Send nothing until the user approves a specific text.

## Reviews

1. `list_review_accounts` (optionally `platform: google`). Use the accounts whose `Status` is `ok`. This tool and the review tools return capitalised keys: `AccountID`, `Name`, `Status`, `Summary`.
2. `get_reviews` with `account_id` set to that `AccountID` and `order: newest`. Each review has `ID`, `Rating`, `Text`, `Author`, `CreatedAt` and `Reply`, which is null when the business has not answered.
3. Draft each answer in the chat. Call `reply_to_review` (`account_id`, `review_id` set to the review `ID`, `text` up to 2200 characters) only for the replies the user approves. Google may return `state: PENDING` while it checks the reply: that is a success.

A Google review has one business reply, so calling `reply_to_review` again replaces it (and costs another credit). A reply cannot be deleted through these tools.

## Drafting and checking a post

1. `list_accounts` to find the account for each platform the user named.
2. `validate_post` with `account_ids` (preferred over `platforms`: it runs each account's own checks), `text`, any `media`, and the same `platform_data` you would publish with. Instagram needs `{"instagram": {"content_type": "feed"}}`, or `reel`, `stories` or `carousel`.
3. Report `errors` (blocking) and `warnings` (advisory), each with its `platform`, `field` and `message`. `get_constraints` gives the raw limits (text length, media count, file types and sizes) when the user asks for them.
4. Instagram cannot publish text alone: every Instagram post needs an image or video, and `validate_post` does not flag a missing one. When the user gave no media, say an image or video is needed for Instagram before anything is published.
5. Save or publish only when asked: `create_post` (see Publishing).

## Publishing

- `create_post` always takes `text` and one entry in `targets` per account, with `page_id` for a specific Facebook Page and `board_id` on every Pinterest target (`list_pinterest_boards` gives the board ids). `publish_now: true` publishes, `scheduled_at` (RFC3339) schedules, neither saves a free draft. `publish_post` publishes a draft later.
- Publishing finishes in the background: the call returns status `publishing`. Check `get_post` until it reads `published`, `partial` or `failed` before saying it worked. `retry_post` resends the failed targets of a `failed` or `partial` post.
- Media: a public file goes in as `{"source_type": "url", "source": "https://..."}`. `get_media_upload_url` returns an address that only accepts the file's bytes by HTTP PUT within 15 minutes, which a chat cannot send. Use it only when you can run HTTP requests yourself, then `verify_media_upload` and pass `{"source_type": "media_id", "source": "<media_id>"}`. Otherwise ask the user for a public link.
- Figures: `get_post_metrics` for a post's current numbers, `get_post_analytics`, `get_account_analytics` and `get_brand_analytics` for daily history.

## Credits

One interaction credit: `reply_to_comment`, `send_dm`, `reply_to_review`, `reply_to_mention`. One post credit: `create_post` when it publishes or schedules, `publish_post`, `retry_post`. Everything else is free, including drafts, reads, `private_reply_to_comment`, hiding, liking and deleting comments, and managing Automations. The free plan allows 10 posts and 50 interactions a month, paid plans are unlimited. `get_usage` shows what is left, where -1 means unlimited.

## Confirm first

- Anything public or that reaches a person: show the exact text and wait for a yes before `reply_to_comment`, `private_reply_to_comment`, `send_dm`, `reply_to_review`, `reply_to_mention`, `create_post` with `publish_now` or `scheduled_at`, `publish_post`, and `create_automation`.
- Irreversible: `delete_comment`, `delete_post`, `unpublish_post`, `delete_media`, `delete_brand` (disconnects all its accounts), `disconnect_account`, `delete_automation`, `delete_webhook`, `revoke_key`, `revoke_invite`. Name what disappears and wait for a yes.

## When a tool returns an error

A failed call returns `{"error": "...", "code": "..."}` with extra fields, or a plain sentence. Read it out rather than guessing.

| `code` | Meaning and what to do |
|---|---|
| `resource.not_supported`, or the sentence "Operation not supported for this platform" | The platform cannot do this. Do not retry. Say which platform, and check [references/platforms.md](references/platforms.md) for one that can. |
| `billing.platform_not_available` | That platform or account type is not open to this account. |
| `account.reconnection_required`, `platform.<name>.auth`, `platform.<name>.insufficient_scope` | The account must be reconnected: `connect_account`. |
| `platform.<name>.window_closed` | Instagram and Facebook only accept a DM within 24 hours of the person's last message. On Instagram, `message_tag: HUMAN_AGENT` extends that to 7 days; otherwise say the window has closed. |
| `platform.<name>.private_reply_ineligible` | A private reply was already sent for that comment, or the comment is older than 7 days. |
| `validation.post_limit_exhausted`, `validation.interaction_limit_exhausted` | Monthly plan limit reached. `get_usage` shows when it resets. |
| `ratelimit.exceeded`, `publishing.velocity_limit`, `messaging.velocity_limit`, `platform.<name>.rate_limit`, `platform.<name>.throttled` | Too many calls. Wait `retry_after_seconds` when present, then retry once. |
| `validation.*` | A field is wrong: the message and `field` say which. When `create_post` refuses a post, `issues` lists each problem with its platform and field. |

For anything unexplained, `list_events` filtered by `account_id` or `resource_id` shows what the platform answered.

References: [references/tools.md](references/tools.md) (every tool, ids, pagination, response shapes, Automations, webhooks) and [references/platforms.md](references/platforms.md) (what each platform supports).

Referenced files: 2 — file references are metadata, not package contents.