# bundle.social > This file is very large and may be truncated. For an index of this content, please refer to https://info.bundle.social/llms.txt instead. # SECURITY Source: https://info.bundle.social/SECURITY # Security Policy ## Supported Versions bundle.social is a hosted service, so the API and dashboard always run the current version - there are no older deployments to patch. For the client libraries we ship fixes to the latest release of the current major line. | Component | Supported | | - | - | | bundle.social API and dashboard (hosted) | :white_check_mark: current deployment | | `bundlesocial` (Node SDK) 2.x | :white_check_mark: latest release | | `bundlesocial-cli` 1.x, `bundlesocial-mcp` 1.x | :white_check_mark: latest release | | Client libraries, older majors | :x: | Self-hosting is not supported, so pinning an old SDK version does not keep you on an old API. If you are affected by a fix in a client library, upgrade to its latest release. ## Reporting a Vulnerability Please report security issues privately - do not open a public GitHub issue, pull request, or discussion. Reach us through [bundle.social/contact](https://bundle.social/contact) with "security" in the subject, and we will move the report to a private channel with the engineers who own the affected area. A useful report includes what you found, the affected endpoint, page, or package, the steps to reproduce it, and what an attacker could do with it. Proof-of-concept code and request/response captures help a lot. If you need to share something sensitive, say so and we will arrange an encrypted channel rather than having you paste it into a form. ### What to expect * **Acknowledgement** within 3 business days. * **Initial assessment** - whether we can reproduce it and how we are rating it - within 7 business days. * **Progress updates** at least every 7 days while the report is open. * **If accepted**, we fix it and tell you when the fix is live. Timelines depend on severity: critical issues are handled immediately, lower-severity ones ship with regular releases. You will get credit in the [changelog](https://info.bundle.social/changelog) if you want it, and we are happy to stay anonymous if you prefer. * **If declined**, you get an explanation of why - usually out of scope, working as intended, or already known and tracked. ### Scope In scope: the bundle.social API, the dashboard, the hosted connect portal, the official SDK/CLI/MCP packages, and this documentation site. Out of scope: findings in the social platforms we integrate with (report those to Meta, Google, TikTok, X, and so on through their own programs), denial-of-service and volumetric testing, spam or social engineering against our staff or users, missing hardening headers with no demonstrated impact, and automated scanner output without a working proof of concept. ### Ground rules When testing, please use your own organization and your own connected accounts. Do not access, modify, or exfiltrate other customers' data or their social accounts, and do not publish to accounts you do not own. Stop as soon as you have confirmed a vulnerability, and give us a reasonable window to ship a fix before disclosing publicly. Research that follows these rules is welcome, and we will not pursue action over it. # Analytics Source: https://info.bundle.social/api-reference/analytics How analytics work, how we refresh them, how long we keep them, and why some numbers are zero. The full picture. Everything you need to know about analytics before you read the [platform-specific pages](/api-reference/platforms/index). This page covers refresh rates, rate limits, data retention, and why some numbers are zero. For platform-specific metrics and quirks, see each platform's dedicated page. > [!WARNING] > > **Analytics require a paid plan.** The free plan has API access, but not analytics. Every analytics > endpoint returns `403` with `Analytics access is disabled for your subscription tier.` on the free plan, > and nothing is collected in the background either - so upgrading later does not backfill the period you > spent on the free plan. Analytics are included on Pro, Business, and Enterprise. *** ## Analytics Refresh & Rate Limits ### Default Refresh Analytics are refreshed automatically, so you don't need to run your own refresh job for standard updates: * **Account analytics:** every **24 hours**. * **Post analytics**, depending on the post's age: | Post age | Refreshed | | :- | :- | | Up to 2 days | Every 24 hours, or your organization's custom interval | | 2 to 30 days | Every 24 hours (a shorter custom interval doesn't apply) | | Over 30 days | Once a week | Older posts keep being refreshed, just less often, since their numbers barely move. Need fresh numbers for an older post? Use [Force Refresh](#force-refresh). ### Force Refresh You can request analytics to be refreshed immediately by calling the analytics force refresh endpoints. | Target | Endpoint | Body | | :- | :- | :- | | Social account analytics | `POST /api/v1/analytics/social-account/force` | `{ "teamId": "...", "platformType": "INSTAGRAM" }` | | Post analytics | `POST /api/v1/analytics/post/force` | `{ "postId": "...", "platformType": "INSTAGRAM" }` | | Imported post analytics | `POST /api/v1/analytics/post/force` | `{ "importedPostId": "..." }` | However, force refresh requests are rate limited to **6 per social account** and **6 per post** in any rolling 24 hours. You may ask why? To protect US from our greatest and brightest vibe code engineers doing: ```typescript theme={null} while (true) { await bundlesocial.analytics.analyticsForceRefresh({ teamId: team.id, }); } ``` We had such cases. We are not joking. Someone actually did this in production. > [!NOTE] > > **Rate Limits**: Each social account can be force refreshed up to **6 times** in a rolling 24 hours, and each post up to **6 times**. The counters are separate, so refreshing one account doesn't use up another account's or a post's allowance. > > A refresh that fails doesn't count against the limit. If you exceed the limit, the API returns `429 Too Many Requests`. > > Need more? Reach out and we can raise it for your organization, up to **48** per account and per post in 24 hours. Your current allowances are in `GET /api/v1/organization` as `forcedAccountAnalyticsDailyLimit` and `forcedPostAnalyticsDailyLimit` (`null` = the default of 6). An organization can also have manual refreshes turned off (limit `0`): the force endpoints then answer `403` with `Manual account analytics refreshes are disabled for your organization.` (or `post`). ### Custom Refresh Periods By default, analytics are automatically refreshed every **24 hours** (see [Default Refresh](#default-refresh) for how post age changes that). However, we can configure custom refresh periods based on your organization's needs. The shortest possible period is **1 hour**, and for posts it applies only during their first 2 days. **Important**: If you require a higher refresh rate (e.g., every hour for large organizations), there may be additional charges due to increased data costs. We will discuss these costs with you directly to determine the best solution for your use case. ### When Collection Stops For An Account A daily refresh that fails is retried, and what happens next depends on the error: | Error | What we do | Force refresh returns | | :- | :- | :- | | Temporary platform error (5xx, timeout, rate limit) | Try again on the next daily run | `5xx` while the platform keeps failing | | Expired or revoked token | Try again on the next daily run. Reconnect the account if the token is dead | the platform's auth error | | Permanent error (e.g. a missing permission) | Stop collecting for that account | `400` with `Analytics access is disabled for this social account.` | There is no status field for this on the account yet. To spot an account whose collection stopped, check the date of its newest analytics item: if it is older than your refresh period plus a day, force a refresh and read the response. For an account that returns the `400` above, reconnect it (Facebook and Instagram) or contact us with the social account ID. ### Posts Deleted On The Platform When a post is deleted on TikTok, YouTube, Instagram or Threads, its profile post gets `externallyDeletedAt` (the time we noticed) on the next analytics refresh and is no longer refreshed. The analytics collected before stay. This applies to published and imported posts. * **Instagram and Threads** return the same error for a deleted post and for one the account can't access, so a post is marked only when it's also missing from the account's own post list. Very old posts (beyond the account's latest \~500 on Instagram, \~1,000 on Threads) aren't checked. * Facebook and the other platforms don't set `externallyDeletedAt`. * To hear about it as it happens, subscribe to the [`post.externally-deleted`](/api-reference/webhooks#externally-deleted-posts-payload) webhook. It's sent once per post. *** ## Data Retention We retain analytics data for **30 days** from the date of creation. After that, it's gone. Poof. Deleted. If your team needs yearly or long-term history, we recommend fetching and storing the data daily on your end. Build a cron job, pipe it to your database, and sleep well at night. This retention period is fixed and is not extended automatically. Maybe we are evil? > [!WARNING] > > **30 days.** That's it. If you need analytics from 3 months ago and you didn't save them, we can't help you. We told you. Right here. In this doc. That you're reading right now. For the full breakdown of what we retain and for how long (not just analytics), see [Data Retention](/api-reference/data-retention). *** ## Important Note: Data Differences & Zeros > [!NOTE] > > **Data shown in our platform may differ from what you see on the social media platform itself.** This can happen for several reasons: > > * **Processing Delays**: Platforms may take time to process and return analytics data. For example, TikTok can take up to 48 hours for some detailed analytics like audience demographics and splits. > > * **Rolling Window Timing**: When platforms return rolling window data, the exact time window and aggregation method may differ slightly from what's displayed in their native interfaces. > > * **Data Availability**: Some metrics may be available in the platform's native interface but not through their API, or vice versa. APIs and dashboards are built by different teams. At big companies. With different priorities. > > * **Update Frequency**: Analytics are updated based on when we fetch data from each platform, which may not match the real-time updates you see in the platform's own interface. > > * **Zero Values**: **Some metrics return `0` when the platform API doesn't provide that specific data point.** This doesn't mean you have zero engagement - it means the data is not available through the API. Each platform page clearly marks which fields return 0 and why. > > * **No Data vs. Zero (Instagram)**: When Instagram refuses insights for a post, we store **no snapshot** instead of a row of zeros. This happens for posts published before the account switched to a professional (Business/Creator) account, which Meta never serves insights for, and for posts with too few viewers. A forced refresh on such a post returns `400` with Meta's reason. Posts that can never have insights are excluded from future refreshes. *** ## Understanding Analytics This is what we return in the standard analytics schema. ### Rolling Window Analytics show aggregated data over a fixed time period (e.g., last 30 days) that updates as time progresses. Each time you view analytics, you see data for the most recent period. Older data falls out of the window as newer data is added. ### Lifetime Analytics show a snapshot of cumulative totals from when the post or profile was created up to the current moment. These values represent the current state and will continue to grow over time. These values usually only increase, unless the platform removes or recalculates engagement. *** ## Raw Analytics Data In addition to the parsed analytics data described above, raw analytics data is available through dedicated raw endpoints. Raw analytics contain the raw payload we store for the snapshot. Depending on the platform, this can be the original API response, a flat metric object built from platform insights, or a platform payload plus a computed summary. This includes: * Platform-specific metrics that may not be mapped to our standard schema * Additional metadata and context provided by the platform * Detailed breakdowns (e.g., audience demographics, engagement by time period, etc.) * **LinkedIn:** reaction-type breakdowns (our normalized `likes` field is a single aggregate; raw payloads retain per-reaction detail where the API provides it) Raw analytics are useful when you need platform-specific metrics that are not included in the standard analytics format. Raw data structure and fields vary significantly between platforms. ### Raw Endpoints | Target | Endpoint | Query | | :- | :- | :- | | Social account raw analytics | `GET /api/v1/analytics/social-account/raw` | `teamId`, `platformType` | | Post raw analytics | `GET /api/v1/analytics/post/raw` | `postId` + `platformType`, or `importedPostId` | ```http theme={null} GET /api/v1/analytics/social-account/raw?teamId=team_123&platformType=FACEBOOK ``` ```http theme={null} GET /api/v1/analytics/post/raw?postId=post_123&platformType=FACEBOOK ``` ```http theme={null} GET /api/v1/analytics/post/raw?importedPostId=profile_post_123 ``` Raw responses use the same wrapper shape as parsed analytics, but each item includes a platform-specific `raw` object. Social account raw responses return `socialAccount` and `items[]`; post raw responses return `post`, optional `profilePost`, and `items[]`. ```json theme={null} { "socialAccount": { "id": "sa_123", "type": "INSTAGRAM", "teamId": "team_123" }, "items": [ { "id": "raw_123", "socialAccountId": "sa_123", "analyticsId": "analytics_123", "raw": { "platformSpecificPayload": {} }, "forced": false, "createdAt": "2026-04-27T10:00:00.000Z", "updatedAt": "2026-04-27T10:00:00.000Z", "deletedAt": null } ] } ``` For exact raw payload examples, use the platform pages: * [Instagram raw analytics](/api-reference/platforms/instagram#raw-analytics-demographics--audience-data) * [Facebook raw analytics](/api-reference/platforms/facebook#raw-analytics) * [LinkedIn raw analytics](/api-reference/platforms/linkedin#raw-analytics) * [TikTok raw analytics](/api-reference/platforms/tiktok#raw-analytics-demographics--audience-data) * [YouTube raw analytics](/api-reference/platforms/youtube#raw-analytics-demographics--audience-data) * [Snapchat analytics](/api-reference/platforms/snapchat#analytics) * [Threads raw analytics](/api-reference/platforms/threads#raw-analytics) * [Pinterest raw analytics](/api-reference/platforms/pinterest#raw-analytics) * [Reddit raw analytics](/api-reference/platforms/reddit#raw-analytics) * [Mastodon raw analytics](/api-reference/platforms/mastodon#raw-analytics) * [Bluesky raw analytics](/api-reference/platforms/bluesky#raw-analytics) * [Google Business raw analytics](/api-reference/platforms/google-business#raw-analytics) ### Raw Availability By Platform | Platform | Profile raw | Post raw | Typical contents | | :- | :- | :- | :- | | Instagram | Yes | Yes | Account info, daily totals, demographics, media insights | | Facebook | Yes | Yes | Page info, page insights, demographic insights, reaction/video/post insight metrics | | LinkedIn | Yes | Yes | Member/org analytics, share statistics, reaction breakdowns where available | | TikTok | Yes | Yes | Account metrics, audience splits, video watch and source metrics | | YouTube | Yes | Yes | Channel/video statistics, video demographics where available | | Snapchat | Optional | Optional | Public Profile, Story, and Spotlight stats when raw Snapchat analytics is enabled for the organization | | Threads | Yes | Yes | Profile/media insights returned by Threads | | Pinterest | Yes | Yes | User/pin analytics and lifetime metric payloads | | Reddit | Limited | Limited | Listing data and engagement fields returned by Reddit | | Mastodon | Limited | Limited | Account/status payloads with basic engagement | | Bluesky | Limited | Limited | Actor/post payloads and calculated engagement inputs | | Google Business | Yes | No post raw | Location info, daily metrics, computed summary | | Twitter/X | No | No | No raw payloads; analytics are on demand only (see the X page) | | Discord | No | No | Messaging platform; no analytics API | | Slack | No | No | Messaging platform; no analytics API | > [!NOTE] > > Raw data is subject to the same **30-day retention** as parsed analytics. If you need it long-term, fetch and store it yourself. BTW, you are a nerd for reading all of this. *** ## Platform Summary Table A quick reference for what each platform gives us (and what it doesn't). | Platform | Profile Period | Post Period | Key Limitations | | :- | :- | :- | :- | | [Instagram](/api-reference/platforms/instagram) | Rolling (30d) | Lifetime | Views (Unique) returns 0 | | [Facebook](/api-reference/platforms/facebook) | Rolling (30d) | Lifetime | Profile: likes, comments, post count all return 0 | | [LinkedIn (Personal)](/api-reference/platforms/linkedin) | Rolling (30d) | Rolling (30d) | Views, post count, following return 0 | | [LinkedIn (Org)](/api-reference/platforms/linkedin) | Rolling (30d) | Rolling (30d) | Post count, following, post saves return 0; post views only for video posts | | [Twitter/X](/api-reference/platforms/twitter) | On demand | On demand | Forced refresh only, billed from X credits; profile returns followers, following and post count only | | [TikTok](/api-reference/platforms/tiktok) | Rolling (30d) | Lifetime | Post saves return 0 | | [YouTube](/api-reference/platforms/youtube) | Lifetime | Lifetime | Profile likes, following, post shares return 0 | | [Snapchat](/api-reference/platforms/snapchat) | Lifetime | Lifetime | Public Profile required; raw payloads require organization-level enablement | | [Threads](/api-reference/platforms/threads) | Rolling | Lifetime | Following returns 0 | | [Pinterest](/api-reference/platforms/pinterest) | Rolling (30d) | Mixed | Profile comments, post shares return 0 | | [Reddit](/api-reference/platforms/reddit) | N/A | Lifetime | All profile analytics return 0 | | [Mastodon](/api-reference/platforms/mastodon) | Snapshot | Lifetime | Most metrics return 0 - very limited | | [Bluesky](/api-reference/platforms/bluesky) | Snapshot | Lifetime | Most metrics return 0 - impressions are calculated | | [Discord](/api-reference/platforms/discord) | N/A | N/A | No analytics | | [Slack](/api-reference/platforms/slack) | N/A | N/A | No analytics | | [Google Business](/api-reference/platforms/google-business) | Rolling (30d) | N/A | Profile/location raw analytics only; post analytics are not returned | *** ## Available Metrics Reference ### Understanding Return Values * **Available**: The metric is provided by the platform API and returns real data. * **Returns 0**: The metric returns 0 because the platform API doesn't provide this data. This is not a bug. This is the platform being stingy. ### Profile Analytics Metrics | Metric | Description | | :- | :- | | `impressions` | Number of times your profile/content was shown | | `impressionsUnique` | Number of unique users who saw your profile/content | | `views` | Number of times your profile/page was viewed | | `viewsUnique` | Number of unique users who viewed your profile | | `likes` | Total likes/reactions received | | `comments` | Total comments received | | `postCount` | Total number of posts published | | `followers` | Current follower count | | `following` | Current following count | ### Post Analytics Metrics | Metric | Description | | :- | :- | | `impressions` | Number of times the post was shown | | `impressionsUnique` | Number of unique users who saw the post | | `views` | Number of times the post was viewed (for videos, this is play count) | | `viewsUnique` | Number of unique users who viewed the post | | `likes` | Total likes/reactions received | | `dislikes` | Total dislikes (YouTube, Reddit only) | | `comments` | Total comments received | | `shares` | Total shares/reposts | | `saves` | Total saves/bookmarks | *** ## Notes * **Rolling Window** data refreshes to show the most recent period. Each time you check, you see the current window. * **Lifetime** data represents cumulative totals from creation to now. * **Returns 0** means the platform API doesn't provide that data. Not a bug. Each platform page documents exactly which fields return 0. * Some platforms have date restrictions (e.g., Threads requires posts after April 2024). * LinkedIn has significant differences between personal and organization account analytics. * Metrics may vary slightly between platforms due to how each defines and tracks engagement. * All analytics (parsed and raw) are deleted after **30 days**. See [Data Retention](/api-reference/data-retention). # Automations Source: https://info.bundle.social/api-reference/automations Auto-reply to comments and DMs on Instagram, Facebook and TikTok. Keyword triggers, private replies, quick replies, buttons, execution logs and platform menus. > [!WARNING] > > **Turned on per organization, on request.** Automations are part of the paid plans (the Free plan has no run allowance). Access is per platform: one switch covers Instagram and Facebook and also turns on [Direct Messages](/api-reference/direct-messages), a separate one covers TikTok. [Contact us](https://bundle.social/contact) with your **organization ID** (the `id` returned by `GET /api/v1/organization`) and the platforms you need. Until then every endpoint in this section answers `403` with a message that says how to request access, and so does creating a flow for a platform that isn't turned on. > > Once it's on, two things are on you: > > 1. **Reconnect** your Facebook and Instagram accounts with `withMessagingScope: true`, then **subscribe** each one to messages with `POST /api/v1/social-account/messaging/enable`. Accounts connected before the switch receive neither comments nor DMs until you do. See [Before You Start](/api-reference/automations#before-you-start). > 2. **Accept the new webhook events.** Your webhook starts receiving an event for every new comment on the account's posts, including posts published outside bundle.social, and every new DM. Keep your endpoint answering `2xx`, or it gets disabled. See [Webhooks](/api-reference/automations/webhooks). Automations reply for you. Someone comments "LINK" under your reel, and a second later they get a DM with the link. Someone asks "price?" in your inbox, and they get a message with buttons. Nobody on your team had to be awake for it. You describe **what should happen** as a flow (a trigger plus a list of steps), publish it, and we run it on every matching comment or message. ## Try It In The Dashboard Automations are already live in the bundle.social dashboard under **Automations** ([bundle.social/dashboard/general/automations](https://bundle.social/dashboard/general/automations)), so you can see how everything works before writing a line of code. * **Use it as a flow builder.** Click a flow together, and the **API definition** panel next to it shows the exact `definition` JSON this API expects, with the real IDs from your team. Copy it into your `POST /api/v1/automations` or `PATCH` call and you're done. * **Watch it run.** The execution logs show every run and what each step did, the same data as [Testing & Execution Logs](/api-reference/automations/testing-and-logs). * **Ice breakers and the persistent menu** can be set up there too. * It's the same data either way: flows created through the API show up in the dashboard, and the other way around. ## In This Section > [card] [Building Flows](/api-reference/automations/building-flows) > > Triggers, keywords, delays, conditions and message formats. > [card] [Managing Flows](/api-reference/automations/managing-flows) > > Create, publish, pause, archive, delete and copy flows. > [card] [How Flows Behave](/api-reference/automations/how-flows-behave) > > What happens in practice, and the built-in safety limits. Read before you build. > [card] [Testing & Execution Logs](/api-reference/automations/testing-and-logs) > > Test a flow and see why every run did what it did. > [card] [Ice Breakers & Persistent Menu](/api-reference/automations/provider-settings) > > Instagram ice breakers, Messenger menu and Get Started button. > [card] [Automation Webhooks](/api-reference/automations/webhooks) > > `comment.received` and the other events your webhook starts getting. > [card] [Recipes](/api-reference/automations/recipes) > > Copy-paste flows for the most common use cases. > [card] [Direct Messages](/api-reference/direct-messages) > > The inbox API automations are built on. ## All Endpoints All endpoints use your API key in the `x-api-key` header, same as the rest of the API. | Method | Endpoint | What it does | Docs | | :- | :- | :- | :- | | `GET` | `/api/v1/automations` | List flows | [Managing Flows](/api-reference/automations/managing-flows#list-flows) | | `POST` | `/api/v1/automations` | Create a flow (as a draft) | [Managing Flows](/api-reference/automations/managing-flows#create-edit-publish) | | `GET` | `/api/v1/automations/:id` | Get a flow with its draft and published versions | [Managing Flows](/api-reference/automations/managing-flows#the-flow-object) | | `PATCH` | `/api/v1/automations/:id` | Rename, or save a new draft definition | [Managing Flows](/api-reference/automations/managing-flows#create-edit-publish) | | `POST` | `/api/v1/automations/:id/publish` | Validate and go live | [Managing Flows](/api-reference/automations/managing-flows#create-edit-publish) | | `POST` | `/api/v1/automations/:id/pause` | Stop running, keep the config | [Managing Flows](/api-reference/automations/managing-flows#pause-activate-archive-delete) | | `POST` | `/api/v1/automations/:id/activate` | Go live again | [Managing Flows](/api-reference/automations/managing-flows#pause-activate-archive-delete) | | `POST` | `/api/v1/automations/:id/archive` | Retire without deleting | [Managing Flows](/api-reference/automations/managing-flows#pause-activate-archive-delete) | | `DELETE` | `/api/v1/automations/:id` | Delete a flow | [Managing Flows](/api-reference/automations/managing-flows#pause-activate-archive-delete) | | `POST` | `/api/v1/automations/copy` | Copy flows to another team | [Managing Flows](/api-reference/automations/managing-flows#copy-flows-between-teams) | | `POST` | `/api/v1/automations/:id/test` | Run the flow once, right now | [Testing](/api-reference/automations/testing-and-logs#test-a-flow) | | `GET` | `/api/v1/automations/:id/executions` | Execution logs of one flow | [Execution Logs](/api-reference/automations/testing-and-logs#executions) | | `GET` | `/api/v1/automation-executions/:id` | One execution with every step | [Execution Logs](/api-reference/automations/testing-and-logs#executions) | | `GET` | `/api/v1/automation-provider-settings` | List ice breakers / persistent menus | [Provider Settings](/api-reference/automations/provider-settings) | | `PUT` | `/api/v1/automation-provider-settings/:socialAccountId/:type` | Save one | [Provider Settings](/api-reference/automations/provider-settings#save-then-sync) | | `POST` | `/api/v1/automation-provider-settings/:id/sync` | Push it to the platform | [Provider Settings](/api-reference/automations/provider-settings#save-then-sync) | | `POST` | `/api/v1/automation-rich-messages/conversations/:conversationId` | Send a rich message by hand | [Building Flows](/api-reference/automations/building-flows#send-a-rich-message-by-hand) | *** ## Which Tool Do I Need? Not everything is an automation. Pick the right tool first: | You want to... | Use | | :- | :- | | Reply to a comment **publicly**, by hand | [Comments API](/api-reference/comments#replying-to-imported-comments): `POST /api/v1/comment` with `fetchedParentCommentId` | | Hide, delete or like a comment (where the platform allows it), by hand | [Comments API](/api-reference/comments#actions-on-fetched-comments): `POST /api/v1/comment/import/comments/:commentId/action` | | Answer a comment **with a DM**, by hand | [Private replies](/api-reference/direct-messages/private-replies): `POST /api/v1/conversations/private-reply` | | Read and answer DMs, by hand | [Direct Messages](/api-reference/direct-messages) | | Do any of the above **automatically** | Automations (this section) | All of them work on the same comments and conversations. A comment your flow answered can still be moderated by hand, and a conversation started by an automation shows up in the DM inbox. *** ## Supported Platforms | Platform | What automations can do | | :- | :- | | `INSTAGRAM` | React to comments, DMs and button taps. Send DMs, private replies and public comment replies. Manage ice breakers. | | `FACEBOOK` | The same comment and DM features as Instagram, plus liking comments. Instead of ice breakers, manage the Messenger persistent menu and Get Started button. | | `TIKTOK` | **Comments only.** React to new comments, reply publicly, like the comment. | > [!NOTE] > > TikTok has no DM automations. TikTok flows work on comments and nothing else. *** ## Plans And Limits Automations are a paid-plan feature. Each connected account has a monthly budget of **automation runs**: | Plan | Runs per account / month | | :- | :- | | Free | 0 | | Pro | 200 | | Business | 1,000 | * One run = one flow reacting to one comment or message, no matter how many steps it has. * Runs that stop at a condition, get skipped by a safety limit (see [Safety Limits](/api-reference/automations/how-flows-behave#safety-limits)), or get canceled **don't count**. * Runs that fail **do** count, and so do [test runs](/api-reference/automations/testing-and-logs#test-a-flow), since they really send messages. * DMs sent by automations also count toward the account's [monthly message quota](/api-reference/direct-messages#plans-and-limits). * When the budget runs out, new runs are recorded as `SKIPPED` with the code `AUTOMATION_MONTHLY_LIMIT_REACHED`. Quotas reset on the 1st of every month (UTC). * Check how much each account has used with `GET /api/v1/organization/usage/messages` (`automationRunsUsed` and `automationRunsLimit`). See [Check Monthly Message And Automation Usage](/api-reference/rate-limits#check-monthly-message-and-automation-usage). Need more? [Contact us](https://bundle.social/contact). *** ## Before You Start Once automations are turned on for your organization: 1. **Reconnect your Facebook and Instagram accounts** with `withMessagingScope: true`. This covers accounts that were already connected before the switch. Until they are reconnected they have no messaging permissions, and we don't receive their new comments either, so no flow on them can ever fire. 2. **Subscribe each account to messages** with `POST /api/v1/social-account/messaging/enable`. This registers it for Meta's message webhooks. It's needed for any flow that reacts to DMs or button taps, or sends DMs or private replies. A flow that only replies publicly or likes comments works without it. Both steps are two API calls, see [Direct Messages → Setup](/api-reference/direct-messages/setup). 3. **TikTok** accounts need comment management permissions. A regular TikTok connection has them. If publishing a flow complains about permissions, reconnect the account. Also give every TikTok flow a 5-10 second [delay](/api-reference/automations/building-flows#delays). 4. **Comment flows** cover one post or all of them. Set `postId` to a post published through bundle.social to cover that post. Leave `postId` out to cover every post on the account, including posts published outside bundle.social (directly in the Instagram, Facebook or TikTok app). 5. **Your webhook endpoint accepts the new events** (see [Webhooks](/api-reference/automations/webhooks)). If an account is missing permissions, publishing the flow fails with a clear message such as `Instagram account must be reconnected with messaging permissions`. ### Where The IDs Come From | ID | Where to get it | | :- | :- | | `teamId`, `socialAccountId` | `GET /api/v1/team/:id` returns the team with its `socialAccounts[]`. `messaging/enable` also returns the `socialAccountId`. | | `postId` | The `id` you got back from `POST /api/v1/post`. It's the bundle.social post, not the Instagram or TikTok post ID. Optional: leave it out for a flow on all posts. | | `conversationId` | `GET /api/v1/conversations`, or any `conversation.*` [webhook](/api-reference/automations/webhooks) | | `fetchedCommentId` | The `comment.id` of a `comment.received` [webhook](/api-reference/automations/webhooks), or `GET /api/v1/comment/import/comments` | | `senderExternalIds` | A person's platform ID: `externalParticipantId` on a conversation, or `authorExternalId` on a comment | | `uploadId` | `POST /api/v1/upload` ([Upload Content](/api-reference/upload-content)) | *** ## How It Works A **flow** is one trigger plus up to 100 steps: ``` Trigger: someone comments "link" on post_123 (Instagram) → Step 1: send them a private reply with the link → Step 2: reply publicly "Check your DMs 👀" ``` 1. **Trigger.** An event arrives: a new comment, a new DM, or a tap on a button or quick reply. We look for published, active flows whose trigger matches it. 2. **Run.** Each matching flow gets its own **execution** (a run). If the trigger has a delay, the run waits for it. 3. **Steps.** Steps run top to bottom. A `CONDITION` step that doesn't match stops the run right there. 4. **Log.** Every run and every step is recorded, with inputs, outputs and errors. That's your debugging tool, see [Executions](/api-reference/automations/testing-and-logs#executions). ### Drafts And Publishing Flows are versioned, so you can edit safely while the old version keeps running. Changes are saved as a **draft**, and **nothing you edit goes live until you publish it**. Details in [Managing Flows](/api-reference/automations/managing-flows#lifecycle). | Flow status | Meaning | | :- | :- | | `DRAFT` | Never published. Doesn't run. | | `ACTIVE` | Live. Runs on every matching event. | | `PAUSED` | Temporarily off. Keeps its configuration, runs waiting on a delay are canceled. | | `ARCHIVED` | Retired. Doesn't run until you activate or publish it again. | *** ## Capabilities By Platform ### Triggers | Trigger | Instagram | Facebook | TikTok | Fires when | | :- | :-: | :-: | :-: | :- | | `COMMENT_CREATED` | ✅ | ✅ | ✅ | Someone comments on the post in `postId`, or on any post of the account if `postId` is left out | | `DM_RECEIVED` | ✅ | ✅ | - | Someone sends a DM to the account | | `QUICK_REPLY_CLICKED` | ✅ | ✅ | - | Someone taps one of your quick replies | | `BUTTON_CLICKED` | ✅ | ✅ | - | Someone taps a `POSTBACK` button, an ice breaker, or a persistent menu item | ### Steps | Step | Instagram | Facebook | TikTok | What it does | | :- | :-: | :-: | :-: | :- | | `CONDITION` | ✅ | ✅ | ✅ | Continue only if all rules match | | `SEND_MESSAGE` | ✅ | ✅ | - | Send a DM (text, media, buttons, quick replies, carousel) | | `SEND_PRIVATE_REPLY` | ✅ | ✅ | - | Answer a comment with a DM | | `SEND_PUBLIC_COMMENT_REPLY` | ✅ | ✅ | ✅ | Reply to the comment publicly | | `LIKE_COMMENT` | - | ✅ | ✅ | Like the comment | | `ARCHIVE_CONVERSATION` | ✅ | ✅ | - | Move the conversation to archive | | `OPEN_CONVERSATION` | ✅ | ✅ | - | Move the conversation back to the active inbox | ### Which Steps Fit Which Trigger Some combinations make no sense (or Meta forbids them), so publishing rejects them: * `SEND_PRIVATE_REPLY`, `SEND_PUBLIC_COMMENT_REPLY` and `LIKE_COMMENT` need a `COMMENT_CREATED` trigger. There's no comment to reply to otherwise. * `SEND_MESSAGE` needs a `DM_RECEIVED`, `QUICK_REPLY_CLICKED` or `BUTTON_CLICKED` trigger. To DM a commenter, use `SEND_PRIVATE_REPLY`. Meta doesn't allow any other message until they answer it. * `ARCHIVE_CONVERSATION` / `OPEN_CONVERSATION` need a DM or click trigger, or a `SEND_PRIVATE_REPLY` earlier in the flow (that's what creates the conversation). * Every flow needs at least one step that actually does something (not only conditions). *** ## Quick FAQ ### "My flow is ACTIVE but nothing happens." Check in this order: 1. Was the account reconnected **after** automations were turned on for your organization? Accounts connected earlier don't send us comments or DMs. See [Before You Start](/api-reference/automations#before-you-start). 2. Is it a comment flow with a `postId`? That post must be published through bundle.social on the same account. Also, when a post has its own flow that matches the comment, flows on all posts don't run for it (see [Comment Flows](/api-reference/automations/how-flows-behave#comment-flows)). 3. Did you edit it after publishing? Edits are drafts until you publish again. 4. Do the keywords really match? They match whole words: `"link"` won't match "links". 5. Look at the executions. If runs are there as `SKIPPED`, `error.code` tells you why. No error means a condition stopped the run, `output.skippedAtStepId` says which one. 6. No executions at all for a DM flow? Make sure the account is subscribed with `messaging/enable` ([Direct Messages → Setup](/api-reference/direct-messages/setup)). 7. Still no executions? While automations are paused on our side (for example during a platform incident), incoming events don't create runs at all, so nothing shows up in the logs. ### "Can one comment or message trigger several flows?" Yes, every matching flow runs (up to 25), and each one sends its own reply. If that's not what you want, make the keywords not overlap. ### "Why did someone get two replies to one message?" Two flows matched the same message, usually a catch-all flow plus a keyword flow. See [DM Flows](/api-reference/automations/how-flows-behave#dm-flows). ### "Why did my automation ignore someone's second message?" The loop brake: in DMs, one automated answer per person per 60 seconds, 6 per hour. The skipped run is in the executions with `AUTOMATION_CONVERSATION_COOLDOWN`. Use quick replies or buttons for back-and-forth conversations, since taps skip this brake. ### "My TikTok flow sometimes fails on the reply or like step." Most likely TikTok wasn't ready for the comment yet when the step ran. Set `actionDelaySeconds` to 5-10 on the flow and publish again. See [Delays](/api-reference/automations/building-flows#delays). ### "Can one flow cover all my posts?" Yes. Leave `postId` out of the `COMMENT_CREATED` trigger and the flow reacts to comments on every post of the account, including posts published outside bundle.social. You can still add flows for single posts: when one of them matches a comment, it runs instead of the all-posts flows. See [Comment Flows](/api-reference/automations/how-flows-behave#comment-flows). ### "Can I stop automations for one conversation when a human takes over?" Not per conversation. Pausing a flow stops it for everyone. Build your flows around keywords and buttons so they only answer what they're meant to. ### "How do I reply to a comment by hand?" With the [Comments API](/api-reference/comments#replying-to-imported-comments), or with a [private reply](/api-reference/direct-messages/private-replies) if you want to answer in DMs. See [Which Tool Do I Need?](/api-reference/automations#which-tool-do-i-need). ### "Can I DM everyone who commented, not just reply?" That's exactly what `SEND_PRIVATE_REPLY` is. One private reply per comment, text only, within 7 days of the comment. Those are Meta's rules, not ours. ### "Does it work on posts I didn't publish through bundle.social?" Not for comment triggers right now. DM triggers work for any conversation. ### "Is there a visual flow builder?" Yes, in the bundle.social dashboard, see [Try It In The Dashboard](#try-it-in-the-dashboard). It shows the API definition of the flow you're building, so you can build there and copy the JSON into your code. # Building Flows Source: https://info.bundle.social/api-reference/automations/building-flows Write a flow definition: triggers, keywords, delays, conditions, steps and message formats. A flow definition is one `trigger` plus up to 100 `steps`. It's what you send as `definition` when you [create or update a flow](/api-reference/automations/managing-flows#create-edit-publish). Which triggers and steps each platform supports is in [Capabilities By Platform](/api-reference/automations#capabilities-by-platform). ```json theme={null} { "trigger": { "type": "COMMENT_CREATED", "platform": "INSTAGRAM", "socialAccountId": "sa_789", "postId": "post_123", "keywords": ["link", "info"], "matchMode": "ANY", "caseSensitive": false, "actionDelaySeconds": 0 }, "steps": [ { "type": "SEND_PRIVATE_REPLY", "message": { "text": "Here you go: https://yourshop.com/drop" } }, { "type": "SEND_PUBLIC_COMMENT_REPLY", "text": "Sent you a DM 👀" } ] } ``` ## Trigger Fields | Field | Used by | Description | | :- | :- | :- | | `type` | all | Trigger type, see [Capabilities By Platform](/api-reference/automations#capabilities-by-platform) | | `platform` | all | `INSTAGRAM`, `FACEBOOK` or `TIKTOK` | | `socialAccountId` | all | The account the flow listens on | | `postId` | `COMMENT_CREATED` | **Optional.** A post published through bundle.social on that account, to cover that one post. Leave it out (or send `null`) to cover every post on the account, including posts published outside bundle.social. An empty string counts as left out. Which flow wins when both kinds exist: [Comment Flows](/api-reference/automations/how-flows-behave#comment-flows). **Must be left out** for DM and click triggers: a DM or click flow with a `postId` publishes fine but never fires. | | `keywords` | comments, DMs | Up to 100, each up to 200 characters. Empty = every comment / message matches. | | `matchMode` | comments, DMs | `ANY` (default): one keyword is enough. `ALL`: every keyword must appear. | | `caseSensitive` | comments, DMs | Default `false` | | `payloads` | clicks | Up to 100, each up to 1,000 characters. Only taps with one of these payloads match. Empty = any tap. | | `senderExternalIds` | all | Optional. Only react to these people (platform user IDs). Great for testing on your own profile before going public. | | `actionDelaySeconds` | all | Wait before running, 0 to 86,400 (24h). Default 0. **Recommended on TikTok: 5-10.** See [Delays](/api-reference/automations/building-flows#delays). | **Keyword matching** is whole-word and forgiving: * `"link"` matches "send me the **link** pls" but not "**link**edin". * Phrases work: `"free sample"` matches "can I get a free sample?". * Extra spaces are always ignored, case is ignored unless `caseSensitive: true`, and Unicode is normalized, so accented and non-Latin keywords behave. * Emoji and punctuation keywords match anywhere: `"🔥"` matches "🔥🔥🔥". Keywords go on comment and DM triggers, `payloads` go on click triggers. Mixing them up is rejected. > [!TIP] > > **Quick replies win over DMs.** When someone taps a quick reply, flows with a `QUICK_REPLY_CLICKED` trigger run first. Your `DM_RECEIVED` flows only see the tap if no quick-reply flow matched it, so one tap never gets two answers. ## Delays `actionDelaySeconds` holds the run back before its first step. The clock starts when the comment or message reaches us. Three good reasons to set it: 1. **TikTok needs a moment. We recommend 5-10 seconds on every TikTok flow.** Right after TikTok tells us about a new comment, TikTok itself isn't always ready to accept a reply or a like on it yet. How long that takes depends on how busy TikTok's servers are: most of the time the reply works instantly, sometimes it needs a few extra seconds. Without a delay, the reply or like step can fail in those moments, and failed runs are not retried. A short delay costs you nothing and makes TikTok flows reliable. 2. **Feeling human.** An answer that lands 0.3 seconds after a DM doesn't feel like a person wrote it. A few seconds on DM flows reads more naturally. 3. **Anything else you want.** Reply a few minutes later so it looks like a person answered, or follow up with a DM an hour after someone asked. Up to 24 hours is possible. Good to know: * While it waits, the run is `QUEUED` in the [executions](/api-reference/automations/testing-and-logs#executions). * Pausing, archiving or deleting the flow cancels the runs that are still waiting (`CANCELED`). > [!WARNING] > > **Watch the 24-hour window with delays on DMs.** Meta only allows DMs within 24 hours of the person's last message. A `SEND_MESSAGE` flow with a very long delay can wake up to a closed window and fail. Keep DM delays well below 24 hours. ## Condition Steps A condition lets one flow handle several cases, or filter what the trigger let through: ```json theme={null} { "type": "CONDITION", "conditions": [ { "field": "TEXT", "operator": "CONTAINS", "value": "refund" } ] } ``` | Field | Reads | | :- | :- | | `TEXT` | The comment or message text | | `PAYLOAD` | The payload of the tapped button or quick reply | | `PLATFORM` | `INSTAGRAM`, `FACEBOOK` or `TIKTOK` | | `SENDER_ID` | The platform user ID of the person | | Operator | Matches when | | :- | :- | | `CONTAINS` | The value appears anywhere in the field | | `EQUALS` | The field equals the value exactly | | `MATCHES_ANY` | The field equals one of a comma-separated list: `"value": "PRO,BUSINESS"` | Comparisons ignore case unless `caseSensitive: true`. **All** rules in one condition step must match. If they don't, the run stops there as `SKIPPED` (and doesn't use your quota). ## Step IDs Steps can have an optional `id`. Without one we generate it from the type and position (`dm-1`, `private-reply-2`, ...). IDs must be unique within a flow. Set your own if you want stable names in the execution logs. *** ## Messages In Automations `SEND_MESSAGE` accepts a rich message: | Field | Limit | | :- | :- | | `text` | 1,000 characters (Instagram: 1,000 **bytes**, emoji and non-Latin letters count more) | | `attachments` | 1, `IMAGE` or `VIDEO`, as `{ "uploadId": "...", "type": "IMAGE" }`, file up to 24 MB | | `quickReplies` | up to 13, label up to 20 characters | | `buttons` | up to 3. `POSTBACK` and `URL` everywhere, `PHONE` on Facebook only | | `carousel` | up to 10 cards, `title` / `subtitle` up to 80 characters, `imageUploadId`, up to 3 buttons per card | Media comes from your [uploads](/api-reference/upload-content): upload once with `POST /api/v1/upload`, then reference the `uploadId`. Carousel images must be image uploads. Every quick reply, button and carousel card needs an `id` (your choice, up to 36 characters, e.g. `"btn-pricing"`). Same rules as in [Direct Messages](/api-reference/direct-messages/sending-messages#message-content): buttons and quick replies need `text`, never both in one message, and a carousel travels alone. `SEND_PRIVATE_REPLY` is **text only** (Meta allows exactly one private message per comment). `SEND_PUBLIC_COMMENT_REPLY` takes plain `text`: up to 1,000 characters on Facebook, 1,000 bytes on Instagram and **150 characters on TikTok**. *** ## Send A Rich Message By Hand **Endpoint:** `POST /api/v1/automation-rich-messages/conversations/:conversationId` Sends a message into a conversation with the **same format as a `SEND_MESSAGE` step**, uploads and all. Useful when an agent takes over from an automation and wants to send the same product carousel. ```json theme={null} { "teamId": "team_123", "message": { "text": "Here's our bestseller 👇", "attachments": [{ "uploadId": "upload_456", "type": "IMAGE" }] } } ``` Returns `{ conversationId, messageId, externalMessageId }`. The 24-hour rule and your message quota apply, same as [sending a normal DM](/api-reference/direct-messages/sending-messages#send-a-message). # How Flows Behave Source: https://info.bundle.social/api-reference/automations/how-flows-behave What happens in practice: comment and DM flow behavior, failures, and built-in safety limits. Read this before you build. Most "why did my automation do that?" questions are answered here. ## Comment Flows * **One post or all posts.** A comment trigger with a `postId` covers that one post, published through bundle.social. The easiest moment to create it is right when you schedule the post: the flow can be published before the post goes live and is armed the moment it does. A comment trigger without `postId` covers every post on the account, including posts published outside bundle.social and posts that are already live. * **A post's own flows go first.** For each comment we first check the flows set on that post. If at least one of them matches (keywords included), only those run. If none matches, or the post has no flow of its own, the all-posts flows run. One comment never runs both kinds. Comments on posts published outside bundle.social can only match all-posts flows. * **Facebook visitor posts are left out.** Comments under posts that other people wrote on your Page's timeline don't trigger flows. * **Replies are comments too.** A reply inside a comment thread fires the trigger like any other comment. That includes people answering "thanks!" under your automated public reply. Without keywords, the flow answers those too, so use keywords. * **Every comment gets its own answer.** On Instagram and Facebook there's no per-person cooldown for comment flows. If the same person comments "LINK" three times, they get three answers. Meta allows exactly one private reply per comment, so each comment gets at most one. * **Hidden comments never trigger anything** (TikTok). * **Your own comments never trigger anything.** Comments posted through bundle.social (including your flows' public replies) or by the account itself are ignored. * **No comment import needed.** New comments arrive in real time. They trigger your flows, arrive as `comment.received` [webhooks](/api-reference/automations/webhooks), and show up in `GET /api/v1/comment/import/comments` without you running an import. ## DM Flows * **Every matching flow answers.** Flows have no priorities. If a catch-all flow (no keywords) and a keyword flow both match the same message, the person gets **two** replies. Either run one catch-all, or keep keywords from overlapping. * **Conditions have no "else".** A `CONDITION` step either lets the run continue or stops it. For "if X do A, otherwise do B", build separate flows. * **One automated answer per minute per person.** If someone sends two messages within 60 seconds, only the first one gets an automated answer, and nobody gets more than 6 an hour. Taps on quick replies and buttons skip this limit, so button-driven conversations can move fast. The replies they trigger still count toward the budget, though: a message someone *types* right after a tap-driven reply can go unanswered. The skipped runs show `AUTOMATION_CONVERSATION_COOLDOWN` or `AUTOMATION_CONVERSATION_HOURLY_LIMIT`. * **Button taps only trigger `BUTTON_CLICKED` flows.** A quick reply tap that no `QUICK_REPLY_CLICKED` flow picks up falls through to your `DM_RECEIVED` flows like a typed message. A `POSTBACK` button, ice breaker or menu tap with no matching `BUTTON_CLICKED` flow gets no automated answer. * **URL buttons don't trigger anything.** Platforms don't report when someone opens a link. Use a `POSTBACK` button if the tap should lead somewhere. * **There's no per-conversation pause.** When someone from your team takes over a chat, your automations keep answering whatever their triggers match. Pausing a flow stops it for everyone. Archiving a conversation doesn't stop it either, since a new message reopens the conversation. If humans answer in the same inbox, build your flows around keywords and buttons rather than a catch-all. * **Your team's messages never trigger flows.** Messages sent through bundle.social, or typed in the Instagram or Messenger app, are ignored. * **Story replies and story mentions are DMs.** On Instagram, a reply to your story fires `DM_RECEIVED` like any other message, so keywords match what the person wrote ("reply LINK to my story" works). A story mention has no text, so only flows without keywords pick it up. Each run's `input` tells them apart: `isStoryReply`, `storyId`, `storyLinkStickerUrl` and `isStoryMention` (see [Execution Logs](/api-reference/automations/testing-and-logs)). ## When Something Fails * A failing step stops the run. Steps that already ran are not undone: a DM that went out stays sent. * Failed runs are **not retried** automatically. Platform rate limits are the only exception: the run waits and continues where it stopped, without re-sending finished steps, for up to an hour. After that it fails with `AUTOMATION_EXECUTION_EXPIRED`. * You can't re-run an old execution. Fix the flow and the next event will use it, or check it with a [test run](/api-reference/automations/testing-and-logs#test-a-flow). * If the account's [monthly message quota](/api-reference/direct-messages#plans-and-limits) is used up, `SEND_MESSAGE` and `SEND_PRIVATE_REPLY` steps fail with `Monthly message limit reached`. Public replies and likes keep working. The same two steps also fail if messaging isn't enabled for the account, or while sending is paused on our side. * A whole run can take at most 60 seconds (`AUTOMATION_EXECUTION_TIMEOUT`). * Uploads in rich messages (a missing upload, wrong type, or a file over 24 MB) are checked when the step runs, not when you publish. Test the flow once before relying on it. *** ## Safety Limits Automations answering other automations in a loop is how accounts get flagged. We have a few brakes built in so that doesn't happen to you: * **Loop brake for DMs.** In Instagram and Facebook DMs, each person gets at most **1 automated reply per 60 seconds** and **6 per hour**, shared across all your flows. Messages that arrive while the brake is on get no automated answer. Button and quick reply taps skip this brake, since they're answers to your own messages, but the replies they trigger count toward the budget. A quick reply tap that no `QUICK_REPLY_CLICKED` flow picks up and that falls through to a `DM_RECEIVED` flow is treated like a typed message. The brake is checked per incoming message, so if several flows match the same message, they all answer it (see [How Flows Behave In Practice](/api-reference/automations/how-flows-behave#dm-flows)). * **Loop brake for TikTok comments.** The same budget applies per TikTok commenter, because TikTok hides bursts of similar replies as spam. Skipped runs show `AUTOMATION_COMMENTER_COOLDOWN` or `AUTOMATION_COMMENTER_HOURLY_LIMIT`. Instagram and Facebook **comment** flows have no per-person brake: every comment gets its answer. * **No self-triggering.** Messages and comments sent by bundle.social, or by the account itself, never trigger your flows. * **One team per page.** If the same Page or Instagram account is connected in several of your teams, only the first team's flow answers a comment. The rest are skipped with `AUTOMATION_SHARED_PAGE_CLAIMED`. The same applies to DMs: if another team answered that person in the last 60 seconds, your run is skipped with that code, taps included. * **No double sends.** Each event runs each flow at most once, even if the platform delivers the same webhook twice. * **At most 25 flows** react to a single event. * **Rate limits are handled for you.** If a platform tells us to slow down, the run goes back to `QUEUED` and retries automatically for up to an hour. # Managing Flows Source: https://info.bundle.social/api-reference/automations/managing-flows Create, edit, publish, pause, archive, delete and copy automation flows. Everything you do with a flow after writing its [definition](/api-reference/automations/building-flows): create it, save changes, publish, pause, retire, copy. ## Lifecycle Flows are versioned, so you can edit safely while the old version keeps running. 1. **Create** with `POST /api/v1/automations`. The flow starts as a `DRAFT` and never runs. 2. **Save changes** with `PATCH /api/v1/automations/:id` and a `definition`. This saves a **draft**. If the flow is already live, the live version keeps running untouched. 3. **Publish** with `POST /api/v1/automations/:id/publish`. We validate the draft, make it the live version and set the flow to `ACTIVE`. **Nothing you edit goes live until you publish it.** > [!TIP] > > **Recommended rhythm: `PATCH` the definition, then publish with an empty body.** Publish also accepts a `definition` in its body, but that skips the draft. [Test runs](/api-reference/automations/testing-and-logs#test-a-flow) always use the saved draft when there is one, so publishing a definition that was never saved as a draft leaves your tests running an older version. | Flow status | Meaning | How you get there | | :- | :- | :- | | `DRAFT` | Never published. Doesn't run. | Create | | `ACTIVE` | Live. Runs on every matching event. | Publish, or activate a paused flow | | `PAUSED` | Temporarily off. Keeps its configuration. | Pause | | `ARCHIVED` | Retired. Doesn't run until you activate or publish it again. | Archive | ## The Flow Object Every flow endpoint except `DELETE` returns the flow with its current versions: ```json theme={null} { "id": "flow_abc", "teamId": "team_123", "name": "Reel drop - comment LINK to get the link", "status": "ACTIVE", "platformScope": "INSTAGRAM", "createdAt": "2026-09-20T10:00:00.000Z", "updatedAt": "2026-09-26T09:00:00.000Z", "publishedVersion": { "id": "ver_3", "version": 3, "status": "PUBLISHED", "publishedAt": "2026-09-26T09:00:00.000Z", "definition": { "trigger": { "...": "..." }, "steps": [] } }, "draftVersion": { "id": "ver_1", "version": 1, "status": "DRAFT", "definition": { "trigger": { "...": "..." }, "steps": [] } } } ``` * `publishedVersion` is what runs. It's missing until the first publish. * `draftVersion` is your latest saved draft. It **stays** after publishing, so right after a publish both usually carry the same definition. The next `PATCH` overwrites the draft in place, so the draft keeps its `version` number while each publish creates a new, higher one. * Every run in the [execution logs](/api-reference/automations/testing-and-logs#executions) records the `flowVersionId` it used, so you can tell which version answered. ## List Flows **Endpoint:** `GET /api/v1/automations?teamId=team_123` Optional filters: `status`, `platformScope`, `socialAccountId` (matches flows whose **published** version listens on that account, so drafts don't show up here), plus `offset` and `limit` (default 10). Returns `{ items, total }`, newest first. Archived flows are included, filter with `status` if you don't want them. **Endpoint:** `GET /api/v1/automations/:id` returns a single flow. ## Create, Edit, Publish `platformScope` is the flow's platform label: `INSTAGRAM`, `FACEBOOK`, `TIKTOK`, or `BOTH` (Instagram or Facebook). It has to fit the trigger's `platform`. A flow has exactly one trigger, so it listens on one account. Want the same automation on Instagram and Facebook? Create two flows. The flow `name` can be up to 120 characters. ```ts theme={null} const API = "https://api.bundle.social/api/v1"; const headers = { "Content-Type": "application/json", "x-api-key": process.env.BUNDLE_API_KEY, }; // 1. Create (you can pass the definition right away, or add it later with PATCH) const flow = await fetch(`${API}/automations`, { method: "POST", headers, body: JSON.stringify({ teamId: "team_123", name: "Reel drop - comment LINK to get the link", platformScope: "INSTAGRAM", definition: { trigger: { type: "COMMENT_CREATED", platform: "INSTAGRAM", socialAccountId: "sa_789", postId: "post_123", keywords: ["link"], }, steps: [ { type: "SEND_PRIVATE_REPLY", message: { text: "Here's the link 🔗 https://yourshop.com/drop" } }, { type: "SEND_PUBLIC_COMMENT_REPLY", text: "Check your DMs 👀" }, ], }, }), }).then((r) => r.json()); // 2. Publish - validates everything and makes it live const res = await fetch(`${API}/automations/${flow.id}/publish`, { method: "POST", headers, body: JSON.stringify({}), }); if (!res.ok) { // 400: schema problems come in `issues`, the rest in `message` separated by "; " const err = await res.json(); console.error(err.issues ?? err.message); } // 3. Later: change the reply text, then publish again await fetch(`${API}/automations/${flow.id}`, { method: "PATCH", headers, body: JSON.stringify({ definition: { /* full definition with your changes */ } }), }); await fetch(`${API}/automations/${flow.id}/publish`, { method: "POST", headers, body: JSON.stringify({}) }); ``` `PATCH` accepts `name`, `platformScope` and `definition`, all optional. A `definition` always replaces the whole draft, so send the full trigger and all steps, not just the part you changed. Validation runs on create and on every `PATCH` that carries a `definition`, and again on publish. It happens in two stages: * **Shape** (field types, lengths, counts, duplicate step ids): a `400` with an `issues` array, one entry per problem with its `path`. * **Everything else** (accounts, permissions, the post, whether steps fit the trigger), once the shape is valid: all problems come back in one `400` whose `message` joins them with `; `, so you can fix them in one go. A flow is also rejected with `403` while automations for its platform are not turned on for your organization (TikTok has its own switch, Instagram and Facebook share one). Publishing a flow that has no draft and no `definition` in the body returns `400`. ## Pause, Activate, Archive, Delete | Endpoint | What happens | | :- | :- | | `POST /api/v1/automations/:id/pause` | The flow stops reacting to new events. Runs still waiting on a [delay](/api-reference/automations/building-flows#delays) are canceled. | | `POST /api/v1/automations/:id/activate` | A paused (or archived) flow goes live again with its published version. Returns `400` if the flow was never published. | | `POST /api/v1/automations/:id/archive` | Retired. Stops running, waiting runs are canceled. Still listed and readable, and it comes back if you activate or publish it again. | | `DELETE /api/v1/automations/:id` | Gone. Waiting runs are canceled and the flow answers `404` from now on. Past runs stay readable by their ID via `GET /api/v1/automation-executions/:id` until they're [30 days old](/api-reference/data-retention). | None of these take a body. ## Copy Flows Between Teams **Endpoint:** `POST /api/v1/automations/copy` ```json theme={null} { "sourceTeamId": "team_123", "targetTeamId": "team_456", "flowId": "flow_abc" } ``` Leave out `flowId` to copy every flow of the source team (archived ones included). Copies land as **drafts** in the target team, with the account-specific bits cleared (`socialAccountId`, `postId`, `senderExternalIds`). A comment flow that pointed at one post becomes a flow on all posts, and its name gets the suffix ` (copy, all posts)` so you can spot it. Set a `postId` again if it should stay on one post. Point them at the new team's accounts with `PATCH`, then publish. Perfect for agencies rolling out the same automations to many clients. Create and copy answer `201`. Copy returns `{ items, total, skipped }`: the new flows, plus how many source flows were left out because their platform isn't turned on in the source or target organization (for example TikTok flows when the target only has Instagram and Facebook). Copying one flow with `flowId` answers `403` in that case instead. Source and target team must be different. `GET /api/v1/automations` also leaves out flows whose platform isn't turned on for your organization. # Ice Breakers & Persistent Menu Source: https://info.bundle.social/api-reference/automations/provider-settings Manage Instagram ice breakers and the Facebook Messenger persistent menu and Get Started button. Some conversation UI lives on the platform itself, not in a message. We manage two of those for you: | Type | Platform | What it is | | :- | :- | :- | | `INSTAGRAM_ICE_BREAKERS` | Instagram | Up to 4 suggested questions shown to people who open a new chat with you | | `FACEBOOK_PERSISTENT_MENU` | Facebook | The always-visible Messenger menu (up to 3 items) and the Get Started button | A tap on an ice breaker, menu item or Get Started sends its `payload`, which you catch with a `BUTTON_CLICKED` flow. That's how "tap *Pricing* → get the price list" works. Every Facebook persistent menu comes with a Get Started button. Its payload is `GET_STARTED` unless you set `getStartedPayload`. A `BUTTON_CLICKED` flow with `"payloads": ["GET_STARTED"]` makes a nice welcome message. ## Save, Then Sync Saving and pushing to the platform are two separate calls, so you can prepare changes safely. **1. Save:** `PUT /api/v1/automation-provider-settings/:socialAccountId/:type` `:type` is `INSTAGRAM_ICE_BREAKERS` or `FACEBOOK_PERSISTENT_MENU`, and `platform` in the body has to match it. Saving only stores the config and sets the status to `DRAFT` (or `DISABLED`, if you send `"status": "DISABLED"`). Whatever you synced before stays live on the platform until you sync again. ```json theme={null} { "teamId": "team_123", "platform": "INSTAGRAM", "config": { "iceBreakers": [ { "question": "What are your prices?", "payload": "ICE_PRICING" }, { "question": "Do you ship internationally?", "payload": "ICE_SHIPPING" }, { "question": "Talk to a human", "payload": "ICE_HUMAN" } ] } } ``` For the Facebook persistent menu: ```json theme={null} { "teamId": "team_123", "platform": "FACEBOOK", "config": { "getStartedPayload": "GET_STARTED", "composerInputDisabled": false, "items": [ { "type": "POSTBACK", "title": "Pricing", "payload": "MENU_PRICING" }, { "type": "POSTBACK", "title": "Book a demo", "payload": "MENU_DEMO" }, { "type": "URL", "title": "Visit website", "url": "https://yourshop.com" } ] } } ``` `composerInputDisabled: true` hides the text box, so people can only use the menu. Use it carefully. **2. Sync:** `POST /api/v1/automation-provider-settings/:id/sync` This pushes the saved config to Instagram or Facebook. If the platform rejects it, the call returns an error with the platform's message and the setting keeps its previous status. Otherwise the response tells you how it went: | Status | Meaning | | :- | :- | | `DRAFT` | Saved, not pushed yet | | `SYNCED` | Live on the platform. `lastSyncedAt` says when. | | `SYNC_FAILED` | We couldn't push it, for example because the account is missing its access token. `lastSyncError.message` says why. Reconnect the account if needed and sync again. | | `DISABLED` | Marked for removal. After a sync, it's removed from the platform. | To **remove** ice breakers or the menu, save the setting with `"status": "DISABLED"` and sync it. Removing the Facebook menu also removes the Get Started button. Reconnected an account? Sync again to be safe. List what you have with `GET /api/v1/automation-provider-settings?teamId=team_123` (filters: `platform`, `socialAccountId`, `type`, `status`, plus `offset` and `limit`). The list returns `{ items, total }`, most recently updated first. Every other endpoint here returns the setting: ```json theme={null} { "id": "ps_1", "teamId": "team_123", "platform": "INSTAGRAM", "socialAccountId": "sa_789", "type": "INSTAGRAM_ICE_BREAKERS", "status": "SYNCED", "config": { "iceBreakers": [{ "question": "What are your prices?", "payload": "ICE_PRICING" }] }, "lastSyncedAt": "2026-09-26T09:00:00.000Z", "lastSyncError": null, "socialAccount": { "id": "sa_789", "type": "INSTAGRAM", "username": "mybrand" }, "createdAt": "2026-09-20T10:00:00.000Z", "updatedAt": "2026-09-26T09:00:00.000Z" } ``` # Recipes Source: https://info.bundle.social/api-reference/automations/recipes Copy-paste flows: comment-to-DM, DM with quick replies, TikTok replies, conditions and monitoring. Ready-to-use flows for the most common cases. Most are complete `POST /api/v1/automations` bodies, the shorter ones show just the `definition`. Swap in your own `teamId`, `socialAccountId` and `postId`, create the flow, then [publish](/api-reference/automations/managing-flows#create-edit-publish). Need something that isn't here? Build it in the [dashboard](/api-reference/automations#try-it-in-the-dashboard) and copy the **API definition** it shows. ## Comment "LINK" → Get A DM The classic Instagram growth funnel. Someone comments a keyword, they get the link privately and a public reply that makes others comment too. ```json theme={null} { "teamId": "team_123", "name": "Reel - LINK funnel", "platformScope": "INSTAGRAM", "definition": { "trigger": { "type": "COMMENT_CREATED", "platform": "INSTAGRAM", "socialAccountId": "sa_789", "postId": "post_123", "keywords": ["link", "info", "send"] }, "steps": [ { "type": "SEND_PRIVATE_REPLY", "message": { "text": "Hey! Here's the link you asked for 🔗 https://yourshop.com/drop" } }, { "type": "SEND_PUBLIC_COMMENT_REPLY", "text": "Sent 📩 check your DMs!" } ] } } ``` When the person answers the private reply, the conversation opens up and your `DM_RECEIVED` flows can take it from there. ## DM Flow With Quick Replies Two flows. The first answers "price" with a question, the second answers the tap. ```json theme={null} { "teamId": "team_123", "name": "Pricing - ask", "platformScope": "INSTAGRAM", "definition": { "trigger": { "type": "DM_RECEIVED", "platform": "INSTAGRAM", "socialAccountId": "sa_789", "keywords": ["price", "pricing", "how much"], "actionDelaySeconds": 3 }, "steps": [ { "type": "SEND_MESSAGE", "message": { "text": "Happy to help! Which plan are you looking at?", "quickReplies": [ { "id": "qr-starter", "label": "Starter", "payload": "PLAN_STARTER" }, { "id": "qr-pro", "label": "Pro", "payload": "PLAN_PRO" }, { "id": "qr-human", "label": "Talk to a human", "payload": "HUMAN" } ] } } ] } } ``` ```json theme={null} { "teamId": "team_123", "name": "Pricing - Pro answer", "platformScope": "INSTAGRAM", "definition": { "trigger": { "type": "QUICK_REPLY_CLICKED", "platform": "INSTAGRAM", "socialAccountId": "sa_789", "payloads": ["PLAN_PRO"] }, "steps": [ { "type": "SEND_MESSAGE", "message": { "text": "Pro is 49 EUR/month and includes everything in Starter plus analytics.", "buttons": [ { "id": "btn-buy", "type": "URL", "label": "Get Pro", "url": "https://yourshop.com/pro" }, { "id": "btn-done", "type": "POSTBACK", "label": "That's all, thanks", "payload": "DONE" } ] } } ] } } ``` And one more to tidy up when they tap "That's all, thanks": ```json theme={null} { "trigger": { "type": "BUTTON_CLICKED", "platform": "INSTAGRAM", "socialAccountId": "sa_789", "payloads": ["DONE"] }, "steps": [ { "type": "SEND_MESSAGE", "message": { "text": "Anytime! 👋" } }, { "type": "ARCHIVE_CONVERSATION" } ] } ``` ## TikTok: Reply And Like ```json theme={null} { "teamId": "team_123", "name": "TikTok - drop comments", "platformScope": "TIKTOK", "definition": { "trigger": { "type": "COMMENT_CREATED", "platform": "TIKTOK", "socialAccountId": "sa_tiktok_1", "postId": "post_456", "keywords": ["when", "drop", "release"], "actionDelaySeconds": 8 }, "steps": [ { "type": "SEND_PUBLIC_COMMENT_REPLY", "text": "Dropping Friday 6pm CET 🔥 link in bio" }, { "type": "LIKE_COMMENT" } ] } } ``` Remember the 150-character limit for TikTok replies. The 8-second delay is there on purpose: TikTok sometimes needs a moment before a new comment can be replied to or liked (see [Delays](/api-reference/automations/building-flows#delays)). ## Route By Keyword With A Condition One Facebook flow that listens to every DM, but only answers refund questions: ```json theme={null} { "trigger": { "type": "DM_RECEIVED", "platform": "FACEBOOK", "socialAccountId": "sa_fb_1" }, "steps": [ { "type": "CONDITION", "conditions": [{ "field": "TEXT", "operator": "CONTAINS", "value": "refund" }] }, { "type": "SEND_MESSAGE", "message": { "text": "Sorry to hear that! You can request a refund here, it takes 2 minutes.", "buttons": [ { "id": "btn-refund", "type": "URL", "label": "Request refund", "url": "https://yourshop.com/refund" }, { "id": "btn-call", "type": "PHONE", "label": "Call us", "phoneNumber": "+48123456789" } ] } } ] } ``` (`PHONE` buttons are fine here because it's Facebook. On Instagram use a `URL` button.) ## Monitor Your Automations From Your Backend There are no automation-specific webhooks. Messages sent by automations are normal messages, so they arrive as [`conversation.message.created`](/api-reference/direct-messages/webhooks) events like everything else. For run-level monitoring, poll the executions: ```ts theme={null} const res = await fetch( `https://api.bundle.social/api/v1/automations/${flowId}/executions?teamId=team_123&status=FAILED&limit=50`, { headers: { "x-api-key": process.env.BUNDLE_API_KEY } }, ); const { items } = await res.json(); for (const execution of items) { const failedStep = execution.steps?.find((step) => step.status === "FAILED"); console.warn(execution.id, failedStep?.stepId, failedStep?.error?.message ?? execution.error?.message); } ``` # Testing & Execution Logs Source: https://info.bundle.social/api-reference/automations/testing-and-logs Test a flow on a real conversation or comment, and read the log of every run. Two tools for finding out what your flows do: a **test run** fires a flow on demand, and the **execution log** records every run, triggered or tested. ## Test A Flow **Endpoint:** `POST /api/v1/automations/:id/test` Runs the flow **once, synchronously**, and returns the finished execution. It uses the draft if there is one, otherwise the published version, so you can test changes before publishing them. A test skips the trigger entirely: keywords, `payloads`, `senderExternalIds`, the delay and the loop brake are not applied. It goes straight to the steps (conditions still run). Use it to check what the steps do, and a real comment or DM to check what triggers them. ```json theme={null} { "input": { "conversationId": "conv_abc", "text": "how much is the pro plan?" } } ``` Give it the context the steps need: * DM and click flows: `conversationId` of a real conversation in the team (plus `text` or `payload` if your conditions look at them), * comment flows: `fetchedCommentId` of a real comment (from the [Comments API](/api-reference/comments)), * flows with `SENDER_ID` conditions: pass the sender's ID in `input` yourself, a test doesn't take it from the conversation. > [!WARNING] > > **Tests are real.** Steps really send messages to the real person in that conversation, and the run counts toward your monthly quota. Test on a conversation with your own second account. Before anything runs, a test returns: * `400` if the flow has neither a draft nor a published version, or its definition doesn't pass validation (for example missing permissions), * `404` if the flow, conversation or comment isn't found in the flow's team, * `403` if the account's monthly run budget is used up, * `429` if the platform is rate-limiting the account right now (try again shortly). Once the steps run, the result comes back as `200` with the execution, even when it didn't go well: check its `status` and `error`. In the execution, `input.type` is `MANUAL_TEST`. *** ## Executions Every run is logged as an **execution**. This is where you answer "why didn't my automation reply?". Logs are kept for [30 days](/api-reference/data-retention) after the run. **Endpoints:** * `GET /api/v1/automations/:id/executions?teamId=team_123` - runs of one flow, newest first * `GET /api/v1/automation-executions/:id` - one run, with every step Filters for the list: `status`, `platform`, `socialAccountId`, `conversationId`, `fetchedCommentId`, `flowVersionId`, `triggerId`. Paginate with `limit` (max 1000) and either `offset` or `cursor` (pass back `nextCursor`), same as [conversations](/api-reference/direct-messages/conversations#pagination). ```json theme={null} { "id": "exec_1", "teamId": "team_123", "flowId": "flow_abc", "flowVersionId": "ver_3", "triggerId": "trg_1", "platform": "INSTAGRAM", "socialAccountId": "sa_789", "fetchedCommentId": "fetched_1", "conversationId": null, "conversationMessageId": null, "senderExternalId": "1789000000000000", "currentStepId": "public-reply-2", "status": "COMPLETED", "input": { "type": "COMMENT_CREATED", "platform": "INSTAGRAM", "postId": "post_123", "text": "LINK please!" }, "output": { "completedAtStepId": "public-reply-2" }, "error": null, "startedAt": "2026-09-26T09:30:01.000Z", "completedAt": "2026-09-26T09:30:02.400Z", "createdAt": "2026-09-26T09:30:00.500Z", "updatedAt": "2026-09-26T09:30:02.400Z", "steps": [ { "id": "stepexec_1", "stepId": "private-reply-1", "status": "COMPLETED", "attemptCount": 1, "output": { "conversationId": "conv_abc", "messageId": "msg_42" }, "error": null, "startedAt": "2026-09-26T09:30:01.100Z", "completedAt": "2026-09-26T09:30:01.900Z" }, { "id": "stepexec_2", "stepId": "public-reply-2", "status": "COMPLETED", "attemptCount": 1, "error": null, "startedAt": "2026-09-26T09:30:01.950Z", "completedAt": "2026-09-26T09:30:02.400Z" } ] } ``` The execution also carries the related `flow`, `flowVersion`, `conversation`, `conversationMessage`, `fetchedComment` and `socialAccount` objects, so you rarely need a second request. ### Execution Status | Status | Meaning | | :- | :- | | `QUEUED` | Waiting to run (delay, or a platform rate limit) | | `RUNNING` | Steps are running | | `COMPLETED` | All steps done | | `SKIPPED` | Stopped on purpose. A condition didn't match (then `error` is empty and `output.skippedAtStepId` names the condition), or a limit kicked in (then `error.code` says which). | | `FAILED` | A step failed. The failing step has the details in its `error`. | | `CANCELED` | The flow was paused, archived or deleted while the run was still waiting | Each step has its own status: `PENDING`, `RUNNING`, `COMPLETED`, `FAILED` or `SKIPPED`. ### Error Codes Worth Knowing | `error.code` | Status | Meaning | | :- | :- | :- | | `AUTOMATION_MONTHLY_LIMIT_REACHED` | `SKIPPED` | Monthly run budget for this account is used up | | `AUTOMATION_CONVERSATION_COOLDOWN` | `SKIPPED` | DMs: this person got an automated reply less than 60 seconds ago | | `AUTOMATION_CONVERSATION_HOURLY_LIMIT` | `SKIPPED` | DMs: this person already got 6 automated replies in the last hour | | `AUTOMATION_COMMENTER_COOLDOWN` | `SKIPPED` | TikTok comments: this commenter got an automated reply less than 60 seconds ago | | `AUTOMATION_COMMENTER_HOURLY_LIMIT` | `SKIPPED` | TikTok comments: this commenter already got 6 automated replies in the last hour | | `AUTOMATION_SHARED_PAGE_CLAIMED` | `SKIPPED` | Another team with the same page connected already answered this comment or conversation | | `AUTOMATION_EXECUTION_DISABLED` | `SKIPPED` | Automations were briefly paused on our side (for example during a platform incident). Mostly seen on test runs: events that arrive during a pause don't create runs at all. | | `AUTOMATIONS_DISABLED` | `SKIPPED` | Automations were switched off for your organization before the run started | | `AUTOMATION_EXECUTION_EXPIRED` | `FAILED` | The run couldn't finish within an hour of its scheduled time (usually a long platform rate limit) | | `AUTOMATION_EXECUTION_TIMEOUT` | `FAILED` | The run took longer than 60 seconds | | `AUTOMATION_EXECUTION_STALE` | `FAILED` | The run was interrupted and didn't finish. Check which steps completed before acting on it. | Failed steps carry a readable `message`. Some come from the platform (for example, Meta rejecting a message), others from our own checks before sending (for example, a Facebook private reply to a comment older than 7 days, messaging not enabled for the account, or the monthly message limit). # Automation Webhooks Source: https://info.bundle.social/api-reference/automations/webhooks The comment.received event and the other notifications your webhook starts getting. As soon as the feature is on, your [webhook](/api-reference/webhooks) starts receiving notifications for new activity. If your webhook has no event filter, you get them automatically: | Event | When it fires | | :- | :- | | `comment.received` | Someone else commented on one of the account's posts on Instagram, Facebook or TikTok, whether it was published through bundle.social or directly on the platform. TikTok comments arrive once we've flipped the TikTok switch for you. | | `conversation.created`, `conversation.message.created`, ... | New DMs and conversation changes, see [Direct Messages → Webhooks](/api-reference/direct-messages/webhooks) | `comment.received` fires for every such comment (comments by the account itself and your automated replies are left out), whether or not a flow reacts to it, so you can also use it to build a live comments feed. `data.comment` has the same shape as items from the [Comments API](/api-reference/comments) (on posts published outside bundle.social, `postId` is `null` both there and in `data`, and `comment.importedPostId` is set instead; use it as `importedPostId` in the [Comments API](/api-reference/comments)), and its `id` is exactly the `fetchedCommentId` you use for [private replies](/api-reference/direct-messages/private-replies) and [test runs](/api-reference/automations/testing-and-logs#test-a-flow). ```json theme={null} { "type": "comment.received", "data": { "comment": { "id": "fetched_1", "platform": "INSTAGRAM", "postId": "post_123", "socialAccountId": "sa_789", "externalId": "18001234567890", "externalParentId": null, "externalPostId": "17900000000000000", "text": "LINK please!", "authorName": "janedoe", "authorExternalId": "1789000000000000", "authorAvatarUrl": "https://...", "likesCount": 0, "repliesCount": 0, "publishedAt": "2026-09-26T09:30:00.000Z" }, "postId": "post_123", "teamId": "team_123", "organizationId": "org_123", "socialAccountId": "sa_789", "platform": "INSTAGRAM" } } ``` > [!WARNING] > > **Your endpoint has to keep up.** New comments and DMs can mean a lot of events. Answer each one with a `2xx` within 15 seconds, **including event types you don't handle**, and do the heavy work asynchronously. If your endpoint keeps failing and goes **7 days without a single successful delivery**, we disable it automatically. You'll get an email and a dashboard notification, and you then have to re-enable it (or set up a new one) in the [Webhooks dashboard](https://bundle.social/dashboard/organization/webhooks). Events sent while it was disabled are not replayed. More in [Webhooks](/api-reference/webhooks). # Bulk Post from CSV Source: https://info.bundle.social/api-reference/bulk-posts-csv Create many posts at once by uploading a CSV file. Async processing with per-row results. Got 200 posts to schedule? Upload a CSV instead of creating every post with a separate `POST /post` request. Each row in the CSV becomes one post. Multiple platforms per row, multiple teams, media referenced by URL - one bad row won't block the rest. ## How it works This is an **asynchronous** job, same pattern as [Import Post History](/api-reference/import-posts). 1. **Upload:** You send us a CSV file. 2. **Wait:** We process each row in the background. 3. **Poll:** You check if we're done. 4. **Results:** You get per-row success/failure details. *** ## Step 1: Upload the CSV **Endpoint:** `POST /api/v1/post-csv-import` ```bash theme={null} curl -X POST "https://api.bundle.social/api/v1/post-csv-import" \ -H "x-api-key: YOUR_KEY" \ -F "file=@./posts.csv" ``` The file must be `.csv` and under **100 MB**. **Response** (`201`): ```json theme={null} { "id": "import_abc123", "teamId": "team_456", "organizationId": "org_789", "status": "PENDING", "fileName": "posts.csv", "totalRows": 200, "processedRows": 0, "successRows": 0, "failedRows": 0, "error": null, "rateLimitResetAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-03-31T12:00:00.000Z", "updatedAt": "2026-03-31T12:00:00.000Z" } ``` > [!NOTE] > > Every row in the CSV must include a **`teamId`**, and all referenced teams must belong to the same organization that owns your API key. *** ## Step 2: Poll Progress You have two options: lightweight status or full import details. ### Status (lightweight) **Endpoint:** `GET /api/v1/post-csv-import/{importId}/status` ```bash theme={null} curl "https://api.bundle.social/api/v1/post-csv-import/import_abc123/status" \ -H "x-api-key: YOUR_KEY" ``` ```json theme={null} { "id": "import_abc123", "status": "PROCESSING", "totalRows": 200, "processedRows": 87, "successRows": 85, "failedRows": 2, "error": null, "startedAt": "2026-03-31T12:00:01.000Z", "completedAt": null, "updatedAt": "2026-03-31T12:00:45.000Z" } ``` ### Full import details **Endpoint:** `GET /api/v1/post-csv-import/{importId}` Returns the full import object (same shape as the `POST` response). ### Import history **Endpoint:** `GET /api/v1/post-csv-import` | Parameter | Type | Default | Description | | :- | :- | :- | :- | | `offset` | number | `0` | Skip this many records | | `limit` | number | `20` | How many to return, up to 1000 | Returns `{ items, total }`, newest first. *** ## Step 3: Row Results Once the import finishes (or while it's running), you can inspect individual rows. **Endpoint:** `GET /api/v1/post-csv-import/{importId}/rows` | Parameter | Type | Default | Description | | :- | :- | :- | :- | | `status` | string | - | Filter by `SUCCESS` or `FAILED` | | `offset` | number | `0` | Skip this many rows | | `limit` | number | `50` | How many to return, up to 1000 | ```bash theme={null} curl "https://api.bundle.social/api/v1/post-csv-import/import_abc123/rows?status=FAILED" \ -H "x-api-key: YOUR_KEY" ``` ```json theme={null} { "items": [ { "id": "row_001", "importId": "import_abc123", "rowNumber": 14, "status": "FAILED", "postId": null, "rawRow": { "teamId": "team_456", "postDate": "2026-04-05T10:00:00Z", "socialAccountTypes": "INSTAGRAM,TIKTOK", "text": "Hello world!" }, "normalizedPayload": null, "error": "Team not found or does not belong to your organization", "createdAt": "2026-03-31T12:00:12.000Z" } ], "total": 2 } ``` Successful rows include the `postId` so you can track the created post: ```json theme={null} { "rowNumber": 1, "status": "SUCCESS", "postId": "post_xyz789", "error": null } ``` *** ## Import Statuses | Status | Meaning | | :- | :- | | `PENDING` | Queued, processing hasn't started yet. | | `PROCESSING` | We're working through the rows. | | `COMPLETED` | All rows processed successfully. | | `COMPLETED_WITH_ERRORS` | Done, but at least one row failed. | | `FAILED` | The entire import failed (e.g. invalid file). | | `RATE_LIMITED` | Paused due to platform rate limits. | *** ## CSV Format Each row is one post. Column names map to post fields: | Column | Required | Description | | :- | :- | :- | | `teamId` | Yes | Which team this post belongs to | | `title` | Yes | Internal post title shown in bundle.social | | `postDate` | Yes | ISO 8601 date-time with timezone, for example `2026-04-05T10:00:00Z`. A `SCHEDULED` row more than 10 minutes in the past is rejected with `Scheduled date cannot be more than 10 minutes in the past`, before its media is downloaded. | | `status` | Yes | `DRAFT` or `SCHEDULED` | | `socialAccountTypes` | Yes | Comma-separated platforms (e.g. `INSTAGRAM,TIKTOK,LINKEDIN`) | | `text` | - | Post body text | | `*MediaUrls` | - | Platform-specific media URLs (e.g. `instagramMediaUrls`, `tiktokMediaUrls`) | Media is referenced by **URL** - we download and process it for you. No need to upload files first with `/upload`. Use `#` to separate multiple media URLs or list-like values inside one cell: ```csv theme={null} instagramMediaUrls https://cdn.example.com/1.jpg#https://cdn.example.com/2.jpg ``` ### Platform Media URL Columns | Platform | Column | | :- | :- | | Facebook | `facebookMediaUrls` | | Instagram | `instagramMediaUrls` | | TikTok | `tiktokMediaUrls` | | YouTube | `youtubeMediaUrls` | | LinkedIn | `linkedinMediaUrls` | | Pinterest | `pinterestMediaUrls` | | Reddit | `redditMediaUrls` | | Threads | `threadsMediaUrls` | | Twitter / X | `twitterMediaUrls` | | Mastodon | `mastodonMediaUrls` | | Bluesky | `blueskyMediaUrls` | | Discord | `discordMediaUrls` | | Slack | `slackMediaUrls` | | Google Business | `googleBusinessMediaUrls` | | Snapchat | `snapchatMediaUrls` | ### Common Platform Columns | Platform | Columns | | :- | :- | | Facebook | `facebookType`, `facebookText`, `facebookLink`, `facebookThumbnail`, `facebookMediaTitle`, `facebookNativeScheduleTime` | | Instagram | `instagramType`, `instagramText`, `instagramThumbnailOffset`, `instagramThumbnail`, `instagramShareToFeed`, `instagramCollaborators`, `instagramAutoFitImage`, `instagramAutoCropImage`, `instagramTagged`, `instagramCarouselItems`, `instagramLocationId`, `instagramTrialParamsGraduationStrategy`, `instagramMusicSoundId`, `instagramMusicSoundVolume`, `instagramVideoOriginalSoundVolume` | | TikTok | `tiktokType`, `tiktokText`, `tiktokThumbnail`, `tiktokPrivacy`, `tiktokIsBrandContent`, `tiktokIsOrganicBrandContent`, `tiktokDisableComments`, `tiktokDisableDuet`, `tiktokDisableStitch`, `tiktokThumbnailOffset`, `tiktokIsAiGenerated`, `tiktokAutoAddMusic`, `tiktokAutoScale`, `tiktokUploadToDraft`, `tiktokPhotoCoverIndex`, `tiktokMusicSoundId`, `tiktokMusicSoundVolume`, `tiktokMusicSoundStart`, `tiktokMusicSoundEnd`, `tiktokVideoOriginalSoundVolume` | | YouTube | `youtubeType`, `youtubeTitle`, `youtubeDescription`, `youtubeThumbnail`, `youtubePrivacy`, `youtubeMadeForKids`, `youtubeContainsSyntheticMedia`, `youtubeHasPaidProductPlacement` | | LinkedIn | `linkedinText`, `linkedinLink`, `linkedinThumbnail`, `linkedinMediaTitle`, `linkedinPrivacy`, `linkedinHideFromFeed`, `linkedinDisableReshare` | | Pinterest | `pinterestBoardName`, `pinterestTitle`, `pinterestDescription`, `pinterestLink`, `pinterestThumbnail`, `pinterestAltText`, `pinterestNote`, `pinterestDominantColor` | | Reddit | `redditSubreddit`, `redditText`, `redditDescription`, `redditLink`, `redditNsfw`, `redditFlairId` | | Threads | `threadsText` | | Twitter / X | `twitterText`, `twitterReplySettings` | | Mastodon | `mastodonText`, `mastodonPrivacy`, `mastodonThumbnail`, `mastodonSpoiler` | | Bluesky | `blueskyText`, `blueskyTags`, `blueskyLabels`, `blueskyQuoteUri`, `blueskyExternalUrl`, `blueskyExternalTitle`, `blueskyExternalDescription`, `blueskyThumbnail`, `blueskyVideoAlt` | | Discord | `discordChannelId`, `discordText`, `discordUsername`, `discordAvatarUrl` | | Slack | `slackChannelId`, `slackText`, `slackUsername`, `slackAvatarUrl` | | Google Business | `googleBusinessText`, `googleBusinessTopicType`, `googleBusinessLanguageCode`, `googleBusinessCallToActionType`, `googleBusinessCallToActionUrl`, `googleBusinessEventTitle`, `googleBusinessEventStartDate`, `googleBusinessEventEndDate`, `googleBusinessOfferCouponCode`, `googleBusinessOfferRedeemOnlineUrl`, `googleBusinessOfferTermsConditions`, `googleBusinessAlertType` | | Snapchat | `snapchatType`, `snapchatDescription`, `snapchatLocale`, `snapchatSkipSaveToProfile` | Boolean columns must be `TRUE` or `FALSE`. Enum-like columns are case-insensitive in practice because we normalize them to uppercase before validation. > [!TIP] > > Download a CSV template from the bundle.social dashboard under the **Bulk Post** section to see all available columns and example values. *** ## Handling Rate Limits If the import status goes to `RATE_LIMITED`, don't panic. We hit a platform's posting cap. * The import pauses automatically. * Check `rateLimitResetAt` for when it can resume. * We retry automatically - just keep polling. This works the same as [Import Post History](/api-reference/import-posts) rate limiting. *** ## See also * [Import Post History](/api-reference/import-posts) - same async pattern, but for pulling existing posts from platforms. * [Media Upload](/api-reference/upload-content) - if you prefer uploading media separately before creating posts. * [Rate Limits](/api-reference/rate-limits) - posting limits per platform and plan. # CLI Source: https://info.bundle.social/api-reference/cli Post to 14+ social platforms from your shell, CI, cron or an AI agent. `bundlesocial-cli` is a thin, scriptable wrapper over the [bundle.social SDK](/api-reference/sdk). It prints **JSON to stdout by default** (one object per command) and human status to stderr - easy for scripts and AI agents to parse. > [card] [npm: bundlesocial-cli](https://www.npmjs.com/package/bundlesocial-cli) > > `npx bundlesocial-cli --help` > [card] [OpenClaw / agent skill](https://www.npmjs.com/package/bundlesocial-cli) > > `npx skills add bundleglobal/bundlesocial-cli` ## Install ```bash theme={null} npx bundlesocial-cli --help # one-off npm install -g bundlesocial-cli # global → `bundle-social` ``` Requires Node.js 20+. ## Authenticate Create an API key in the [dashboard](https://bundle.social/dashboard/organization/api-keys), then: ```bash theme={null} export BUNDLESOCIAL_API_KEY="sk_live_..." # optional, if your org has more than one team: export BUNDLESOCIAL_TEAM_ID="team_..." # optional, for self-hosted/staging: export BUNDLESOCIAL_API_URL="https://api.bundle.social" bundle-social doctor # sanity-check the setup ``` Every env var also has a flag: `--api-key`, `--team-id`, `--api-url` (work before or after the command). ## Commands Run `bundle-social --help` for the full option list of any command. The CLI covers the whole bundle.social API surface (the platform-specific edit/delete-after-publish helpers live under `integrations:trigger`). **Posts** | Command | What it does | | - | - | | `posts:create` | Publish a post immediately (or `--draft`). | | `posts:schedule` | Schedule a post for a future ISO-8601 `--date`. | | `posts:update ` | Update a post - only the fields you pass change. | | `posts:list` | List recent posts with filters. | | `posts:get ` / `posts:delete ` / `posts:retry ` | Fetch / delete / re-attempt a post. | | `posts:get-by-reference-key ` | Fetch a post by the `--reference-key` you set on it instead of its bundle.social id. | | `posts:reconnect-candidates` / `posts:reconnect` | List posts that lost their social account after a disconnect, and reattach them to a newly connected account. | | `posts:import` … | Import post history from a connected account: `posts:import`, `posts:imports`, `posts:import:get `, `posts:import:posts`, `posts:import:delete-posts`, `posts:import:retry `. | | `posts:csv` … | Bulk-schedule from a CSV: `posts:csv --file `, `posts:csv:list`, `posts:csv:get `, `posts:csv:status `, `posts:csv:rows `. | **Comments** | Command | What it does | | - | - | | `comments:create` | Comment on a post; repeat `-c` for a chain of replies (X-style thread via comments). `--imported-post-id` comments on an imported post, `--fetched-parent-comment-id` replies to an imported comment. | | `comments:list` / `comments:get ` / `comments:update ` / `comments:delete ` | List / fetch / update / delete comments. | | `comments:retry ` | Re-attempt a comment that ended in `ERROR`. | | `comments:import` … | Pull existing comments for a post: `comments:import`, `comments:imports`, `comments:import:get `, `comments:import:comments`. | | `comments:import:action ` | Moderate an imported comment - `--action DELETE\|HIDE\|UNHIDE\|LIKE\|UNLIKE\|APPROVE\|REJECT`. | **Media** | Command | What it does | | - | - | | `media:upload ` | Upload an image/video/document; returns the upload object. | | `media:upload-large ` | Chunked upload for large files (>\~90 MB). | | `media:list` / `media:get ` / `media:delete ` / `media:delete-many` | List / fetch / delete uploads. | **Integrations (social accounts)** | Command | What it does | | - | - | | `integrations:list` | List connected social accounts (ids, platform types, channels). | | `integrations:tools` / `integrations:trigger ` | List & call the read-only platform helpers - subreddit flairs/requirements, YouTube categories/playlists/regions, LinkedIn mentions, Instagram locations/audio/business discovery, Google Business categories, TikTok trending music. | | `integrations:connect` / `integrations:disconnect` | Start an OAuth connect flow / disconnect an account. | | `integrations:portal-link` | Create a hosted portal link for end users to connect accounts. | | `integrations:set-channel` / `integrations:unset-channel` / `integrations:refresh-channels` | Pick / clear / refresh the channel (page, board, server channel) for an account. | | `integrations:check` / `integrations:refresh-profile` / `integrations:by-type ` / `integrations:copy` / `integrations:to-delete` | Connection check, profile refresh, lookup by platform, copy between teams, list accounts pending deletion. | **Analytics** | Command | What it does | | - | - | | `analytics:post [id]` | Engagement metrics for one post - yours, or an imported one via `--imported-post-id` (`--raw` for the unprocessed payload). | | `analytics:account` | Latest analytics for a connected account by `-p ` (`--raw` for the unprocessed payload). | | `analytics:bulk` | Engagement metrics for several posts (`--post-id` repeatable). | | `analytics:refresh` | Force a fresh pull - `--post-id` for a post, otherwise `-p ` for an account. | | `analytics:summary` | Org-level usage quotas + latest per-integration analytics snapshot. | **Teams, organization & diagnostics** | Command | What it does | | - | - | | `teams:list` / `teams:get ` / `teams:create` / `teams:update ` / `teams:delete ` | Manage teams. | | `org:get` / `org:usage` | Your organization, and posts/comments/uploads/imports usage & quotas. | | `org:daily-limits` | A connected account's daily post/comment allowance for a given day. | | `doctor` | Diagnostic JSON: API key, connectivity, organization API access, team selection, integrations, quotas. | ### Examples ```bash theme={null} # text post to X and Bluesky bundle-social posts:create -c "We just shipped dark mode 🌙" -i x -i bluesky # TikTok video with the required privacy level bundle-social posts:create -c "BTS" -i tiktok -m ./demo.mp4 \ --platform-settings '{"TIKTOK":{"privacy":"PUBLIC_TO_EVERYONE"}}' # schedule a thread: post, then add replies as comments POST=$(bundle-social posts:create -i linkedin -c "1/ A thread 🧵") ID=$(printf '%s' "$POST" | jq -r .id) bundle-social comments:create --post-id "$ID" -c "2/ more…" -c "3/ even more…" # Reddit, done right: check requirements + flairs first bundle-social integrations:trigger reddit:requirements --data '{"subreddit":"r/test"}' bundle-social integrations:trigger reddit:flairs --data '{"subreddit":"r/test"}' bundle-social posts:create --data '{"REDDIT":{"sr":"r/test","text":"Title","flairId":"","uploadIds":[]}}' ``` The per-platform fields you can put under `--platform-settings` / `--data` are documented in [Platform parameters](/api-reference/platform-parameters). ## Output contract (for scripts & agents) * **stdout** = exactly one JSON value per command (or a table with `--pretty`). Pipe it to `jq`. * **stderr** = human progress + `--pretty` error lines. Never parse stderr. * On error: exit code `1` and `{ "error": { "code", "message", "details"? } }` on stdout. > [!NOTE] > > The CLI ships with a `SKILL.md` (OpenClaw / agent skill), a `PROVIDER_SETTINGS.md` (exhaustive per-platform field reference) and an `examples/` directory of ready-to-run `data` JSON templates and shell recipes - see the [repo](https://github.com/bundleglobal/bundlesocial-cli). Also see: [MCP server](/api-reference/mcp) · [SDK](/api-reference/sdk) · [n8n](/api-reference/n8n) · [Examples](/api-reference/examples). # Force refresh post analytics Source: https://info.bundle.social/api-reference/client/analytics/force-refresh-post-analytics https://api.bundle.social/swagger-json post /api/v1/analytics/post/force Trigger an immediate fetch of fresh analytics for a single post instead of waiting for the scheduled refresh. Use sparingly, as it consumes platform rate limits. # Force refresh social account analytics Source: https://info.bundle.social/api-reference/client/analytics/force-refresh-social-account-analytics https://api.bundle.social/swagger-json post /api/v1/analytics/social-account/force Trigger an immediate fetch of fresh social account analytics from the platform instead of waiting for the scheduled refresh. Use sparingly, as it consumes platform rate limits. # Get Bulk Post Analytics Source: https://info.bundle.social/api-reference/client/analytics/get-bulk-post-analytics https://api.bundle.social/swagger-json get /api/v1/analytics/post/bulk Retrieve analytics for multiple posts in a single request. Maximum 60 posts per request, paginated with 20 per page. # Get Post Analytics Source: https://info.bundle.social/api-reference/client/analytics/get-post-analytics https://api.bundle.social/swagger-json get /api/v1/analytics/post Retrieve normalized engagement metrics such as likes, comments, shares, and views for a single published post. Metric names are unified across platforms for easier reporting. # Get Post Analytics Raw Source: https://info.bundle.social/api-reference/client/analytics/get-post-analytics-raw https://api.bundle.social/swagger-json get /api/v1/analytics/post/raw Retrieve post analytics exactly as returned by the social platform, without bundle.social's normalization. Use this when you need a platform-specific metric that the normalized response does not expose. # Get Social Account Analytics Source: https://info.bundle.social/api-reference/client/analytics/get-social-account-analytics https://api.bundle.social/swagger-json get /api/v1/analytics/social-account Retrieve normalized profile-level metrics such as followers, reach, and impressions for a connected social account over a date range. Metric names are unified across platforms so you can chart accounts side by side. # Get Social Account Analytics Raw Source: https://info.bundle.social/api-reference/client/analytics/get-social-account-analytics-raw https://api.bundle.social/swagger-json get /api/v1/analytics/social-account/raw Retrieve social account analytics exactly as returned by the social platform, without bundle.social's normalization. Use this when you need a platform-specific metric that the normalized response does not expose. # Get health Source: https://info.bundle.social/api-reference/client/app/get-health https://api.bundle.social/swagger-json get /api/v1/ Check whether the bundle.social API is reachable and see the current operational status of every supported social platform. Use this endpoint for uptime monitoring and to detect platform-side outages before publishing. # Activate an automation flow Source: https://info.bundle.social/api-reference/client/automation/activate-an-automation-flow https://api.bundle.social/swagger-json post /api/v1/automations/{id}/activate Resume a paused flow so that it triggers on new events again. # Archive an automation flow Source: https://info.bundle.social/api-reference/client/automation/archive-an-automation-flow https://api.bundle.social/swagger-json post /api/v1/automations/{id}/archive Retire a flow without deleting it. Archived flows never trigger and are hidden from the default list. # Copy automation flows between teams Source: https://info.bundle.social/api-reference/client/automation/copy-automation-flows-between-teams https://api.bundle.social/swagger-json post /api/v1/automations/copy Duplicate one or more automation flows into another team. The copies are created as drafts so they can be re-pointed at that team's social accounts before going live. # Create an automation flow Source: https://info.bundle.social/api-reference/client/automation/create-an-automation-flow https://api.bundle.social/swagger-json post /api/v1/automations Create an automation flow from a trigger and a list of steps. The flow starts as a draft and only runs once it is published. # Create or update automation provider settings Source: https://info.bundle.social/api-reference/client/automation/create-or-update-automation-provider-settings https://api.bundle.social/swagger-json put /api/v1/automation-provider-settings/{socialAccountId}/{type} Create or replace the automation setting of a given type for a social account, and push it to the platform. # Delete an automation flow Source: https://info.bundle.social/api-reference/client/automation/delete-an-automation-flow https://api.bundle.social/swagger-json delete /api/v1/automations/{id} Delete an automation flow. Past executions are kept for auditing and stay readable. # Get an automation execution Source: https://info.bundle.social/api-reference/client/automation/get-an-automation-execution https://api.bundle.social/swagger-json get /api/v1/automation-executions/{id} Get a single automation run by id, including its input event, its per-step results and any error that stopped it. # Get an automation flow Source: https://info.bundle.social/api-reference/client/automation/get-an-automation-flow https://api.bundle.social/swagger-json get /api/v1/automations/{id} Get a single automation flow by id, including its trigger, its steps and its current status. # Get automation flow executions Source: https://info.bundle.social/api-reference/client/automation/get-automation-flow-executions https://api.bundle.social/swagger-json get /api/v1/automations/{id}/executions List the runs of a single automation flow, newest first. Use it to see which events matched and how each run ended. Paginate with `offset` (`limit` max 500, default 10) or by passing the previous response's `nextCursor` back as `cursor`; the two cannot be combined. `total` is returned on the first page only. # Get automation flows Source: https://info.bundle.social/api-reference/client/automation/get-automation-flows https://api.bundle.social/swagger-json get /api/v1/automations List the automation flows of a team, newest first. Filter by `socialAccountId`, `status` and `platformScope`. Paginate with `offset` and `limit` (default 10). The response always carries the full `total`. # Get automation provider settings Source: https://info.bundle.social/api-reference/client/automation/get-automation-provider-settings https://api.bundle.social/swagger-json get /api/v1/automation-provider-settings List the platform-side automation settings stored per social account, such as the Instagram icebreakers or persistent menu we manage for you. Paginate with `offset` and `limit` (default 10). The response always carries the full `total`. # Pause an automation flow Source: https://info.bundle.social/api-reference/client/automation/pause-an-automation-flow https://api.bundle.social/swagger-json post /api/v1/automations/{id}/pause Stop a live flow from triggering on new events while keeping its configuration intact. # Publish an automation flow Source: https://info.bundle.social/api-reference/client/automation/publish-an-automation-flow https://api.bundle.social/swagger-json post /api/v1/automations/{id}/publish Validate a draft flow and make it live, so that matching events start triggering it. Returns 400 when the flow is not valid. # Run an automation flow test Source: https://info.bundle.social/api-reference/client/automation/run-an-automation-flow-test https://api.bundle.social/swagger-json post /api/v1/automations/{id}/test Run a flow once against a sample event and return the resulting execution. Steps that send a message really send it, so a test returns 503 while messaging sending is temporarily disabled. # Send a rich automation message to a conversation Source: https://info.bundle.social/api-reference/client/automation/send-a-rich-automation-message-to-a-conversation https://api.bundle.social/swagger-json post /api/v1/automation-rich-messages/conversations/{conversationId} Send a rich message, such as a button or card template, into a conversation using the same renderer the automation steps use. Returns 503 while messaging sending is temporarily disabled. # Sync automation provider settings Source: https://info.bundle.social/api-reference/client/automation/sync-automation-provider-settings https://api.bundle.social/swagger-json post /api/v1/automation-provider-settings/{id}/sync Re-push a stored automation setting to the platform, for example after a failed sync or a reconnected account. # Update an automation flow Source: https://info.bundle.social/api-reference/client/automation/update-an-automation-flow https://api.bundle.social/swagger-json patch /api/v1/automations/{id} Update the name, trigger or steps of an automation flow. Changes to a published flow take effect on the next matching event. # Create comment Source: https://info.bundle.social/api-reference/client/comment/create-comment https://api.bundle.social/swagger-json post /api/v1/comment/ Publish a comment or a reply on one of your published posts. Use it to schedule the first comment on Instagram or LinkedIn, or to respond to your audience programmatically. # Delete comment Source: https://info.bundle.social/api-reference/client/comment/delete-comment https://api.bundle.social/swagger-json delete /api/v1/comment/{id} Permanently delete a comment from bundle.social. Deleting a scheduled comment cancels it before it publishes. # Get comment Source: https://info.bundle.social/api-reference/client/comment/get-comment https://api.bundle.social/swagger-json get /api/v1/comment/{id} Retrieve a single comment you created through bundle.social, including its publishing status and any error details. # Get comment import by ID Source: https://info.bundle.social/api-reference/client/comment/get-comment-import-by-id https://api.bundle.social/swagger-json get /api/v1/comment/import/{importId} Check the status, progress, and result of a single comment import job. # Get comment import list Source: https://info.bundle.social/api-reference/client/comment/get-comment-import-list https://api.bundle.social/swagger-json get /api/v1/comment/import List comment import jobs for a team so you can monitor which imports are queued, running, finished, or failed. # Get comment list Source: https://info.bundle.social/api-reference/client/comment/get-comment-list https://api.bundle.social/swagger-json get /api/v1/comment/ List and filter the comments your organization has created, with pagination. Use it to track which scheduled comments published successfully. # Get fetched comments for a post Source: https://info.bundle.social/api-reference/client/comment/get-fetched-comments-for-a-post https://api.bundle.social/swagger-json get /api/v1/comment/import/comments List the comments pulled in by a comment import, with pagination. Use this to read audience replies and decide which ones need a response. # Retry comment Source: https://info.bundle.social/api-reference/client/comment/retry-comment https://api.bundle.social/swagger-json post /api/v1/comment/{id}/retry Re-attempt publishing a comment that failed, for example after a token expired or a platform outage. # Run an action on a fetched comment Source: https://info.bundle.social/api-reference/client/comment/run-an-action-on-a-fetched-comment https://api.bundle.social/swagger-json post /api/v1/comment/import/comments/{commentId}/action Reply to, hide, like, or delete an imported comment directly on the social platform. Use this to moderate and engage without leaving your own app. # Start a new comment import for a post Source: https://info.bundle.social/api-reference/client/comment/start-a-new-comment-import-for-a-post https://api.bundle.social/swagger-json post /api/v1/comment/import Kick off an asynchronous import that pulls existing comments from a published post on the social platform into bundle.social so you can read and reply to them through the API. # Update comment Source: https://info.bundle.social/api-reference/client/comment/update-comment https://api.bundle.social/swagger-json patch /api/v1/comment/{id} Change the content or scheduled time of a comment that has not published yet. # Archive conversation Source: https://info.bundle.social/api-reference/client/conversation/archive-conversation https://api.bundle.social/swagger-json post /api/v1/conversations/{id}/archive Move a conversation out of the active inbox. Incoming messages reopen it automatically. # Get conversation Source: https://info.bundle.social/api-reference/client/conversation/get-conversation https://api.bundle.social/swagger-json get /api/v1/conversations/{id} Get a single conversation by id, including the participant, the linked social account and its unread and status flags. # Get conversation messages Source: https://info.bundle.social/api-reference/client/conversation/get-conversation-messages https://api.bundle.social/swagger-json get /api/v1/conversations/{id}/messages List the messages of a conversation. Pages walk backwards in time, while the messages inside a page are ordered oldest first, ready to render. Includes attachments, reactions and delivery state. Paginate with `offset` (`limit` max 500, default 10) or by passing the previous response's `nextCursor` back as `cursor`; the two cannot be combined. `total` is returned on the first page only. # Get conversations Source: https://info.bundle.social/api-reference/client/conversation/get-conversations https://api.bundle.social/swagger-json get /api/v1/conversations/ List conversations for a team, newest activity first. Filter by `socialAccountId`, `platform` and `status`. Paginate with `offset` (`limit` max 500, default 10) or by passing the previous response's `nextCursor` back as `cursor`; the two cannot be combined. `total` is returned on the first page only. # Mark conversation as read Source: https://info.bundle.social/api-reference/client/conversation/mark-conversation-as-read https://api.bundle.social/swagger-json post /api/v1/conversations/{id}/read Clear the unread state of a conversation, optionally up to a specific message. # Open conversation Source: https://info.bundle.social/api-reference/client/conversation/open-conversation https://api.bundle.social/swagger-json post /api/v1/conversations/{id}/open Move an archived or closed conversation back into the active inbox. # React or unreact to a conversation message Source: https://info.bundle.social/api-reference/client/conversation/react-or-unreact-to-a-conversation-message https://api.bundle.social/swagger-json post /api/v1/conversations/{id}/messages/{messageId}/reaction Add or remove a reaction on a message in a conversation. Returns 503 while messaging sending is temporarily disabled. # Send a conversation message Source: https://info.bundle.social/api-reference/client/conversation/send-a-conversation-message https://api.bundle.social/swagger-json post /api/v1/conversations/{id}/messages Send a message to the participant of a conversation. The platform reply window must still be open. Returns 503 while messaging sending is temporarily disabled. # Send a private reply to a fetched Meta comment Source: https://info.bundle.social/api-reference/client/conversation/send-a-private-reply-to-a-fetched-meta-comment https://api.bundle.social/swagger-json post /api/v1/conversations/private-reply Send a direct message in reply to a Facebook or Instagram comment we have already imported. Creates the conversation when none exists yet. Returns 503 while messaging sending is temporarily disabled. # Update conversation Source: https://info.bundle.social/api-reference/client/conversation/update-conversation https://api.bundle.social/swagger-json patch /api/v1/conversations/{id} Set the status of a conversation. This is the general form of the archive and open endpoints, which move a conversation to one specific status. # Get credit balance Source: https://info.bundle.social/api-reference/client/credit/get-credit-balance https://api.bundle.social/swagger-json get /api/v1/billing/credits/balance Retrieve your organization's prepaid credit balance: settled funds, in-flight holds, and the available amount metered X actions draw from. # Quote a metered X action Source: https://info.bundle.social/api-reference/client/credit/quote-a-metered-x-action https://api.bundle.social/swagger-json post /api/v1/billing/billable-usage/quote Estimate the credit cost of a metered X action (post publishing, analytics reads, imports) before running it, and see whether your current balance covers it. # [DISABLED] Edit an existing Pinterest pin Source: https://info.bundle.social/api-reference/client/misc/[disabled]-edit-an-existing-pinterest-pin https://api.bundle.social/swagger-json patch /api/v1/misc/pinterest/pin Temporarily disabled # Add a media item (photo/video) using uploadId and category Source: https://info.bundle.social/api-reference/client/misc/add-a-media-item-photovideo-using-uploadid-and-category https://api.bundle.social/swagger-json post /api/v1/misc/google-business/media Publish a photo or video to your Google Business Profile from a bundle.social upload, tagged with a category such as exterior, interior, or product. Fresh photos are a local ranking and conversion signal. # Add a video to a playlist Source: https://info.bundle.social/api-reference/client/misc/add-a-video-to-a-playlist https://api.bundle.social/swagger-json post /api/v1/misc/youtube/playlist-items Append a video to a YouTube playlist on a connected channel. # Build Linkedin text, insert mentions at tag placeholders. Source: https://info.bundle.social/api-reference/client/misc/build-linkedin-text-insert-mentions-at-tag-placeholders https://api.bundle.social/swagger-json post /api/v1/misc/linkedin/mentions/builder If tag already exists (case insensitive), mentions replace it; otherwise they're appended to the end. # Create a new playlist Source: https://info.bundle.social/api-reference/client/misc/create-a-new-playlist https://api.bundle.social/swagger-json post /api/v1/misc/youtube/playlist Create a playlist on a connected YouTube channel with a title, description, and privacy status. Playlists group related videos and increase session watch time. # Create Google Business place action link Source: https://info.bundle.social/api-reference/client/misc/create-google-business-place-action-link https://api.bundle.social/swagger-json post /api/v1/misc/google-business/location/place-action-links Add an action link such as Book, Order online, or Reserve to your Google Business Profile so customers can convert straight from the listing. # Delete a Bluesky comment Source: https://info.bundle.social/api-reference/client/misc/delete-a-bluesky-comment https://api.bundle.social/swagger-json delete /api/v1/misc/bluesky/comment Permanently delete a published Bluesky reply/comment. # Delete a Bluesky post Source: https://info.bundle.social/api-reference/client/misc/delete-a-bluesky-post https://api.bundle.social/swagger-json delete /api/v1/misc/bluesky/post Permanently delete a published Bluesky post. # Delete a channel playlist Source: https://info.bundle.social/api-reference/client/misc/delete-a-channel-playlist https://api.bundle.social/swagger-json delete /api/v1/misc/youtube/playlist/{playlistId} Permanently delete a playlist from a connected YouTube channel. The videos themselves are not deleted. # Delete a Discord message Source: https://info.bundle.social/api-reference/client/misc/delete-a-discord-message https://api.bundle.social/swagger-json delete /api/v1/misc/discord/message Permanently delete a published Discord message. # Delete a Facebook comment Source: https://info.bundle.social/api-reference/client/misc/delete-a-facebook-comment https://api.bundle.social/swagger-json delete /api/v1/misc/facebook/comment Permanently delete a published Facebook comment. # Delete a Facebook post Source: https://info.bundle.social/api-reference/client/misc/delete-a-facebook-post https://api.bundle.social/swagger-json delete /api/v1/misc/facebook/post Permanently delete a published Facebook post or reel. # Delete a Google Business post Source: https://info.bundle.social/api-reference/client/misc/delete-a-google-business-post https://api.bundle.social/swagger-json delete /api/v1/misc/google-business/post Permanently delete a published Google Business post. # Delete a LinkedIn comment Source: https://info.bundle.social/api-reference/client/misc/delete-a-linkedin-comment https://api.bundle.social/swagger-json delete /api/v1/misc/linkedin/comment Permanently delete a published LinkedIn comment. # Delete a LinkedIn post Source: https://info.bundle.social/api-reference/client/misc/delete-a-linkedin-post https://api.bundle.social/swagger-json delete /api/v1/misc/linkedin/post Permanently delete a published LinkedIn post. # Delete a Mastodon comment Source: https://info.bundle.social/api-reference/client/misc/delete-a-mastodon-comment https://api.bundle.social/swagger-json delete /api/v1/misc/mastodon/comment Permanently delete a published Mastodon reply/comment. # Delete a Mastodon status Source: https://info.bundle.social/api-reference/client/misc/delete-a-mastodon-status https://api.bundle.social/swagger-json delete /api/v1/misc/mastodon/status Permanently delete a published Mastodon status. # Delete a Pinterest pin Source: https://info.bundle.social/api-reference/client/misc/delete-a-pinterest-pin https://api.bundle.social/swagger-json delete /api/v1/misc/pinterest/pin Permanently delete a published Pinterest pin. # Delete a Reddit comment Source: https://info.bundle.social/api-reference/client/misc/delete-a-reddit-comment https://api.bundle.social/swagger-json delete /api/v1/misc/reddit/comment Permanently delete a published Reddit comment. # Delete a Reddit post Source: https://info.bundle.social/api-reference/client/misc/delete-a-reddit-post https://api.bundle.social/swagger-json delete /api/v1/misc/reddit/post Permanently delete a published Reddit post. # Delete a Slack message Source: https://info.bundle.social/api-reference/client/misc/delete-a-slack-message https://api.bundle.social/swagger-json delete /api/v1/misc/slack/message Permanently delete a published Slack message. # Delete a TikTok comment Source: https://info.bundle.social/api-reference/client/misc/delete-a-tiktok-comment https://api.bundle.social/swagger-json delete /api/v1/misc/tiktok/comment Delete a published TikTok comment. # Delete a Twitter/X comment Source: https://info.bundle.social/api-reference/client/misc/delete-a-twitterx-comment https://api.bundle.social/swagger-json delete /api/v1/misc/twitter/comment Permanently delete a published Twitter/X reply/comment. X charges for deletes ($0.01 per request). # Delete a Twitter/X tweet Source: https://info.bundle.social/api-reference/client/misc/delete-a-twitterx-tweet https://api.bundle.social/swagger-json delete /api/v1/misc/twitter/tweet Permanently delete a published Twitter/X tweet. X charges for deletes ($0.01 per request). # Delete a YouTube comment Source: https://info.bundle.social/api-reference/client/misc/delete-a-youtube-comment https://api.bundle.social/swagger-json delete /api/v1/misc/youtube/comment Permanently delete a published YouTube comment. # Delete a YouTube video Source: https://info.bundle.social/api-reference/client/misc/delete-a-youtube-video https://api.bundle.social/swagger-json delete /api/v1/misc/youtube/video Permanently delete a published YouTube video. # Delete an Instagram comment Source: https://info.bundle.social/api-reference/client/misc/delete-an-instagram-comment https://api.bundle.social/swagger-json delete /api/v1/misc/instagram/comment Permanently delete a published Instagram comment. # Delete Google Business media item Source: https://info.bundle.social/api-reference/client/misc/delete-google-business-media-item https://api.bundle.social/swagger-json delete /api/v1/misc/google-business/media Remove a photo or video from your Google Business Profile. # Delete Google Business place action link Source: https://info.bundle.social/api-reference/client/misc/delete-google-business-place-action-link https://api.bundle.social/swagger-json delete /api/v1/misc/google-business/location/place-action-links Remove an action link from your Google Business Profile, for example when a booking URL is retired. # Delete the owner reply from a Google Review Source: https://info.bundle.social/api-reference/client/misc/delete-the-owner-reply-from-a-google-review https://api.bundle.social/swagger-json delete /api/v1/misc/google-business/reviews/{reviewId}/reply Remove your owner reply from a Google Review, leaving the customer's review in place. # Disable ad authorization for a TikTok post Source: https://info.bundle.social/api-reference/client/misc/disable-ad-authorization-for-a-tiktok-post https://api.bundle.social/swagger-json delete /api/v1/misc/tiktok/ad-authorization Turns off the "Ad authorization" setting of a TikTok post. TikTok refuses this (400) while the post runs in an active Spark Ad: pause those ads first. # Edit a Facebook comment Source: https://info.bundle.social/api-reference/client/misc/edit-a-facebook-comment https://api.bundle.social/swagger-json patch /api/v1/misc/facebook/comment Update the text content of a published Facebook comment. # Edit a Mastodon comment Source: https://info.bundle.social/api-reference/client/misc/edit-a-mastodon-comment https://api.bundle.social/swagger-json patch /api/v1/misc/mastodon/comment Update the text content of a published Mastodon reply/comment. # Edit an existing Facebook post Source: https://info.bundle.social/api-reference/client/misc/edit-an-existing-facebook-post https://api.bundle.social/swagger-json patch /api/v1/misc/facebook/post Update the message/content of a published Facebook post or reel. Note: Only text content can be edited, media cannot be changed. # Edit an existing LinkedIn comment Source: https://info.bundle.social/api-reference/client/misc/edit-an-existing-linkedin-comment https://api.bundle.social/swagger-json patch /api/v1/misc/linkedin/comment Update the text content of a published LinkedIn comment. # Edit an existing LinkedIn post Source: https://info.bundle.social/api-reference/client/misc/edit-an-existing-linkedin-post https://api.bundle.social/swagger-json patch /api/v1/misc/linkedin/post Update the text content of a published LinkedIn post. # Edit an existing Mastodon status Source: https://info.bundle.social/api-reference/client/misc/edit-an-existing-mastodon-status https://api.bundle.social/swagger-json patch /api/v1/misc/mastodon/status Update the text content and spoiler text of a published Mastodon status. # Edit an existing Reddit comment Source: https://info.bundle.social/api-reference/client/misc/edit-an-existing-reddit-comment https://api.bundle.social/swagger-json patch /api/v1/misc/reddit/comment Update the text content of a published Reddit comment. # Edit an existing Reddit post Source: https://info.bundle.social/api-reference/client/misc/edit-an-existing-reddit-post https://api.bundle.social/swagger-json patch /api/v1/misc/reddit/post Update the selftext content of a published Reddit text post. Link and media posts cannot be edited. # Edit an existing Slack message Source: https://info.bundle.social/api-reference/client/misc/edit-an-existing-slack-message https://api.bundle.social/swagger-json patch /api/v1/misc/slack/message Update the text content of a published Slack message. # Edit YouTube comment Source: https://info.bundle.social/api-reference/client/misc/edit-youtube-comment https://api.bundle.social/swagger-json patch /api/v1/misc/youtube/comment Update the text content of a published YouTube comment. # Edit YouTube video metadata Source: https://info.bundle.social/api-reference/client/misc/edit-youtube-video-metadata https://api.bundle.social/swagger-json patch /api/v1/misc/youtube/video Update the title, description, tags, category, or privacy status of a published YouTube video. # Enable ad authorization and get a Spark Ads code Source: https://info.bundle.social/api-reference/client/misc/enable-ad-authorization-and-get-a-spark-ads-code https://api.bundle.social/swagger-json post /api/v1/misc/tiktok/ad-authorization Turns on the "Ad authorization" setting of a public TikTok post and returns its Spark Ads authorization code. Share the code with the advertiser, who adds it to their TikTok ad account to run the post as a Spark Ad. Enabling it accepts TikTok's Advertising Content Terms of Service for the post. # Extend the Spark Ads code of a TikTok post Source: https://info.bundle.social/api-reference/client/misc/extend-the-spark-ads-code-of-a-tiktok-post https://api.bundle.social/swagger-json post /api/v1/misc/tiktok/ad-authorization/extend Adds days to the validity period of the post's Spark Ads code, or issues a new code if the previous one was deleted. Ad authorization must already be enabled for the post. # Get a single imported Facebook recommendation Source: https://info.bundle.social/api-reference/client/misc/get-a-single-imported-facebook-recommendation https://api.bundle.social/swagger-json get /api/v1/misc/facebook/recommendations/{recommendationId} Retrieve one imported Facebook recommendation with its rating, text, author, and existing replies. # Get a single imported Google Review Source: https://info.bundle.social/api-reference/client/misc/get-a-single-imported-google-review https://api.bundle.social/swagger-json get /api/v1/misc/google-business/reviews/{reviewId} Retrieve one imported Google Review with its star rating, text, reviewer, and any existing owner reply. # Get channel playlists Source: https://info.bundle.social/api-reference/client/misc/get-channel-playlists https://api.bundle.social/swagger-json get /api/v1/misc/youtube/playlist List the playlists on a connected YouTube channel, with their IDs, titles, and privacy status. # Get Facebook recommendations import by ID Source: https://info.bundle.social/api-reference/client/misc/get-facebook-recommendations-import-by-id https://api.bundle.social/swagger-json get /api/v1/misc/facebook/recommendations/import/{importId} Check the status, progress, and result of a single Facebook recommendations import job. # Get Facebook recommendations import status list Source: https://info.bundle.social/api-reference/client/misc/get-facebook-recommendations-import-status-list https://api.bundle.social/swagger-json get /api/v1/misc/facebook/recommendations/import List Facebook recommendation import jobs for a team so you can monitor which imports are queued, running, finished, or failed. # Get Facebook token debug details Source: https://info.bundle.social/api-reference/client/misc/get-facebook-token-debug-details https://api.bundle.social/swagger-json get /api/v1/misc/facebook/token-debug Inspect a connected Facebook account's access token, including its scopes and expiry. Use it to diagnose permission errors when publishing fails. # Get Google Business food menus Source: https://info.bundle.social/api-reference/client/misc/get-google-business-food-menus https://api.bundle.social/swagger-json get /api/v1/misc/google-business/location/food-menus Use typed query param `fields`. Supports both comma-separated values (`fields=name,menus`) and repeated params (`fields=name&fields=menus`). # Get Google Business location attributes Source: https://info.bundle.social/api-reference/client/misc/get-google-business-location-attributes https://api.bundle.social/swagger-json get /api/v1/misc/google-business/location/attributes Retrieve the attributes currently set on your Google Business Profile location, such as accessibility, payment options, or amenities. # Get Google Business location profile Source: https://info.bundle.social/api-reference/client/misc/get-google-business-location-profile https://api.bundle.social/swagger-json get /api/v1/misc/google-business/location Use typed query param `fields`. Supports both comma-separated values (`fields=name,title`) and repeated params (`fields=name&fields=title`). # Get Google Business service list Source: https://info.bundle.social/api-reference/client/misc/get-google-business-service-list https://api.bundle.social/swagger-json get /api/v1/misc/google-business/location/service-list Retrieve the services listed on your Google Business Profile, including custom services and prices. # Get Linkedin mentionable tags (people & organizations) Source: https://info.bundle.social/api-reference/client/misc/get-linkedin-mentionable-tags-people-&-organizations https://api.bundle.social/swagger-json get /api/v1/misc/linkedin/mentions/tags Search for LinkedIn people and organizations that can be @-mentioned, and get the tag IDs needed to insert them into post text. LinkedIn only renders a mention when the display text matches the entity's name exactly (case sensitive), so a vanity slug never works. When a person is resolved from `url` but LinkedIn does not expose their name, the tag comes back with an empty `display` and `needsDisplayName: true` — pass `displayName` to set it. Note that a page can only mention its own followers. # Get popular tracks from TikTok Commercial Music Library Source: https://info.bundle.social/api-reference/client/misc/get-popular-tracks-from-tiktok-commercial-music-library https://api.bundle.social/swagger-json get /api/v1/misc/tiktok/cml/trending-list Retrieve up to 100 popular tracks pre-cleared for organic content and ad creation from TikTok CML. # Get recommendation thread comments Source: https://info.bundle.social/api-reference/client/misc/get-recommendation-thread-comments https://api.bundle.social/swagger-json get /api/v1/misc/facebook/recommendations/{recommendationId}/comments List the comments in a Facebook recommendation thread so you can see the full conversation before replying. # Get review import by ID Source: https://info.bundle.social/api-reference/client/misc/get-review-import-by-id https://api.bundle.social/swagger-json get /api/v1/misc/google-business/reviews/import/{importId} Check the status, progress, and result of a single Google Reviews import job. # Get review import status list Source: https://info.bundle.social/api-reference/client/misc/get-review-import-status-list https://api.bundle.social/swagger-json get /api/v1/misc/google-business/reviews/import List Google Review import jobs for a team so you can monitor which imports are queued, running, finished, or failed. # Get subreddit flairs list Source: https://info.bundle.social/api-reference/client/misc/get-subreddit-flairs-list https://api.bundle.social/swagger-json get /api/v1/misc/reddit/subreddit-flairs List the flairs available in a subreddit so you can attach a valid flair ID when creating a Reddit post. # Get subreddit post requirements (flair required/enabled) Source: https://info.bundle.social/api-reference/client/misc/get-subreddit-post-requirements-flair-requiredenabled https://api.bundle.social/swagger-json get /api/v1/misc/reddit/post-requirements Check a subreddit's posting rules before publishing, including whether flair is enabled or mandatory. Call this first to avoid rejected submissions. # Get the posting options of a TikTok account Source: https://info.bundle.social/api-reference/client/misc/get-the-posting-options-of-a-tiktok-account https://api.bundle.social/swagger-json get /api/v1/misc/tiktok/post-settings Returns the privacy levels, interaction settings (comments, duet, stitch) and maximum video duration the connected TikTok account allows, read live from TikTok. A value the account does not allow is not rejected when you create the post, it fails at publish time with TT:40002. Use it to build the options of your own composer, not as a check before every publish: each call counts against the account's TikTok rate limit. # Get the Spark Ads code of a TikTok post Source: https://info.bundle.social/api-reference/client/misc/get-the-spark-ads-code-of-a-tiktok-post https://api.bundle.social/swagger-json get /api/v1/misc/tiktok/ad-authorization Returns the current Spark Ads authorization code of a TikTok post with its validity window and status (NOT_USED, IN_USE, EXPIRED). Fails with 400 if ad authorization was never enabled for the post or its code was deleted. # Get videos from a playlist Source: https://info.bundle.social/api-reference/client/misc/get-videos-from-a-playlist https://api.bundle.social/swagger-json get /api/v1/misc/youtube/playlist-items List the videos in a YouTube playlist, including the playlist item IDs required to remove individual entries. # Get YouTube regions Source: https://info.bundle.social/api-reference/client/misc/get-youtube-regions https://api.bundle.social/swagger-json get /api/v1/misc/youtube/regions Retrieve the list of content regions that the YouTube website supports. # Get YouTube video categories Source: https://info.bundle.social/api-reference/client/misc/get-youtube-video-categories https://api.bundle.social/swagger-json get /api/v1/misc/youtube/video-categories Retrieve the list of video categories that can be associated with YouTube videos for a specific region. # List available Google Business attributes Source: https://info.bundle.social/api-reference/client/misc/list-available-google-business-attributes https://api.bundle.social/swagger-json get /api/v1/misc/google-business/location/attributes/available List the attributes Google allows for your location's category and country. Check this before updating attributes, since the valid set differs per business category. `regionCode`/`languageCode` are honoured by looking the attributes up through the location's primary category; when that category or a region code cannot be resolved (common for service-area businesses with no storefront address) the location's own defaults are returned instead and `lookup.by` comes back as `location`, meaning those two parameters were not applied. # List available Google Business categories Source: https://info.bundle.social/api-reference/client/misc/list-available-google-business-categories https://api.bundle.social/swagger-json get /api/v1/misc/google-business/location/categories/available Requires `regionCode` and `languageCode`. Default `view=BASIC`. Optional `names` fetches exact category IDs through `categories:batchGet`; otherwise `filter` supports `displayName` prefix search. # List Facebook text background presets Source: https://info.bundle.social/api-reference/client/misc/list-facebook-text-background-presets https://api.bundle.social/swagger-json get /api/v1/misc/facebook/text-format-presets Return the text background presets (colored statuses) that can be passed as data.FACEBOOK.textFormatPresetId, grouped by whether each one renders as a flat color, a gradient, or an illustration. Facebook exposes no endpoint of its own for this, so read the list from here instead of hardcoding IDs. Any other numeric ID is also accepted and passed straight through to Facebook. # List Google Business media items Source: https://info.bundle.social/api-reference/client/misc/list-google-business-media-items https://api.bundle.social/swagger-json get /api/v1/misc/google-business/media List the photos and videos on your Google Business Profile, with paging. Use it to audit which images are live before adding or removing media. # List Google Business place action links Source: https://info.bundle.social/api-reference/client/misc/list-google-business-place-action-links https://api.bundle.social/swagger-json get /api/v1/misc/google-business/location/place-action-links List the action links on your Google Business Profile, such as booking, ordering, or reservation URLs. # List imported Facebook recommendations Source: https://info.bundle.social/api-reference/client/misc/list-imported-facebook-recommendations https://api.bundle.social/swagger-json get /api/v1/misc/facebook/recommendations List the Facebook Page recommendations pulled in by an import, with paging and your remaining import capacity. Use it to build a reputation-management inbox. # List imported Google Reviews Source: https://info.bundle.social/api-reference/client/misc/list-imported-google-reviews https://api.bundle.social/swagger-json get /api/v1/misc/google-business/reviews List the Google Reviews pulled in by an import, with paging and your remaining import capacity. Use it to build a review inbox or monitor rating trends. # List the search terms customers used to find the location Source: https://info.bundle.social/api-reference/client/misc/list-the-search-terms-customers-used-to-find-the-location https://api.bundle.social/swagger-json get /api/v1/misc/google-business/location/search-keywords Monthly search keyword impressions for your selected location. `startMonth`/`endMonth` are inclusive `YYYY-MM` values; counts are aggregated across the whole range, so request a single month for a per-month figure. Each keyword returns either an exact `value` or a `threshold`, meaning the real count is below that number: low-volume keywords are only ever reported as a threshold, so treat a null `value` as suppressed rather than zero. Counts are unique users, not raw impressions. Paginated with `pageToken`/`nextPageToken`, max `pageSize` 100. # Remove a video from a playlist Source: https://info.bundle.social/api-reference/client/misc/remove-a-video-from-a-playlist https://api.bundle.social/swagger-json delete /api/v1/misc/youtube/playlist-items/{playlistItemId} Remove a single video from a YouTube playlist. Pass the playlist item ID, not the video ID. The video itself stays on the channel. # Reply to a Facebook recommendation Source: https://info.bundle.social/api-reference/client/misc/reply-to-a-facebook-recommendation https://api.bundle.social/swagger-json put /api/v1/misc/facebook/recommendations/{recommendationId}/reply Publish a Page reply to a Facebook recommendation. Use it to respond to reviews programmatically instead of through Meta Business Suite. # Reply to a Facebook recommendation thread comment Source: https://info.bundle.social/api-reference/client/misc/reply-to-a-facebook-recommendation-thread-comment https://api.bundle.social/swagger-json put /api/v1/misc/facebook/recommendations/{recommendationId}/comments/{commentId}/reply Publish a reply to a specific comment inside a Facebook recommendation thread. # Reply to a Google Review (creates or updates the owner reply) Source: https://info.bundle.social/api-reference/client/misc/reply-to-a-google-review-creates-or-updates-the-owner-reply https://api.bundle.social/swagger-json put /api/v1/misc/google-business/reviews/{reviewId}/reply Publish or update the owner reply on a Google Review. Google allows one owner reply per review, so sending again overwrites the previous text. # Repost a Twitter/X post Source: https://info.bundle.social/api-reference/client/misc/repost-a-twitterx-post https://api.bundle.social/swagger-json post /api/v1/misc/twitter/retweet Repost (retweet) any X post from the connected account. X charges for reposts ($0.015 per request); your credits are charged once per post, per connected account, per UTC day, so reposting the same post again on the same day costs no extra credit. Reposting a post that is already reposted is a no-op on X's side. # Reshare an existing LinkedIn post Source: https://info.bundle.social/api-reference/client/misc/reshare-an-existing-linkedin-post https://api.bundle.social/swagger-json post /api/v1/misc/linkedin/post/reshare Create a LinkedIn reshare as the currently selected LinkedIn channel. # Search Facebook Pages Source: https://info.bundle.social/api-reference/client/misc/search-facebook-pages https://api.bundle.social/swagger-json get /api/v1/misc/facebook/pages Searches public Facebook Pages and returns IDs that can be inserted into Facebook Page mention tokens. # Search for Instagram Business/Creator user by username Source: https://info.bundle.social/api-reference/client/misc/search-for-instagram-businesscreator-user-by-username https://api.bundle.social/swagger-json get /api/v1/misc/instagram/tags Checks if an Instagram user exists and returns their public profile data. Only works for Business and Creator accounts and only when Instagram is connected via Facebook Login. Returns followers_count, media_count, and profile picture if available. # Search Instagram audio assets Source: https://info.bundle.social/api-reference/client/misc/search-instagram-audio-assets https://api.bundle.social/swagger-json get /api/v1/misc/instagram/audio Searches Instagram music or original sounds that can be attached to Reels. Only works for Instagram accounts connected via Facebook Login. # Search Instagram location IDs Source: https://info.bundle.social/api-reference/client/misc/search-instagram-location-ids https://api.bundle.social/swagger-json get /api/v1/misc/instagram/locations Searches Facebook Pages with physical location data and returns IDs that can be used as data.INSTAGRAM.locationId. # Search TikTok location tags Source: https://info.bundle.social/api-reference/client/misc/search-tiktok-location-tags https://api.bundle.social/swagger-json get /api/v1/misc/tiktok/locations Searches location tags available to the connected TikTok account (up to 20 results). Pass `locationId` and `name` as data.TIKTOK.locationId and data.TIKTOK.locationName to show the location on a video or photo post. # Set or change thumbnail for a YouTube video Source: https://info.bundle.social/api-reference/client/misc/set-or-change-thumbnail-for-a-youtube-video https://api.bundle.social/swagger-json post /api/v1/misc/youtube/thumbnail Upload a custom thumbnail for a published YouTube video. Custom thumbnails require a verified channel and strongly influence click-through rate. # Start a new Facebook recommendations import Source: https://info.bundle.social/api-reference/client/misc/start-a-new-facebook-recommendations-import https://api.bundle.social/swagger-json post /api/v1/misc/facebook/recommendations/import Kick off an asynchronous import that pulls recommendations left on your Facebook Page into bundle.social so you can read and reply to them through the API. # Start a new Google Reviews import Source: https://info.bundle.social/api-reference/client/misc/start-a-new-google-reviews-import https://api.bundle.social/swagger-json post /api/v1/misc/google-business/reviews/import Kick off an asynchronous import that pulls your Google Business Profile reviews into bundle.social so you can read and reply to them through the API. # Undo a Twitter/X repost Source: https://info.bundle.social/api-reference/client/misc/undo-a-twitterx-repost https://api.bundle.social/swagger-json delete /api/v1/misc/twitter/retweet Remove a repost (retweet) made by the connected account. X charges for this too ($0.01 per request); your credits are charged once per post, per connected account, per UTC day, the same way reposting is. # Update an existing playlist Source: https://info.bundle.social/api-reference/client/misc/update-an-existing-playlist https://api.bundle.social/swagger-json put /api/v1/misc/youtube/playlist Change the title, description, or privacy status of a YouTube playlist on a connected channel. Send the playlist ID together with the fields you want to update. # Update Google Business food menus Source: https://info.bundle.social/api-reference/client/misc/update-google-business-food-menus https://api.bundle.social/swagger-json patch /api/v1/misc/google-business/location/food-menus Body requires `fields` (`menus`). # Update Google Business location attributes Source: https://info.bundle.social/api-reference/client/misc/update-google-business-location-attributes https://api.bundle.social/swagger-json patch /api/v1/misc/google-business/location/attributes Set or change attributes on your Google Business Profile location. Complete attributes help your listing surface for more specific local searches. # Update Google Business location profile fields Source: https://info.bundle.social/api-reference/client/misc/update-google-business-location-profile-fields https://api.bundle.social/swagger-json patch /api/v1/misc/google-business/location Field mask is derived automatically from provided fields. # Update Google Business place action link Source: https://info.bundle.social/api-reference/client/misc/update-google-business-place-action-link https://api.bundle.social/swagger-json patch /api/v1/misc/google-business/location/place-action-links Body requires `fields` (`uri`, `placeActionType`, `isPreferred`). # Update Google Business regular/special/more hours Source: https://info.bundle.social/api-reference/client/misc/update-google-business-regularspecialmore-hours https://api.bundle.social/swagger-json patch /api/v1/misc/google-business/location/hours Body requires `fields` (`regularHours`, `specialHours`, `moreHours`). # Update Google Business service list Source: https://info.bundle.social/api-reference/client/misc/update-google-business-service-list https://api.bundle.social/swagger-json patch /api/v1/misc/google-business/location/service-list Body requires `fields` (`serviceItems`). # Get daily limits usage for one social account on a given day Source: https://info.bundle.social/api-reference/client/organization/get-daily-limits-usage-for-one-social-account-on-a-given-day https://api.bundle.social/swagger-json get /api/v1/organization/usage/daily-limits Check how many posts a single social account has already published on a specific day versus the platform's own daily cap. Use this to avoid hitting platform-side publishing limits. # Get DM and automation run usage per social account (paginated) Source: https://info.bundle.social/api-reference/client/organization/get-dm-and-automation-run-usage-per-social-account-paginated https://api.bundle.social/swagger-json get /api/v1/organization/usage/messages See how many direct messages and automation runs each Facebook, Instagram and TikTok account has used this UTC calendar month against its monthly limits, paginated with `offset`/`limit` and filterable by team, platform or account. Messages counted: every message you sent, including private replies to comments. Not counted: reactions, marking a conversation as read, and inbound messages. Automation runs counted: every run that was allowed to start, including manual test runs; skipped and canceled runs are not counted. Limits reflect per-account and organization overrides on top of the plan default. # Get organization Source: https://info.bundle.social/api-reference/client/organization/get-organization https://api.bundle.social/swagger-json get /api/v1/organization/ Retrieve your organization's details and plan. The `teams` field is deprecated and will be removed on 2026-11-15: to discover team IDs, use the paginated GET /api/v1/team. # Get organization comments usage Source: https://info.bundle.social/api-reference/client/organization/get-organization-comments-usage https://api.bundle.social/swagger-json get /api/v1/organization/usage/comments See how many comments your organization has consumed against its plan limit for the current billing period. # Get organization imports usage per social account (paginated) Source: https://info.bundle.social/api-reference/client/organization/get-organization-imports-usage-per-social-account-paginated https://api.bundle.social/swagger-json get /api/v1/organization/usage/imports See how much import capacity each social account has consumed, paginated and filterable by team or platform. Use it to track post history and review import quota. # Get organization posts usage Source: https://info.bundle.social/api-reference/client/organization/get-organization-posts-usage https://api.bundle.social/swagger-json get /api/v1/organization/usage/posts See how many posts your organization has consumed against its plan limit for the current billing period. Use it to monitor quota before scheduling large batches. # Get organization uploads usage Source: https://info.bundle.social/api-reference/client/organization/get-organization-uploads-usage https://api.bundle.social/swagger-json get /api/v1/organization/usage/uploads See how much upload capacity your organization has consumed against its plan limit for the current billing period. # Create post Source: https://info.bundle.social/api-reference/client/post/create-post https://api.bundle.social/swagger-json post /api/v1/post/ Schedule or immediately publish a post to one or more connected social accounts in a single request. Supply shared content plus optional per-platform overrides for captions, media, and platform-specific options. # Delete post Source: https://info.bundle.social/api-reference/client/post/delete-post https://api.bundle.social/swagger-json delete /api/v1/post/{id} Permanently delete a post from bundle.social. Deleting a scheduled post cancels it; deleting an already-published post does not remove it from the social platform. # Get post Source: https://info.bundle.social/api-reference/client/post/get-post https://api.bundle.social/swagger-json get /api/v1/post/{id} Retrieve a single post by ID, including its per-platform status, scheduled time, media, and any publishing errors. # Get post by reference key Source: https://info.bundle.social/api-reference/client/post/get-post-by-reference-key https://api.bundle.social/swagger-json get /api/v1/post/reference-key/{referenceKey} Retrieve a single post using your own reference key instead of the bundle.social post ID. Useful when you store your own identifier on create and want to look the post up later without keeping a mapping table. # Get post list Source: https://info.bundle.social/api-reference/client/post/get-post-list https://api.bundle.social/swagger-json get /api/v1/post/ List and filter posts across a team by status, platform, or date range with pagination. Use this to build a content calendar or reconcile your own database with bundle.social. # Get posts that can be reconnected to a social account Source: https://info.bundle.social/api-reference/client/post/get-posts-that-can-be-reconnected-to-a-social-account https://api.bundle.social/swagger-json get /api/v1/post/reconnect-social-account/candidates List posts that lost their link to a social account after a disconnect, and that can be reattached to a newly connected account of the same platform. # Reconnect social account to matching posts Source: https://info.bundle.social/api-reference/client/post/reconnect-social-account-to-matching-posts https://api.bundle.social/swagger-json post /api/v1/post/reconnect-social-account Reattach a newly connected social account to posts that were orphaned when the previous account was disconnected, so scheduled posts publish instead of failing. # Retry post Source: https://info.bundle.social/api-reference/client/post/retry-post https://api.bundle.social/swagger-json post /api/v1/post/{id}/retry Re-attempt publishing a post that failed, for example after a token expired or a platform outage. Fix the underlying cause first, then retry. # Update post Source: https://info.bundle.social/api-reference/client/post/update-post https://api.bundle.social/swagger-json patch /api/v1/post/{id} Change the content, media, scheduled time, or target platforms of a post that has not published yet. Only the fields you send are modified. # Create post CSV import Source: https://info.bundle.social/api-reference/client/postcsv/create-post-csv-import https://api.bundle.social/swagger-json post /api/v1/post-csv-import/ Upload CSV for async bulk post import. # Get post CSV import details Source: https://info.bundle.social/api-reference/client/postcsv/get-post-csv-import-details https://api.bundle.social/swagger-json get /api/v1/post-csv-import/{importId} Retrieve a single CSV import with its summary counts and configuration. # Get post CSV import history Source: https://info.bundle.social/api-reference/client/postcsv/get-post-csv-import-history https://api.bundle.social/swagger-json get /api/v1/post-csv-import/ List your team's bulk CSV post imports with pagination, so you can see what was uploaded and when. # Get post CSV import processing status Source: https://info.bundle.social/api-reference/client/postcsv/get-post-csv-import-processing-status https://api.bundle.social/swagger-json get /api/v1/post-csv-import/{importId}/status Poll the progress of a bulk CSV post import, including how many rows are processed, succeeded, and failed. # Get post CSV import row results Source: https://info.bundle.social/api-reference/client/postcsv/get-post-csv-import-row-results https://api.bundle.social/swagger-json get /api/v1/post-csv-import/{importId}/rows List the per-row outcome of a CSV import with pagination, showing which rows created posts and which failed validation and why. Use it to report errors back to the person who uploaded the file. # Bulk delete imported posts and their analytics Source: https://info.bundle.social/api-reference/client/postimport/bulk-delete-imported-posts-and-their-analytics https://api.bundle.social/swagger-json delete /api/v1/post-history-import/posts Permanently delete up to 100 imported historical posts and their analytics in one request, freeing import capacity. # Get import by ID Source: https://info.bundle.social/api-reference/client/postimport/get-import-by-id https://api.bundle.social/swagger-json get /api/v1/post-history-import/{importId} Check the status, progress, and result of a single post history import job. # Get import status list Source: https://info.bundle.social/api-reference/client/postimport/get-import-status-list https://api.bundle.social/swagger-json get /api/v1/post-history-import/ List post history import jobs for a team so you can monitor which backfills are queued, running, finished, or failed. # Get imported posts with analytics for a social account Source: https://info.bundle.social/api-reference/client/postimport/get-imported-posts-with-analytics-for-a-social-account https://api.bundle.social/swagger-json get /api/v1/post-history-import/posts List the historical posts pulled in by an import, with their analytics and your remaining import capacity. Use it to report on performance from before the account was connected. # Retry a failed import Source: https://info.bundle.social/api-reference/client/postimport/retry-a-failed-import https://api.bundle.social/swagger-json post /api/v1/post-history-import/{importId}/retry Re-run a post history import that failed, for example after a token expired or the platform rate-limited the request. # Start a new post history import Source: https://info.bundle.social/api-reference/client/postimport/start-a-new-post-history-import https://api.bundle.social/swagger-json post /api/v1/post-history-import/ Kick off an asynchronous import that backfills posts a social account published before it was connected to bundle.social, together with their analytics. Use it to get historical reporting from day one. # Connect social account for team Source: https://info.bundle.social/api-reference/client/socialaccount/connect-social-account-for-team https://api.bundle.social/swagger-json post /api/v1/social-account/connect Generate OAuth URL for social account connection. Redirect user to this URL to connect social account. For Mastodon and Bluesky an unusable `serverUrl` returns 400 with the reason, while a reachable-but-failing instance returns 502. # Copy social accounts Source: https://info.bundle.social/api-reference/client/socialaccount/copy-social-accounts https://api.bundle.social/swagger-json post /api/v1/social-account/copy Copy connected social accounts from one team to another so you can reuse an existing authorization without sending the user through OAuth again. # Create portal link Source: https://info.bundle.social/api-reference/client/socialaccount/create-portal-link https://api.bundle.social/swagger-json post /api/v1/social-account/create-portal-link Simplify connect flow. Create a portal link which can be used to manage connected social accounts directly on bundle.social platform without implementing the logic on your side. # Disable DM messaging for a social account Source: https://info.bundle.social/api-reference/client/socialaccount/disable-dm-messaging-for-a-social-account https://api.bundle.social/swagger-json post /api/v1/social-account/messaging/disable Stop processing DMs for the account and narrow its Meta webhook subscription to what other features still need. Idempotent. Processing stops immediately; if Meta does not confirm the change the status is DISABLE_PENDING and the call returns 502, so it can be retried. # Disconnect social account from team Source: https://info.bundle.social/api-reference/client/socialaccount/disconnect-social-account-from-team https://api.bundle.social/swagger-json delete /api/v1/social-account/disconnect This will remove the social account from all the scheduled posts too. # Enable DM messaging for a social account Source: https://info.bundle.social/api-reference/client/socialaccount/enable-dm-messaging-for-a-social-account https://api.bundle.social/swagger-json post /api/v1/social-account/messaging/enable Subscribe the team's Facebook page or Instagram account to Meta DM webhooks and start processing its messages. Connecting or re-authorizing an account never does this on its own. Idempotent. Returns 403 when the organization has not been granted Instagram and Facebook direct messages and automations (email contact@bundle.social to request it), 400 when the account lacks the messaging permissions (reconnect it), and 502 when Meta rejects the subscription; the account then stays DISABLED. # Get paginated social accounts scheduled to delete Source: https://info.bundle.social/api-reference/client/socialaccount/get-paginated-social-accounts-scheduled-to-delete https://api.bundle.social/swagger-json get /api/v1/social-account/to-delete List social accounts queued for deletion, with pagination. Use it to warn users before an account and its data are permanently removed. # Get social account by team and type Source: https://info.bundle.social/api-reference/client/socialaccount/get-social-account-by-team-and-type https://api.bundle.social/swagger-json get /api/v1/social-account/by-type Look up a team's connected account for a specific platform without listing every account first. Useful when you already know which platform you want to publish to. # Manually refresh social account profile info Source: https://info.bundle.social/api-reference/client/socialaccount/manually-refresh-social-account-profile-info https://api.bundle.social/swagger-json post /api/v1/social-account/profile-refresh Pull the latest profile name, handle, and avatar from the platform for a connected account. Use it to keep your own UI in sync after a user renames their profile. # Manually run connection/disconnect check Source: https://info.bundle.social/api-reference/client/socialaccount/manually-run-connectiondisconnect-check https://api.bundle.social/swagger-json post /api/v1/social-account/connection-check Force an immediate check of whether a social account's authorization is still valid, instead of waiting for the scheduled check. Use it to surface expired tokens before a scheduled post fails. # Refresh channels for social account Source: https://info.bundle.social/api-reference/client/socialaccount/refresh-channels-for-social-account https://api.bundle.social/swagger-json post /api/v1/social-account/refresh-channels Refresh channels saved on socialAccount.channels. This is only needed for some social account types - Reddit, Discord, Slack, Pinterest. # Set channel for social account Source: https://info.bundle.social/api-reference/client/socialaccount/set-channel-for-social-account https://api.bundle.social/swagger-json post /api/v1/social-account/set-channel Needed only for some social account types - Youtube, Instagram, Facebook, Linkedin, Google Business and Snapchat connected with the BUSINESS method. # Unset channel for social account Source: https://info.bundle.social/api-reference/client/socialaccount/unset-channel-for-social-account https://api.bundle.social/swagger-json post /api/v1/social-account/unset-channel Clear selected channel while keeping social account authorization. # Create new team Source: https://info.bundle.social/api-reference/client/team/create-new-team https://api.bundle.social/swagger-json post /api/v1/team/ Create a new team in your organization. Create one team per brand, client, or workspace you want to keep separate, then connect social accounts to it. # Delete team Source: https://info.bundle.social/api-reference/client/team/delete-team https://api.bundle.social/swagger-json delete /api/v1/team/{id} Permanently delete a team along with its connected social accounts, posts, and uploads. This cannot be undone. # Get list of teams Source: https://info.bundle.social/api-reference/client/team/get-list-of-teams https://api.bundle.social/swagger-json get /api/v1/team/ List the teams in your organization with pagination. Use this to discover team IDs, which are required by most publishing and analytics endpoints. # Get team Source: https://info.bundle.social/api-reference/client/team/get-team https://api.bundle.social/swagger-json get /api/v1/team/{id} Retrieve a single team with its connected social accounts and settings. Teams are the container that social accounts, posts, and uploads belong to. # Update team Source: https://info.bundle.social/api-reference/client/team/update-team https://api.bundle.social/swagger-json patch /api/v1/team/{id} Update a team's name, avatar, time zone, or other settings. Only the fields you send are changed. # Abort multipart upload Source: https://info.bundle.social/api-reference/client/upload/abort-multipart-upload https://api.bundle.social/swagger-json post /api/v1/upload/multipart/abort Discard an unfinished multipart upload and its parts. Call this when you give up on an upload — abandoned parts stay in storage and count against your usage. # Complete multipart upload Source: https://info.bundle.social/api-reference/client/upload/complete-multipart-upload https://api.bundle.social/swagger-json post /api/v1/upload/multipart/complete Assemble the uploaded parts into the final object and add it to your media library. Send every part with the ETag returned by its PUT. A 500 is always retryable — whatever we have (your parts, or the assembled object) is kept, so retry this call rather than re-uploading. A 400 is final: either the part list was wrong, or the file itself was rejected (empty, wrong type, too large, no readable preview) and its bytes have been deleted. A 403 means quota or permissions and is raised before assembly, so your parts are still open — call abort yourself. Calling this again after it already succeeded returns the same upload instead of charging you twice. # Create upload Source: https://info.bundle.social/api-reference/client/upload/create-upload https://api.bundle.social/swagger-json post /api/v1/upload/ Upload a file. This is the only endpoint that uses multipart/form-data. # Create upload from URL Source: https://info.bundle.social/api-reference/client/upload/create-upload-from-url https://api.bundle.social/swagger-json post /api/v1/upload/from-url Add an image or video to your media library by giving bundle.social a public URL to fetch, instead of uploading the bytes yourself. Useful when your media already lives in a CDN or S3 bucket. # Delete many uploads Source: https://info.bundle.social/api-reference/client/upload/delete-many-uploads https://api.bundle.social/swagger-json delete /api/v1/upload/ Permanently delete several media files in one request. Use it to clean up your library in bulk instead of calling delete per file. # Delete upload Source: https://info.bundle.social/api-reference/client/upload/delete-upload https://api.bundle.social/swagger-json delete /api/v1/upload/{id} Permanently delete a single media file from your library. Files still attached to scheduled posts should be replaced first. # Finalize large upload Source: https://info.bundle.social/api-reference/client/upload/finalize-large-upload https://api.bundle.social/swagger-json post /api/v1/upload/finalize Finalize large upload. # Get upload Source: https://info.bundle.social/api-reference/client/upload/get-upload https://api.bundle.social/swagger-json get /api/v1/upload/{id} Retrieve a single media file with its processing status, dimensions, duration, and the posts it is attached to. # Get upload list Source: https://info.bundle.social/api-reference/client/upload/get-upload-list https://api.bundle.social/swagger-json get /api/v1/upload/ List the media files in your team's library, newest first. Each file carries `posts`, the links to the posts using it — pass `includePosts=false` to leave them out. Page with `limit` and `offset`. To check whether specific files already exist, filter by `ids` or `urls` instead of listing everything. # Initialize large upload Source: https://info.bundle.social/api-reference/client/upload/initialize-large-upload https://api.bundle.social/swagger-json post /api/v1/upload/init Initialize large upload, you need to initialize a large upload if your file is larger than 90 MB. # Initialize multipart upload Source: https://info.bundle.social/api-reference/client/upload/initialize-multipart-upload https://api.bundle.social/swagger-json post /api/v1/upload/multipart/init Start a multipart upload. Required above the 5 GiB single-request storage limit that /upload/init is bound by, and allowed for any smaller file too. Returns an uploadId plus one presigned URL per part; PUT each part, keep the ETag response header, then call complete with the full part list. Parts are 64 MiB each except the last, up to 10000 parts. # Re-sign multipart upload parts Source: https://info.bundle.social/api-reference/client/upload/re-sign-multipart-upload-parts https://api.bundle.social/swagger-json post /api/v1/upload/multipart/sign Issue fresh presigned URLs for parts whose original URLs expired mid-upload. Parts already uploaded keep their ETags — only re-upload the ones that failed. # Comments Source: https://info.bundle.social/api-reference/comments Import comments from published posts, show them in your app, and reply in the right thread. > [!NOTE] > > Comment import works for posts published through bundle.social and for posts returned by [Post History Import](/api-reference/import-posts). Use exactly one of `postId` or `importedPostId`. > [!NOTE] > > **Real-time comments on any post.** With [Direct Messages or Automations](/api-reference/automations) turned on, new comments on Instagram, Facebook and TikTok arrive on their own, including comments on posts published directly on the platform. Such a post gets an `importedPostId` when its first comment arrives (or keeps the one from Post History Import). It comes in the `comment.received` [webhook](/api-reference/automations/webhooks) as `comment.importedPostId`, and you can use it to list the post's comments with `GET /api/v1/comment/import/comments` and to reply to them. These posts don't count toward your post import limit. With the Comments API you can: * import comments from a published post, * display comments as a real thread, * reply to imported comments on the original platform, * keep your comments list fresh after new activity. ## Supported Platforms Comment import is available for: * `FACEBOOK` * `INSTAGRAM` * `LINKEDIN` * `YOUTUBE` * `TIKTOK` * `REDDIT` * `THREADS` * `MASTODON` * `BLUESKY` * `TWITTER` Comment creation is available for: * `FACEBOOK` * `INSTAGRAM` * `LINKEDIN` * `YOUTUBE` * `TIKTOK` * `REDDIT` * `THREADS` * `MASTODON` * `DISCORD` * `SLACK` * `BLUESKY` * `TWITTER` > [!NOTE] > > On Twitter / X, importing replies and posting a reply are billed from your prepaid X credits at X's own API prices. See [X billing](/api-reference/platforms/twitter#billing). Pinterest and Google Business are not supported for comment creation or comment import. ### Comment Text Limits | Platform | Field | Limit | | :- | :- | :- | | `FACEBOOK` | `data.FACEBOOK.text` | 8,000 characters | | `INSTAGRAM` | `data.INSTAGRAM.text` | 2,200 characters | | `LINKEDIN` | `data.LINKEDIN.text` | 1,250 characters | | `YOUTUBE` | `data.YOUTUBE.text` | 10,000 characters | | `TIKTOK` | `data.TIKTOK.text` | 1,200 characters | | `REDDIT` | `data.REDDIT.text` | 10,000 characters | | `THREADS` | `data.THREADS.text` | 500 characters | | `MASTODON` | `data.MASTODON.text` | 500 characters | | `DISCORD` | `data.DISCORD.text` | 2,000 characters | | `SLACK` | `data.SLACK.text` | 30,000 characters | | `BLUESKY` | `data.BLUESKY.text` | 300 characters | | `TWITTER` | `data.TWITTER.text` | 280 characters, 25,000 for Premium accounts | *** ## Before You Start Use this quick checklist first: 1. You already connected a social account to the team. 2. The post was published through bundle.social or fetched through Post History Import. 3. You have: * `teamId` * `postId` or `importedPostId` * `socialAccountType` If one of these is missing, import will fail with validation error. *** ## Flow of comments API Think about import as a small background job: 1. User clicks "Import comments". 2. Your app starts the import job on bundle. 3. Your app checks status every 5/10 seconds. 4. When completed, your app fetches comments and renders the thread. ### Step 1: Start Import **Endpoint:** `POST /api/v1/comment/import` ```json theme={null} { "teamId": "team_123", "importedPostId": "profile_post_123", "socialAccountType": "INSTAGRAM" } ``` `postId` and `importedPostId` are mutually exclusive. Send `postId` for a post created in bundle.social, or `importedPostId` for a historical post returned by the import API. ### Why Import Can Be Rejected Import start can return validation errors if: * post does not belong to this team, * post is not published to selected platform yet, * this team has no connected account for that platform, * there is already an active import for this same post and platform. If import is already running, you get `409`. ### Step 2: Track Progress **Endpoints:** * `GET /api/v1/comment/import?teamId=...&postId=...` * `GET /api/v1/comment/import?teamId=...&importedPostId=...` * `GET /api/v1/comment/import/:importId` Use these statuses for user-facing UI: | Status | What to show to user | | :- | :- | | `PENDING` | "Waiting in queue" | | `FETCHING` | "Importing comments..." | | `RETRYING` | "Retrying after temporary issue" | | `RATE_LIMITED` | "Platform limit reached. We will retry automatically." | | `COMPLETED` | "Import complete" | | `FAILED` | "Import failed. Try again later." | | `SKIPPED` | "Import skipped" | ### Step 3: Get Imported Comments **Endpoint:** `GET /api/v1/comment/import/comments` Query params: * `teamId` (required) * exactly one of `postId` or `importedPostId` (required) * `platform` (optional) * `socialAccountId` (optional) * `limit`, `offset` Example response: ```json theme={null} { "items": [ { "id": "fetched_1", "platform": "INSTAGRAM", "externalId": "18001234567890", "externalParentId": null, "text": "Top level comment", "authorName": "janedoe", "likesCount": 12, "repliesCount": 2, "publishedAt": "2026-04-13T09:30:00.000Z" }, { "id": "fetched_2", "platform": "INSTAGRAM", "externalId": "18001234567999", "externalParentId": "18001234567890", "text": "Reply comment", "authorName": "bundle_user", "likesCount": 1, "repliesCount": 0, "publishedAt": "2026-04-13T09:35:00.000Z" } ], "total": 2 } ``` *** ## What Exactly Gets Imported Each imported comment includes: * `externalId`: unique platform comment ID. * `externalParentId`: parent comment ID on platform, or `null` for top-level. * `externalPostId`: platform post ID. * author metadata: `authorName`, `authorExternalId`, `authorProfileUrl`, `authorAvatarUrl`. * content and stats: `text`, `likesCount`, `repliesCount`, `publishedAt`. Important detail: * the API returns a flat list, * your app rebuilds thread hierarchy using `externalParentId`. *** ## How To Display Comments In Your App ### Plain-Language Rule If `externalParentId` is empty, this is top-level comment. If `externalParentId` points to another `externalId`, this is a reply. ### Recommended Rendering Steps 1. Create `externalId -> comment` map. 2. Group comments by `externalParentId`. 3. Start from root comments. 4. Attach children recursively. ```ts theme={null} type C = { externalId: string; externalParentId: string | null }; function buildTree(comments: C[]) { const byId = new Map(comments.map((c) => [c.externalId, c])); const byParent = new Map(); for (const c of comments) { const arr = byParent.get(c.externalParentId) ?? []; arr.push(c); byParent.set(c.externalParentId, arr); } const roots = comments.filter((c) => c.externalParentId === null || !byId.has(c.externalParentId)); const visit = (node: C): any => ({ ...node, children: (byParent.get(node.externalId) ?? []).map(visit), }); return roots.map(visit); } ``` > [!NOTE] > > Sometimes platform APIs do not return full parent mapping for every nested reply. If parent is missing, treat this comment as root and still show it. *** ## Replying To Imported Comments To reply to imported comment, create normal comment with `fetchedParentCommentId`. **Endpoint:** `POST /api/v1/comment` Minimal body: ```json theme={null} { "teamId": "team_123", "fetchedParentCommentId": "fetched_1", "text": "Thanks for your comment!" } ``` ### What Happens After You Send Reply 1. API resolves correct platform and post from fetched parent. 2. New comment is saved with `SCHEDULED` status. 3. Queue publishes it to platform. 4. Status becomes `POSTED` or `ERROR`. ## Creating A Top-Level Comment For first comments or top-level comments on a post published through bundle.social, provide the post, schedule fields, target platforms, and platform-specific comment text. **Endpoint:** `POST /api/v1/comment` ```json theme={null} { "teamId": "team_123", "internalPostId": "post_123", "title": "First comment", "status": "SCHEDULED", "postDate": "2026-06-01T15:05:00.000Z", "socialAccountTypes": ["INSTAGRAM"], "data": { "INSTAGRAM": { "text": "Link is in the bio. Thanks for watching!" } } } ``` For `internalParentCommentId`, the reply is linked to a comment already created through bundle.social. For `fetchedParentCommentId`, the platform and post are inferred from the imported comment, so a minimal reply can use only `teamId`, `fetchedParentCommentId`, and `text`. For a top-level comment on a historical post, replace `internalPostId` with `importedPostId`. Do not send both fields. ## List Created Comments **Endpoint:** `GET /api/v1/comment` `teamId` is required. Optional filters include `postId`, `importedPostId`, `status`, `q`, `platforms`, `orderBy`, `order`, `offset`, and `limit`. Use this endpoint for comments created through bundle.social; use `/comment/import/comments` for comments fetched from a platform. ## Actions On Fetched Comments **Endpoint:** `POST /api/v1/comment/import/comments/:commentId/action` ```json theme={null} { "teamId": "team_123", "action": "HIDE", "reason": "Optional moderation note" } ``` Available actions depend on the platform and the permissions reported in `platformData`: | Platform | Actions | | :- | :- | | Facebook, Instagram | `DELETE`, `HIDE`, `UNHIDE` | | LinkedIn, Mastodon | `DELETE`, `LIKE`, `UNLIKE` | | YouTube, Reddit | `DELETE`, `APPROVE`, `REJECT` | | TikTok | `DELETE`, `HIDE`, `UNHIDE`, `LIKE`, `UNLIKE` | | Bluesky | `DELETE` | | Threads | No fetched-comment actions | Check `platformData.canDelete`, `canHide`, `canLike`, and `canModerate` before showing controls. The platform can still reject an action if the connected account does not own or moderate the target comment. For YouTube `APPROVE` or `REJECT`, optional `banAuthor: true` asks YouTube to ban the comment author as part of the moderation action. ## Retry A Failed Comment **Endpoint:** `POST /api/v1/comment/:id/retry` Use this for a comment whose status is `ERROR`. A successful retry returns the comment to the publishing queue. Comments in any other status return `400`. ## Limits Explained ### Per Import Storage Limit (Per Post) Import always runs, but stored comments are capped for each run. | Tier | Max stored comments per post import | | :- | :- | | FREE | 25 | | PRO | 200 | | BUSINESS | 1000 | How this works in practice: * if platform has 900 comments and your cap is 200, * import completes successfully, * newest 200 are stored in this run. ### Is There a Monthly Comment Import Quota? No. Comment import does not use monthly counters. Limit is per run and per post. ### Reply Text Limits By Platform | Platform | Max text length | | :- | :- | | FACEBOOK | 8000 | | INSTAGRAM | 2200 | | LINKEDIN | 1250 | | YOUTUBE | 10000 | | TIKTOK | 1200 | | REDDIT | 10000 | | THREADS | 500 | | MASTODON | 500 | | BLUESKY | 300 | | TWITTER | 280 (25000 for Premium accounts) | *** For global API rate limits, see [Rate Limits](/api-reference/rate-limits). *** ## Quick FAQ ### "Why comments list is empty?" Most common reasons: * post was not published to selected platform, * import still running, * no comments yet on that post. ### "Why does creating a comment fail?" * `404 Post not found or does not belong to this team` - the `internalPostId` doesn't exist, belongs to another team, or the post was deleted. * `Post is not published on yet` - a top-level comment needs the published post. Wait until the post is `POSTED` (or reply to an existing comment instead). * `No text provided to create comment` - the comment has no text for that platform. * `Slack/Discord channel for this post is unknown` - replying to an imported Slack or Discord post isn't supported, since the import doesn't carry its channel. ### "Why I see comment without parent?" Because parent mapping from platform was not returned in this fetch window. Show as root and keep it visible. ### "Do I need webhooks for comment import?" No. Comment import is pull-based. You trigger it and then fetch results. ### "Will you have webhooks for this?" For live comment nortification? No, kinda not our limitation. For import status, yes in the future. # Connect Social Accounts Source: https://info.bundle.social/api-reference/connect-social-accounts Learn how OAuth, hosted connect links, custom connect flows, and channel selection work in bundle.social. Connecting social accounts has two separate parts: 1. **OAuth:** the user grants bundle.social access to the platform account. 2. **Channel selection:** bundle.social selects the exact Page, channel, organization, location, board, subreddit, or workspace target to use for this team. Most integration bugs happen when these steps get mixed together. OAuth says "this Meta user granted access." Channel selection says "this team should use this Facebook Page." > [card] [Hosted Flow](/api-reference/connect-social-accounts/hosted-flow) > > Create a portal link and let bundle.social handle OAuth, pickers, language, and UI. > [card] [Custom UI Flow](/api-reference/connect-social-accounts/custom-ui-flow) > > Build the account picker yourself and call the connect and channel endpoints directly. > [card] [Channel Management](/api-reference/connect-social-accounts/channel-management) > > Use `set-channel`, `refresh-channels`, and `unset-channel` for platforms with multiple targets. > [card] [OAuth Options](/api-reference/connect-social-accounts/oauth-options) > > Understand `disableAutoLogin`, `forceBrowserOAuth`, `withBusinessScope`, and Instagram connection methods. > [card] [Callback Parameters](/api-reference/connect-social-accounts/callbacks) > > Handle success and error query parameters after OAuth completes. *** ## Which Flow Should I Use? | Flow | Best for | What you build | | :- | :- | :- | | Hosted flow | Most apps | A button that opens the portal link | | Custom UI flow | Apps that need a fully custom account connection UI | OAuth button, callback handling, channel picker, and reconnect states | > [!TIP] > > Use the hosted flow unless you have a strong reason to own the whole connection UI. *** ## The Meta Rule For **Facebook** and **Instagram via Facebook**, ask the user to select **all Pages and Instagram accounts they manage** in the Meta OAuth screen. After OAuth, choose the one Page or Instagram account for the current bundle.social team in the hosted picker or with `POST /api/v1/social-account/set-channel`. This does **not** mean one team publishes to every Page. Meta keeps the app grant for every Page the user manages, while bundle.social stores the selected target separately per team. > [!WARNING] > > If the same Meta user connects multiple bundle.social teams and selects only one Page during each OAuth flow, Meta can overwrite page grants for the bundle.social app at the Meta-user level. > > That can leave one team looking connected in bundle.social, while Meta has removed the Page grant remotely. Publishing can then fail with `must be granted before impersonating a user's page`. Correct flow: 1. Reconnect Facebook or Instagram via Facebook. 2. In Meta OAuth, choose **Select all** or manually select every Page and Instagram account the Meta user manages. 3. Back in bundle.social, select the one Page or Instagram account for this team. 4. Retry the failed post. *** ## Platform Selection Rules | Platform | OAuth enough? | Needs `set-channel`? | Notes | | :- | :- | :- | :- | | Facebook | No | Yes | Select a Facebook Page. | | Instagram via Facebook | No | Yes | Select an Instagram account connected to a Facebook Page. | | Instagram direct OAuth | Yes | No | Pass `instagramConnectionMethod: "INSTAGRAM"` in custom UI. | | LinkedIn | No | Yes | Select a member profile or Company Page. | | YouTube | No | Yes | Select a YouTube channel. | | Snapchat (`PERSONAL`, default) | Yes | No | Uses the Public Profile returned during OAuth. | | Snapchat (`BUSINESS`) | No | Yes | Select a Public Profile of the login's Snap Business organizations. See [Snapchat](/api-reference/platforms/snapchat#connection-methods). | | Google Business | No | Yes | Select a business location. | | Pinterest | Usually yes | No | Boards can be refreshed with `refresh-channels`. | | Reddit | Usually yes | No | Destinations can be refreshed with `refresh-channels`. | | Slack | Usually yes | No | Webhook channels can be refreshed with `refresh-channels`. | | Discord | Usually yes | No | Webhook channels can be refreshed with `refresh-channels`. | Need endpoint details? Start with [Hosted Flow](/api-reference/connect-social-accounts/hosted-flow) or [Custom UI Flow](/api-reference/connect-social-accounts/custom-ui-flow). # Callback Parameters Source: https://info.bundle.social/api-reference/connect-social-accounts/callbacks Handle success and error query parameters after social account OAuth completes. Whether you use hosted or custom UI, the user eventually comes back to your `redirectUrl` with query parameters. *** ## Success Callbacks | Parameter | Message | | :- | :- | | `twitter-callback` | Twitter connected successfully | | `pinterest-callback` | Pinterest connected successfully | | `tiktok-callback` | TikTok connected successfully | | `facebook-callback` | Facebook connected successfully | | `instagram-callback` | Instagram connected successfully | | `linkedin-callback` | LinkedIn connected successfully | | `reddit-callback` | Reddit connected successfully | | `discord-callback` | Discord connected successfully | | `slack-callback` | Slack connected successfully | | `youtube-callback` | YouTube connected successfully | | `snapchat-callback` | Snapchat Public Profile connected successfully | | `threads-callback` | Threads connected successfully | | `mastodon-callback` | Mastodon connected successfully | | `bluesky-callback` | Bluesky connected successfully | | `google-business-callback` | Google Business connected successfully | *** ## Error Callbacks | Platform | Parameter | Message | | :- | :- | :- | | Twitter/X | `twitter-callback` | Error connecting Twitter | | Twitter/X | `twitter-not-enough-permissions` | User did not grant all required permissions | | Pinterest | `pinterest-callback` | Error connecting Pinterest | | Pinterest | `pinterest-not-enough-permissions` | User did not grant all required permissions | | TikTok | `tiktok-callback` | Error connecting TikTok | | TikTok | `tiktok-not-enough-permissions` | User did not grant all required permissions | | Facebook | `facebook-callback` | Error connecting Facebook | | Facebook | `facebook-not-enough-pages` | User does not have enough permissions on any Facebook Pages | | Facebook | `facebook-not-enough-permissions` | User did not grant all required permissions | | Instagram | `instagram-callback` | Error connecting Instagram | | Instagram | `instagram-direct-callback` | Error connecting Instagram through direct OAuth (`instagramConnectionMethod: "INSTAGRAM"`) | | Instagram | `instagram-not-enough-accounts` | User does not have enough permissions on any Instagram account, or no Facebook Page has an Instagram account connected | | Instagram | `instagram-not-enough-permissions` | User did not grant all required permissions (Instagram login: the content publish permission is required) | | Instagram | `instagram-reconnect-different-account` | A `reconnect` flow was completed with a different Instagram account than the one connected | | Instagram | `instagram-not-professional-account` | Instagram account is not a Professional or Creator account | | LinkedIn | `linkedin-callback` | Error connecting LinkedIn | | LinkedIn | `linkedin-not-enough-channels` | User does not have enough permissions on any LinkedIn organizations | | LinkedIn | `linkedin-not-enough-permissions` | User did not grant all required permissions | | Reddit | `reddit-callback` | Error connecting Reddit | | Reddit | `reddit-not-enough-permissions` | User did not grant all required permissions | | Discord | `discord-callback` | Error connecting Discord | | Discord | `discord-not-enough-servers` | User does not have enough permissions on any Discord servers | | Discord | `discord-not-enough-permissions` | User did not grant all required permissions | | Slack | `slack-callback` | Error connecting Slack | | Slack | `slack-not-enough-workspaces` | User does not have enough permissions on any Slack workspaces | | Slack | `slack-not-enough-permissions` | User did not grant all required permissions | | YouTube | `youtube-callback` | Error connecting YouTube | | YouTube | `youtube-not-enough-channels` | User does not have enough permissions on any YouTube channels | | YouTube | `youtube-not-enough-permissions` | User did not grant all required permissions | | Snapchat | `snapchat-callback` | Error connecting Snapchat | | Snapchat | `snapchat-no-business-profiles` | Connected with `BUSINESS`, but the login has no Admin or Collaborator role on any Public Profile of its Snap Business organizations | | Snapchat | `snapchat-not-enough-permissions` | User did not grant the required Public Profile permissions | | Snapchat | `snapchat-no-public-profile` | The Snapchat login has no Public Profile. Create one in the Snapchat app, or log in with the account that owns it | | Threads | `threads-callback` | Error connecting Threads | | Threads | `threads-not-enough-permissions` | User did not grant all required permissions | | Mastodon | `mastodon-callback` | Error connecting Mastodon | | Mastodon | `mastodon-not-enough-permissions` | User did not grant all required permissions | | Bluesky | `bluesky-callback` | Error connecting Bluesky | | Bluesky | `bluesky-not-enough-permissions` | User did not grant all required permissions | | Google Business | `google-business-callback` | Error connecting Google Business | | Google Business | `google-business-not-enough-permissions` | User did not tick the "See, edit, create and delete your Google business listings" permission on Google's consent screen | > [!TIP] > > Handle `not-enough-permissions` gracefully. Tell the user the permissions are required for publishing, then let them reconnect. *** ## Error Reasons (Facebook And Instagram) When a Facebook or Instagram (through Facebook) connection finds no Page to publish to, the error stays `facebook-not-enough-pages` or `instagram-not-enough-accounts`, and an extra `errorReason` parameter says why. It's optional, so fall back to the error message when it's missing. ``` https://your-app.com/connect?error=facebook-not-enough-pages&errorReason=facebook-two-factor-required ``` | `errorReason` | What happened | What to tell the user | | :- | :- | :- | | `facebook-two-factor-required` | The business portfolio requires two-factor authentication and the Facebook session didn't pass it. | Log out of Facebook, log back in with the security code, then connect again. | | `facebook-page-token-withheld` | Meta listed the Page but gave no access to it: it was deselected on the consent screen, or the portfolio requires two-factor authentication. | Connect again and select the Page. If the portfolio uses two-factor authentication, log out of Facebook and back in with the security code first. | | `facebook-no-publish-access` | Pages were found, but the user can't create content on any of them. | Ask a Page admin for full control or content access. | | `facebook-business-access-required` | Nothing was found with Standard access. | Connect again and select the Page. If it belongs to a business portfolio, choose Business access. | | `facebook-business-permission-declined` | Business access was chosen, but the business management permission was turned off. | Connect again and leave that permission on. | | `facebook-no-pages-found` | No Page is assigned to this Facebook profile. | Check the right profile is logged in, the Page is assigned to them in the business portfolio, and it was selected when connecting. | Pages that Meta lists without a Page token are no longer offered for selection, because publishing to them would fail later. They count as `facebook-page-token-withheld`. **Refresh channels:** if refreshing a Facebook account's channels finds no usable Page, the call returns `400` with the matching message above and keeps the stored channels, instead of saving an empty list. # Channel Management Source: https://info.bundle.social/api-reference/connect-social-accounts/channel-management Use set-channel, refresh-channels, and unset-channel for social accounts with selectable targets. Some platforms connect one user account first, then require you to pick the exact target for the team. Examples: Facebook Pages, Instagram accounts connected to Facebook Pages, LinkedIn organizations, YouTube channels, and Google Business locations. *** ## Set Channel Use `set-channel` after OAuth when a platform needs a selected Page, channel, organization, or location. **Endpoint:** `POST /api/v1/social-account/set-channel` ```json theme={null} { "type": "FACEBOOK", "teamId": "team_123", "channelId": "page_123" } ``` Use a `channelId` from `socialAccount.channels`. | Field | Required | Description | | :- | :- | :- | | `type` | Yes | One of `FACEBOOK`, `INSTAGRAM`, `LINKEDIN`, `YOUTUBE`, `GOOGLE_BUSINESS`. | | `teamId` | Yes | Team ID. | | `channelId` | Yes | ID from `socialAccount.channels`. | ### Platforms Requiring Set Channel | Platform | Target | | :- | :- | | Facebook | Facebook Page | | Instagram via Facebook | Instagram account connected to a Facebook Page | | LinkedIn | Member profile or Company Page / organization | | YouTube | YouTube channel | | Google Business | Business location | > [!WARNING] > > If you skip `set-channel` for a platform that requires it, the social account remains connected but has no selected publishing target (`externalId` is empty). Posts, comments, imports, analytics, and Google Business APIs can fail because bundle.social has no concrete Page/channel/location to act on. > [!NOTE] > > Direct Instagram OAuth (`instagramConnectionMethod: "INSTAGRAM"`) does not support `set-channel`. *** ## Meta Rule: Select All First For Facebook and Instagram via Facebook, users should select **all Pages and Instagram accounts they manage** in the Meta OAuth screen. Then your UI should show `socialAccount.channels` and call `set-channel` with the one Page or Instagram account for the current team. This avoids Meta overwriting page grants when the same Meta user connects different bundle.social teams with different Pages. *** ## Refresh Channels Use `refresh-channels` when `socialAccount.channels` may be stale. **Endpoint:** `POST /api/v1/social-account/refresh-channels` ```json theme={null} { "type": "PINTEREST", "teamId": "team_123" } ``` | Field | Required | Description | | :- | :- | :- | | `type` | Yes | One of the supported refresh platforms below. | | `teamId` | Yes | Team ID. | | Platform | What gets refreshed | | :- | :- | | Discord | Available webhook channels | | Slack | Available webhook channels | | Reddit | Available subreddits, user destinations, and metadata | | Pinterest | Boards | | Facebook | Pages | | Instagram via Facebook | Instagram accounts connected to Pages | | LinkedIn | Member profile and organizations | | YouTube | Channels | | Google Business | Locations | > [!NOTE] > > Direct Instagram OAuth does not support `refresh-channels`. *** ## Unset Channel Use `unset-channel` when the user picked the wrong target and wants to choose another one without a full reconnect. **Endpoint:** `POST /api/v1/social-account/unset-channel` ```json theme={null} { "type": "FACEBOOK", "teamId": "team_123" } ``` | Field | Required | Description | | :- | :- | :- | | `type` | Yes | One of `FACEBOOK`, `INSTAGRAM`, `LINKEDIN`, `YOUTUBE`, `GOOGLE_BUSINESS`. | | `teamId` | Yes | Team ID. | ### What Happens 1. The selected Page, channel, or location is cleared from the social account. 2. The OAuth connection stays intact. 3. The account is removed from all draft and scheduled posts. 4. Posts that only had this account become drafts. 5. `social-account.updated` and `team.updated` webhooks fire. ### Switch Flow 1. Call `POST /api/v1/social-account/unset-channel`. 2. Show the current `socialAccount.channels` list. 3. Call `POST /api/v1/social-account/set-channel` with the new target ID. > [!WARNING] > > Unsetting removes the account from all draft and scheduled posts. If a post only had this one account, it becomes a draft. # Custom UI Flow Source: https://info.bundle.social/api-reference/connect-social-accounts/custom-ui-flow Build your own social account connection flow using the connect endpoint, callbacks, and channel endpoints. Use custom UI when you want full control over account connection screens. You generate an OAuth URL, redirect the user, handle the callback, fetch the saved social account, and call channel endpoints when a platform needs a selected target. **Endpoint:** `POST /api/v1/social-account/connect` Test it in [Swagger](https://api.bundle.social/swagger#/socialAccount/socialAccount.connect) or the [API Reference Client](/api-reference/client/socialaccount/connect). ```json theme={null} { "type": "INSTAGRAM", "teamId": "team_123", "redirectUrl": "https://app.example.com/oauth/callback", "instagramConnectionMethod": "FACEBOOK", "disableAutoLogin": true, "withBusinessScope": true } ``` Response: ```json theme={null} { "url": "https://www.facebook.com/v..." } ``` Redirect the user to `url`. *** ## Connect Body These are the available body fields for the custom flow. | Field | Required | Description | | :- | :- | :- | | `type` | Yes | Platform to connect. See [Supported Types](#supported-types). | | `teamId` | Yes | Team that should receive the connected social account. | | `redirectUrl` | Yes | HTTP/HTTPS URL where the platform sends the user after OAuth. We append callback query parameters to this URL. | | `serverUrl` | Depends | Required for Mastodon. Optional issuer/server URL for Bluesky. | | `disableAutoLogin` | No | Adds provider-specific flags to avoid automatic login or silent account reuse where supported. Defaults to `false`. | | `tiktokForceLogin` | No | Experimental TikTok-only option. Routes authorization through TikTok logout to request a fresh login session. Defaults to `false`. | | `forceBrowserOAuth` | No | Instagram direct OAuth only. Instagram asks for a fresh login instead of reusing the account already logged in on that browser. Defaults to `false`. See [forceBrowserOAuth](/api-reference/connect-social-accounts/oauth-options#forcebrowseroauth). | | `instagramConnectionMethod` | No | Instagram only. Use `FACEBOOK` or `INSTAGRAM`. If omitted, the Facebook login path is used. | | `snapchatConnectionMethod` | No | Snapchat only. `PERSONAL` (default) or `BUSINESS`. See [Snapchat connection methods](/api-reference/platforms/snapchat#connection-methods). | | `withBusinessScope` | No | Facebook, Instagram via Facebook, and YouTube. Adds broader Meta business scopes for Meta, or the monetary analytics scope (revenue/monetization data) for YouTube, when `true`. Defaults to `false`. | ### Supported Types `TIKTOK`, `YOUTUBE`, `SNAPCHAT`, `INSTAGRAM`, `FACEBOOK`, `TWITTER`, `THREADS`, `LINKEDIN`, `PINTEREST`, `REDDIT`, `MASTODON`, `DISCORD`, `SLACK`, `BLUESKY`, `GOOGLE_BUSINESS` *** ## Platform-Specific Options | Option | Applies to | Notes | | :- | :- | :- | | `serverUrl` | Mastodon, Bluesky | Mastodon requires it. Bluesky can use it for a custom issuer/server. | | `instagramConnectionMethod: "FACEBOOK"` | Instagram | Uses Facebook Login and supports Page/account channel selection, comments, insights, locations, and Instagram audio search. | | `instagramConnectionMethod: "INSTAGRAM"` | Instagram | Uses direct Instagram OAuth. No `set-channel`, `unset-channel`, or `refresh-channels`. Some Facebook-backed features are not available. | | `snapchatConnectionMethod: "BUSINESS"` | Snapchat | Lists the Public Profiles of the login's Snap Business organizations. Needs `set-channel`. | | `disableAutoLogin` | Facebook, Instagram via Facebook, Instagram direct OAuth, TikTok | Helps users pick the correct platform account when many accounts are used in one browser. | | `tiktokForceLogin` | TikTok | Experimental stronger fresh-login flow. Redirects through TikTok logout before authorization. | | `forceBrowserOAuth` | Instagram direct OAuth | Makes Instagram ask for a fresh login instead of reusing the account logged in on that browser. | | `withBusinessScope` | Facebook, Instagram via Facebook, YouTube | Meta: can expose Pages and Instagram accounts hidden in the standard scope flow. YouTube: adds the monetary analytics scope that enables revenue/monetization data. Optional for YouTube - if not granted, the connection still succeeds and only monetization is unavailable. | > [!WARNING] > > For Facebook and Instagram via Facebook, ask users to select **all Pages and Instagram accounts they manage** in Meta OAuth. Then call `set-channel` for the one target this team should use. *** ## Basic Flow 1. Call `POST /api/v1/social-account/connect`. 2. Redirect the user to the returned `url`. 3. Handle the callback query parameters on your `redirectUrl`. 4. Fetch the social account with `GET /api/v1/social-account/by-type`. 5. If `socialAccount.channels` contains selectable targets, show them in your UI. 6. Call `POST /api/v1/social-account/set-channel` when required. Snapchat connected with `PERSONAL` (the default) uses the Public Profile returned by OAuth and needs no channel selection. With `BUSINESS`, pick a profile with `set-channel`. ![Connect social account flow](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/api-reference/connect-social-account/connect-social-account.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=abab69c85854962f34899fdc4b9f9d71) *** ## Fetch The Connected Account Use this after the callback to inspect the connection and available channels. **Endpoint:** `GET /api/v1/social-account/by-type` Query: | Field | Required | Description | | :- | :- | :- | | `type` | Yes | Platform type. | | `teamId` | Yes | Team ID. | ```http theme={null} GET /api/v1/social-account/by-type?type=FACEBOOK&teamId=team_123 ``` If the platform needs channel selection, read `socialAccount.channels` and call [Set Channel](/api-reference/connect-social-accounts/channel-management#set-channel). *** ## Helper Endpoints These endpoints are useful in a full custom UI. | Endpoint | Method | Use | | :- | :- | :- | | `/api/v1/social-account/disconnect` | `DELETE` | Disconnect a social account from the team. This also removes it from scheduled posts. | | `/api/v1/social-account/set-channel` | `POST` | Select a Page, channel, organization, or location after OAuth. | | `/api/v1/social-account/unset-channel` | `POST` | Clear the selected channel while keeping the OAuth connection. | | `/api/v1/social-account/refresh-channels` | `POST` | Refresh available targets saved in `socialAccount.channels`. | | `/api/v1/social-account/connection-check` | `POST` | Manually check whether a connected account is still valid. Requires a selected channel/account where the platform needs one. | | `/api/v1/social-account/profile-refresh` | `POST` | Manually refresh profile information for a connected social account. | | `/api/v1/social-account/by-type` | `GET` | Fetch the connected social account for a team and platform. | Channel details live in [Channel Management](/api-reference/connect-social-accounts/channel-management). Callback query parameters live in [Callback Parameters](/api-reference/connect-social-accounts/callbacks). # Hosted Flow Source: https://info.bundle.social/api-reference/connect-social-accounts/hosted-flow Create a hosted social account connect link and let bundle.social handle OAuth UI and channel selection. The hosted flow is the easiest way to connect accounts. You create a portal link, send the user there, and bundle.social handles the connect UI, provider OAuth, account picker, channel picker, language, and return flow. **Endpoint:** `POST /api/v1/social-account/create-portal-link` Test it in [Swagger](https://api.bundle.social/swagger#/socialAccount/socialAccount.createPortalLink) or the [API Reference Client](/api-reference/client/socialaccount/create-portal-link). ```json theme={null} { "teamId": "team_123", "redirectUrl": "https://app.example.com/settings/social-accounts", "socialAccountTypes": ["FACEBOOK", "INSTAGRAM"], "instagramConnectionMethod": "FACEBOOK", "disableAutoLogin": true, "withBusinessScope": true, "expiresIn": 60, "language": "en" } ``` Response: ```json theme={null} { "url": "https://bundle.social/connect?token=..." } ``` Redirect the user to `url`. *** ## Required Fields | Field | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team that should receive the connected social account. | | `socialAccountTypes` | Yes | Platforms available in the hosted flow. Uses values like `FACEBOOK`, `INSTAGRAM`, `LINKEDIN`, `YOUTUBE`. | `redirectUrl` is optional in the API contract, but you should provide it for normal app flows. It is the URL users return to after they click the back button. *** ## OAuth Behavior Fields | Field | Required | Description | | :- | :- | :- | | `redirectUrl` | No | HTTP/HTTPS URL to return to after the hosted flow. Recommended for most integrations. | | `serverUrl` | No | Mastodon or Bluesky server URL. Mastodon requires a server when it is offered in the portal. | | `disableAutoLogin` | No | Facebook, Instagram via Facebook, Instagram direct OAuth, and TikTok paths use this to avoid silently reusing the last logged-in platform session where supported. Defaults to `false`. | | `tiktokForceLogin` | No | Experimental TikTok-only option. Routes TikTok through logout to request a fresh login session. Defaults to `false`. | | `forceBrowserOAuth` | No | Instagram direct OAuth only. Instagram asks for a fresh login instead of reusing the account already logged in on that browser. In the hosted portal it applies only on iPhone/iPad. Defaults to `false`. See [forceBrowserOAuth](/api-reference/connect-social-accounts/oauth-options#forcebrowseroauth). | | `instagramConnectionMethod` | No | Instagram only. Use `FACEBOOK` or `INSTAGRAM` to preselect the hosted portal connection method. | | `withBusinessScope` | No | Facebook, Instagram via Facebook, and YouTube. When provided, the hosted page skips the business vs standard scope chooser and uses your value. For YouTube it adds the monetary analytics scope that enables revenue/monetization data. | | `expiresIn` | No | Link lifetime in minutes. Min `5`, max `2880` (48 hours). Defaults to `10`. | > [!WARNING] > > For Facebook and Instagram via Facebook, tell users to select **all Pages and Instagram accounts they manage** in Meta OAuth. Then select the one Page or Instagram account for this team inside bundle.social. *** ## Hosted UI Fields | Field | Required | Description | | :- | :- | :- | | `logoUrl` | No | HTTPS image URL shown on the hosted page. | | `userLogoUrl` | No | HTTPS user logo or avatar shown on the hosted page. | | `userName` | No | User name shown on the hosted page. | | `goBackButtonText` | No | Text for the back button. | | `language` | No | Page language: `en` (default), `pl`, `fr`, `hi`, `sv`, `de`, `es`, `it`, `nl`, `pt`, `ru`, `tr`, `zh`, `da`, `no`, `th`, `ko`, `he` or `ar`. | | `hidePoweredBy` | No | Hide the "powered by" text. | | `hideGoBackButton` | No | Hide the back button. | | `hideUserLogo` | No | Hide the user logo. | | `hideUserName` | No | Hide the user name. | | `hideLanguageSwitcher` | No | Hide the language switcher. | | `showModalOnConnectSuccess` | No | Ask the user what to do after a successful connection: go back to `redirectUrl` or close and connect more accounts. | | `maxSocialAccountsConnected` | No | Maximum number of social accounts that can be connected in the hosted flow. | ### Supported Languages | Code | Language | | :- | :- | | `en` | English | | `pl` | Polish | | `fr` | French | | `hi` | Hindi | | `sv` | Swedish | | `de` | German | | `es` | Spanish | | `it` | Italian | | `nl` | Dutch | | `pt` | Portuguese | | `ru` | Russian | | `tr` | Turkish | | `zh` | Chinese | *** ## Hosted Flow Steps 1. Create a portal link with `POST /api/v1/social-account/create-portal-link`. 2. Redirect the user to the returned `url`. 3. The user connects one or more accounts. 4. If a platform needs a channel, the hosted UI handles the picker. 5. The user returns to your app through `redirectUrl` or the back button. ![Connect social account flow](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/api-reference/connect-social-account/connect-social-account-hosted.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=ce031bb15dc3b8ad31dd4b2cc33ee960) For return query parameters, see [Callback Parameters](/api-reference/connect-social-accounts/callbacks). Snapchat connected with `PERSONAL` uses the Public Profile returned during OAuth and shows no channel picker. With `BUSINESS`, the portal shows a picker with the Public Profiles of the login's Snap Business organizations. Set `snapchatConnectionMethod` on the portal link to fix the method; leave it out to let the user choose. # OAuth Options Source: https://info.bundle.social/api-reference/connect-social-accounts/oauth-options Understand disableAutoLogin, tiktokForceLogin, forceBrowserOAuth, withBusinessScope, and Instagram connection methods. These options affect how provider OAuth behaves. They are available in both hosted and custom flows unless noted otherwise. *** ## reconnect Supported for **Instagram** connected with `instagramConnectionMethod: "INSTAGRAM"`. When `true`, the OAuth flow re-authorizes the account that is **already connected** to the team instead of creating a new one. New tokens and permissions are saved on the same account, so its posts, scheduled posts and settings stay as they are. Use it when an account needs a fresh grant (for example, publishing fails with a permission error) and you don't want to disconnect it. ```json theme={null} { "type": "INSTAGRAM", "instagramConnectionMethod": "INSTAGRAM", "reconnect": true } ``` The user has to log in with the same Instagram account. A different account is refused with `instagram-reconnect-different-account`. Without `reconnect`, connecting a type the team already has still returns `400`. The hosted portal shows a **Reconnect** button for these accounts. *** ## disableAutoLogin Supported for **Facebook**, **Instagram via Facebook**, **Instagram direct OAuth**, and **TikTok** where the provider supports it. When `true`, we add provider-specific flags that try to prevent silent account reuse. Use it when your users manage many accounts from the same browser. Without it, the OAuth popup can reuse the last logged-in platform account. ```json theme={null} { "disableAutoLogin": true } ``` *** ## tiktokForceLogin Supported only for **TikTok** and currently experimental. When `true`, bundle.social routes the user through TikTok logout before starting authorization. Use it when TikTok keeps reusing the wrong active account even with `disableAutoLogin`. ```json theme={null} { "type": "TIKTOK", "tiktokForceLogin": true } ``` > [!WARNING] > > This signs the user out of their active TikTok browser session. Use it only when choosing a fresh account is more important than preserving that session. *** ## forceBrowserOAuth Supported for **Instagram direct OAuth**. When `true`, Instagram asks the user to log in again instead of reusing the account already logged in on that browser. Use it when connecting several Instagram accounts one after another. In the [hosted flow](/api-reference/connect-social-accounts/hosted-flow) the flag is applied only on iPhone and iPad; on other devices use `disableAutoLogin`, which has the same effect on Instagram. The custom `connect` endpoint applies it on every device. ```json theme={null} { "type": "INSTAGRAM", "instagramConnectionMethod": "INSTAGRAM", "forceBrowserOAuth": true } ``` > [!NOTE] > > Keeping the login in the browser on iPhone no longer needs this flag: every Instagram direct connection now stays in the browser on iOS instead of jumping into the Instagram app. On Android, the phone's "Open supported links" setting for the Instagram app decides, and links opened inside other apps (Instagram, WhatsApp, Messenger) use their in-app browser, where the login can fail. If that happens, open the link in a regular browser or on a computer. *** ## withBusinessScope Supported for **Facebook**, **Instagram via Facebook**, and **YouTube**. When `true`, OAuth requests broader access on top of the standard scope set: * **Facebook** and **Instagram via Facebook** - the broader Meta scope set, including `business_management`, `ads_management`, and `ads_read` among the permissions we request. * **YouTube** - the monetary analytics scope (`yt-analytics-monetary.readonly`), which enables **revenue/monetization data** in raw analytics. See [YouTube → Monetization](/api-reference/platforms/youtube#monetization). When `false`, OAuth uses the standard scope set. ```json theme={null} { "type": "FACEBOOK", "withBusinessScope": true } ``` > [!WARNING] > > Some Facebook Pages and Instagram accounts only appear in the picker when the connection was made with business scope. If something is missing from the list, reconnect using the other method (`withBusinessScope` flipped) before assuming the picker is wrong. > [!NOTE] > > For **YouTube**, the monetary scope is optional. If the user doesn't grant it, the connection still succeeds - only monetization data is unavailable. Missing it never blocks a connection. *** ## Instagram Connection Method Supported for `type: "INSTAGRAM"` in custom UI and hosted portal links. | Value | Meaning | Channel selection | | :- | :- | :- | | `FACEBOOK` | Instagram through Facebook Login. This is the default path when omitted. | Required. Use `set-channel`. | | `INSTAGRAM` | Direct Instagram OAuth. | Not supported. The account is selected directly during OAuth. | Use Facebook Login when you need Facebook-backed Instagram features such as Page-connected account selection, comments, insights, location search, or Instagram audio search for Reels. Use direct Instagram OAuth when you explicitly want the direct Instagram OAuth path and do not need Facebook-backed channel selection. *** ## serverUrl Supported for **Mastodon** and **Bluesky** in the custom UI flow. | Platform | Required? | Example | | :- | :- | :- | | Mastodon | Yes | `https://mastodon.social` | | Bluesky | No, but supported | `https://bsky.social` | ```json theme={null} { "type": "MASTODON", "teamId": "team_123", "redirectUrl": "https://app.example.com/oauth/callback", "serverUrl": "https://mastodon.social" } ``` # Data Retention Source: https://info.bundle.social/api-reference/data-retention What we keep, for how long, and when it disappears. Analytics 30 days, webhook events 2, deleted uploads 2, stale uploads 14, imported posts 30, DMs and automation logs 30. Plan accordingly. We don't keep your data forever. Storage costs money, and we are great on your wallet - don't exploit us. We are not running a digital museum. Here's exactly what gets cleaned up, when, and why. *** ## Analytics Data - 30 Days **What:** All parsed and raw analytics data (profile analytics, post analytics, and their raw counterparts). **Retention:** **30 days** from the date the analytics record was created. After 30 days, the data is gone. Permanently. No backups. No "can you please recover it?". No. ### What You Should Do If you need analytics history beyond 30 days (and you probably do if you're building dashboards or reports), set up a daily sync. Here's a battle-tested approach: ```typescript theme={null} // analytics-sync.ts - Run this daily via cron import { CronJob } from 'cron'; const syncAnalytics = async () => { // 1. Fetch all teams const teams = await yourDatabase.teams.findAll(); for (const team of teams) { // 2. For each social account, fetch current analytics for (const account of team.socialAccounts) { const analytics = await bundlesocial.analytics.getSocialAccountAnalytics({ teamId: team.id, socialAccountId: account.id, }); // 3. Store with timestamp for historical tracking await yourDatabase.analyticsHistory.upsert({ socialAccountId: account.id, date: new Date().toISOString().split('T')[0], // YYYY-MM-DD ...analytics, fetchedAt: new Date(), }); } // 4. Fetch post analytics too const posts = await bundlesocial.analytics.getBulkPostAnalytics({ teamId: team.id, }); for (const post of posts.data) { await yourDatabase.postAnalyticsHistory.upsert({ postId: post.id, date: new Date().toISOString().split('T')[0], ...post.analytics, fetchedAt: new Date(), }); } } }; // Run daily at 2 AM UTC new CronJob('0 2 * * *', syncAnalytics, null, true, 'UTC'); ``` With this running, you have full analytics history in your own database. Build dashboards, generate reports, impress clients - all without worrying about our 30-day window. > [!NOTE] > > **Why 30 days?** We updated our cleanup/deletion methodology and now run a tighter, more consistent retention policy. If you need longer history, sync daily and store it on your side. *** ## Webhook Events **What:** All webhook event records (delivery attempts, payloads, responses). **Retention:** **2 days** from the date the event was created, once the event is finished: delivered more than an hour ago, or undeliverable because the webhook was disabled or deleted. An event still waiting for a delivery attempt is kept until it is delivered. Debug and [resend](/api-reference/webhooks#resending-events) an event within 2 days. After that, the record is gone. ### What You Should Do Log webhook payloads on your end when you receive them. This is standard practice for any webhook integration. If you're not logging incoming webhooks, you're living dangerously. *** ## Deleted Uploads - 2 Days **What:** Files you've deleted (images, videos) and their database records. **Retention:** **2 days** after an upload is soft-deleted (by you, or by the stale-upload rule below). When an upload is deleted, we don't immediately nuke the file. We keep it around for 2 days in case you change your mind. After 2 days: * If the upload was used in a post: we remove the main file from storage but keep the database record, thumbnail and icon (so post history still shows a preview). The upload's `url` stops working. * If the upload was never used: the files and the database record are all deleted. Uploads attached to a draft or scheduled post can't be deleted. ## Stale Uploads - 14 Days Uploads are cleaned up automatically on a **sliding 14-day window**: * An upload stays alive as long as **any post using it is still a draft, scheduled or publishing**. * Once that's no longer true, it's soft-deleted **14 days** after the later of: when it was uploaded, or when the last post using it reached `POSTED`, `ERROR` or `DELETED`. * An upload that is **never attached to a post** is soft-deleted 14 days after upload. After that, the 2-day deleted-upload window above applies. > [!TIP] > > Scheduling far ahead is safe: attach the upload to the post **when you create the post**, and it stays until the post publishes. Don't upload now and create the post more than 14 days later. *** ## Imported Posts - 30 Days **What:** Posts imported via the [Post History Import](/api-reference/import-posts) feature. **Retention:** **30 days** from the date of import. Imported posts are meant to populate your dashboard quickly - not to serve as a permanent archive. After 30 days, they're deleted (along with their analytics, via cascade). ### Monthly Import Counter Reset Your import quota resets on the **1st of every month**. So if you hit your monthly limit, just wait for the calendar to flip. *** ## Direct Messages And Automation Logs - 30 Days **What:** [Direct messages](/api-reference/direct-messages), conversations, and [automation](/api-reference/automations) execution logs (every run and every step). **Retention:** at least **30 days** from when each message or run was created. * Messages are deleted one by one as they turn 30 days old, so an ongoing conversation keeps its recent part. * A conversation itself disappears once it has had no activity for 30 days and all of its messages are gone. * Automation runs and their step logs go 30 days after the run. The same goes for records of button, quick reply and menu taps. Your flows, their versions, and your ice breakers and menus are not affected. ### Why DMs are private conversations between your users and the people who write to them. We keep them only as long as the inbox and your automations need them, in line with Meta's platform rules. We'd rather not sit on other people's private messages. ### What You Should Do If you need a longer history (support records, CRM, compliance), store messages on your side as they arrive. Every message reaches you as a [`conversation.message.created`](/api-reference/direct-messages/webhooks) webhook, and edits, unsends and status changes as `conversation.message.updated`. Saving those payloads is all it takes. *** ## Summary | Data Type | Retention Period | | :- | :- | | Analytics (parsed + raw) | **30 days** | | Webhook events | **2 days** after delivery | | Deleted uploads | **2 days** after deletion | | Stale uploads | Soft-deleted **14 days** after upload or after the last post using it finished, then the 2-day deleted-upload window applies | | Imported posts | **30 days** | | Direct messages and conversations | **30 days** | | Automation execution logs | **30 days** | *** ## The Golden Rule **If you need it long-term, store it yourself.** We are optimized for real-time publishing and recent analytics. We are not Snowflake. We are not BigQuery. We are a social media API that happens to collect analytics as a side quest. Set up a daily sync. It takes 20 minutes to build (we gave you the code above). You'll sleep better. # Direct Messages Source: https://info.bundle.social/api-reference/direct-messages Read and answer Instagram and Facebook DMs through one API. Conversations, rich messages, private replies to comments, reactions, and real-time webhooks. > [!WARNING] > > **Turned on per organization, on request.** Direct Messages are part of the paid plans (the Free plan has no message allowance) and are switched on per organization. The same switch also turns on [Automations](/api-reference/automations) for Instagram and Facebook. [Contact us](https://bundle.social/contact) with your **organization ID** (the `id` returned by `GET /api/v1/organization`) and we'll turn it on. Until then every endpoint in this section answers `403` with a message that says how to request access. > > Once it's on, two things are on you: > > 1. **Reconnect** every Facebook and Instagram account with `withMessagingScope: true`, then **subscribe** each one to messages with `POST /api/v1/social-account/messaging/enable`. Accounts connected before the switch don't get DMs until you do. See [Setup](/api-reference/direct-messages/setup). > 2. **Accept the new webhook events.** Your webhook starts receiving an event for every new DM and every new comment on the account's posts, including posts published outside bundle.social. Keep your endpoint answering `2xx`, or it gets disabled. See [Webhooks](/api-reference/direct-messages/webhooks). The Direct Messages API gives you a unified inbox for Instagram and Facebook. New DMs land in bundle.social, we tell you about them with a webhook, and you answer through one endpoint no matter which platform the person wrote from. With it you can: * list conversations and read their full message history, * send text, images, videos, buttons, quick replies and carousels, * send a **private reply**: answer a public comment with a DM, * react to messages, mark conversations as read, archive them, * get every new message and status change in real time via webhooks. Want replies to go out on their own? That's [Automations](/api-reference/automations), which are built on top of this API. ## Try It In The Dashboard The inbox is already live in the bundle.social dashboard under **Conversations** ([bundle.social/dashboard/general/conversations](https://bundle.social/dashboard/general/conversations)). Read and answer DMs, react, archive, and see the 24-hour window in action before you build your own inbox on top of this API. Conversations and messages there are the same ones the API returns. ## In This Section > [card] [Setup](/api-reference/direct-messages/setup) > > Reconnect accounts and subscribe them to DMs. Start here. > [card] [Conversations](/api-reference/direct-messages/conversations) > > List conversations, read message history, mark as read, archive. > [card] [Sending Messages](/api-reference/direct-messages/sending-messages) > > Text, media, buttons, quick replies, carousels and reactions. > [card] [Private Replies](/api-reference/direct-messages/private-replies) > > Answer a Facebook or Instagram comment with a DM. > [card] [DM Webhooks](/api-reference/direct-messages/webhooks) > > Every new message and status change pushed to your server. > [card] [Automations](/api-reference/automations) > > Let replies go out on their own. ## All Endpoints All endpoints use your API key in the `x-api-key` header, same as the rest of the API. | Method | Endpoint | What it does | Docs | | :- | :- | :- | :- | | `POST` | `/api/v1/social-account/messaging/enable` | Subscribe an account to DMs | [Setup](/api-reference/direct-messages/setup) | | `POST` | `/api/v1/social-account/messaging/disable` | Stop DMs for an account | [Setup](/api-reference/direct-messages/setup#turning-it-off) | | `GET` | `/api/v1/conversations` | List conversations | [Conversations](/api-reference/direct-messages/conversations#list-conversations) | | `GET` | `/api/v1/conversations/:id` | Get one conversation | [Conversations](/api-reference/direct-messages/conversations#list-conversations) | | `GET` | `/api/v1/conversations/:id/messages` | List messages in a conversation | [Conversations](/api-reference/direct-messages/conversations#read-messages) | | `POST` | `/api/v1/conversations/:id/read` | Mark as read | [Conversations](/api-reference/direct-messages/conversations#mark-as-read) | | `PATCH` | `/api/v1/conversations/:id` | Set status (`OPEN` / `ARCHIVED`) | [Conversations](/api-reference/direct-messages/conversations#archive-and-reopen) | | `POST` | `/api/v1/conversations/:id/archive` | Archive | [Conversations](/api-reference/direct-messages/conversations#archive-and-reopen) | | `POST` | `/api/v1/conversations/:id/open` | Reopen | [Conversations](/api-reference/direct-messages/conversations#archive-and-reopen) | | `POST` | `/api/v1/conversations/:id/messages` | Send a message | [Sending Messages](/api-reference/direct-messages/sending-messages#send-a-message) | | `POST` | `/api/v1/conversations/:id/messages/:messageId/reaction` | React or unreact | [Sending Messages](/api-reference/direct-messages/sending-messages#react-to-a-message) | | `POST` | `/api/v1/conversations/private-reply` | DM someone who commented | [Private Replies](/api-reference/direct-messages/private-replies) | | `POST` | `/api/v1/automation-rich-messages/conversations/:conversationId` | Send a message with uploaded media | [Automations](/api-reference/automations/building-flows#send-a-rich-message-by-hand) | *** ## Supported Platforms | Platform | What is supported | | :- | :- | | `INSTAGRAM` | DMs for Instagram professional accounts (Business or Creator), private replies to comments, heart reactions | | `FACEBOOK` | Messenger DMs for Facebook Pages, private replies to comments | > [!NOTE] > > The `platform` field is **extensible**. We will add more messaging platforms over time, so treat unknown values gracefully (show a generic icon, skip the row) instead of switching over the list exhaustively. *** ## Plans And Limits Sending DMs is a paid-plan feature. Each connected account has a monthly quota of **outbound** messages: | Plan | Outbound messages per account / month | | :- | :- | | Free | 0 | | Pro | 200 | | Business | 1,000 | What counts: every message sent through bundle.social, whether it came from your API call, the dashboard, or an [automation](/api-reference/automations), including [private replies](/api-reference/direct-messages/private-replies). What doesn't count: incoming messages, messages that failed, messages the account owner typed directly in the Instagram or Messenger app, reactions, and marking a conversation as read. Quotas reset on the 1st of every month (UTC). When the quota runs out, sends return `403` with `Monthly message limit reached`. Check each account's usage with `GET /api/v1/organization/usage/messages` (`messagesUsed` and `messagesLimit`, including any higher limit agreed for your organization). See [Check Monthly Message And Automation Usage](/api-reference/rate-limits#check-monthly-message-and-automation-usage). Need a bigger bucket? [Contact us](https://bundle.social/contact). > [!NOTE] > > **Messages are kept for 30 days.** Each message is deleted 30 days after it was created, and a conversation goes once it has been quiet for 30 days. Need a longer history? Store messages on your side as they arrive via [DM webhooks](/api-reference/direct-messages/webhooks). Details in [Data Retention](/api-reference/data-retention). *** ## How It Works ### Conversations And Messages A **conversation** is one thread between a connected account and one person (the *participant*). Each conversation belongs to a team and to one social account. A **message** belongs to a conversation and has a `direction`: * `INBOUND` - the participant wrote to you, * `OUTBOUND` - you (or the account owner) wrote to them. The `source` field tells you where a message came from: | Source | Meaning | | :- | :- | | `DM` | Incoming message from the participant | | `API` | Sent through bundle.social (API, dashboard, or an automation) | | `PRIVATE_REPLY` | A private reply to one of the participant's comments | | `ECHO` | Sent by the account owner directly from the Instagram or Messenger app | Like `platform`, treat unknown `source` values gracefully. ### The 24-Hour Rule This is the one rule you really need to know. **Meta only lets a business send a free-form message within 24 hours of the participant's last message.** After that, the conversation is read-only until the person writes again. * `platformData.lastInboundAt` tells you when the participant last wrote. Use it to show "you can reply for another 3h" in your UI. * `platformData.canReply: false` means the conversation was opened by a private reply and the person hasn't answered yet. You have to wait for them. If you try anyway, you get a `400`: | Message | What to do | | :- | :- | | `Meta only allows replies within 24 hours of the participant's last message` | Wait until the participant writes again. | | `This conversation is waiting for the participant to reply first` | The person never wrote (or only got a private reply). Nothing to send until they do. | > [!NOTE] > > This isn't us being strict for fun. Meta enforces the window on their side, we just stop the request early so you get a clear error instead of a cryptic one from Graph API. ### Message Status Outbound messages move through these statuses. Your own sends first reach your webhook as `conversation.message.created`, already `SENT` (or `FAILED`), and every later change arrives as `conversation.message.updated`. Incoming messages simply arrive as `DELIVERED`. | Status | Meaning | | :- | :- | | `PENDING` | We're handing it to the platform | | `SENT` | The platform accepted it | | `DELIVERED` | It reached the participant's device | | `SEEN` | The participant opened it | | `FAILED` | It didn't go out. `error` holds a readable reason. | Not every platform reports every step (Instagram doesn't send delivery receipts, for example), so a message can jump from `SENT` straight to `SEEN`. *** ## Errors Errors come back as `{ "statusCode": 400, "message": "..." }`. The ones specific to messaging: | Status | Message | Meaning | | :- | :- | :- | | `400` | `Meta only allows replies within 24 hours...` | The 24-hour window closed | | `400` | `This conversation is waiting for the participant to reply first` | Nobody wrote to you yet in this thread | | `400` | `Instagram DMs do not support phone buttons` | Use a `URL` button instead | | `400` | `Private replies support text only...` | Remove attachments or the carousel from the private reply (buttons and quick replies are rejected as unknown fields) | | `400` | `Facebook private replies are only supported for top-level comments` | Facebook doesn't allow private replies to thread replies | | `400` | `Facebook private replies must be sent within 7 days of the comment` | The comment is too old | | `403` | `Messaging is not enabled for this social account. Enable it first.` | Call `/social-account/messaging/enable` | | `403` | `Monthly message limit reached...` | Quota used up for this account this month | | `403` | `Instagram and Facebook direct messages and automations are not enabled for your organization. Email contact@bundle.social with your organization ID to request access.` | Direct Messages are not turned on for your organization yet. Email us as described at the top of this page. | | `404` | `Conversation not found` (or similar) | A wrong ID. The message says what wasn't found. | | `429` | `Private reply send already claimed` | A private reply for this comment is being sent right now, or an earlier attempt timed out and may have been delivered. We never risk sending it twice, so don't keep retrying: check the conversation instead. | | `503` | `Messaging is temporarily disabled...` | Sending is paused on our side (for example during a Meta incident). Retry in a few minutes. | *** ## Quick FAQ ### "I enabled messaging but no conversations show up." Conversations only appear when someone writes **after** you enabled messaging (or when you send a private reply, or answer someone from the Instagram or Messenger app). Send a test DM to the account from another profile. If still nothing shows up, check the setup order: the account has to be reconnected with `withMessagingScope: true` **after** your organization was allowlisted, and only then subscribed with `messaging/enable`. Enabling on an account connected before the switch returns `400`, so reconnect first. ### "Can I start a conversation with anyone?" No. Meta doesn't allow businesses to cold-DM people. Someone has to write to you first, or comment on your post so you can send a private reply. ### "How far back does the message history go?" Up to 30 days. We only have messages that arrived after you enabled messaging on the account, and each one is deleted 30 days after it arrived. For anything older, keep your own copy from the webhooks. ### "Can I message someone after 24 hours?" Not with a regular message. Once the participant writes again, the window reopens for another 24 hours. ### "Do messages from the Instagram app show up too?" Yes. If the account owner answers from the Instagram or Messenger app, the message appears in the conversation with `source: "ECHO"`, so your inbox always shows the full thread. These don't count toward your quota. ### "Is there a WebSocket?" Not in the public API. Use webhooks for real-time updates. # Conversations Source: https://info.bundle.social/api-reference/direct-messages/conversations List conversations, read message history, paginate, mark as read, archive and reopen. All endpoints on this page use your API key in the `x-api-key` header. The full endpoint list is on the [Direct Messages overview](/api-reference/direct-messages#all-endpoints). *** ## List Conversations **Endpoint:** `GET /api/v1/conversations` Query params: * `teamId` (required) * `platform` (optional) - `INSTAGRAM` or `FACEBOOK` * `socialAccountId` (optional) * `status` (optional) - `OPEN` or `ARCHIVED` * `limit` (max 1000), and either `offset` or `cursor` Conversations come back with the most recent activity first. ```bash theme={null} curl "https://api.bundle.social/api/v1/conversations?teamId=team_123&status=OPEN&limit=20" \ -H "x-api-key: YOUR_KEY" ``` ```json theme={null} { "items": [ { "id": "conv_abc", "teamId": "team_123", "socialAccountId": "sa_789", "platform": "INSTAGRAM", "externalConversationId": "aWdfdGhyZWFk...", "externalParticipantId": "1789000000000000", "participantUsername": "janedoe", "participantDisplayName": "Jane Doe", "participantAvatarUrl": "https://...", "status": "OPEN", "lastMessageAt": "2026-09-26T09:30:00.000Z", "lastActivityAt": "2026-09-26T09:30:00.000Z", "lastMessagePreview": "Hi! Do you ship to Poland?", "lastReadAt": null, "unreadCount": 1, "platformSeenAt": null, "platformData": { "lastInboundAt": "2026-09-26T09:30:00.000Z", "participantFollowsBusiness": true, "businessFollowsParticipant": false }, "socialAccount": { "id": "sa_789", "type": "INSTAGRAM", "username": "mybrand" }, "createdAt": "2026-09-26T09:30:00.000Z", "updatedAt": "2026-09-26T09:30:00.000Z" } ], "total": 1, "nextCursor": "eyJ0IjoiMjAyNi0wOS0yNlQwOTozMDowMC4wMDBaIiwiaWQiOiJjb252X2FiYyJ9" } ``` Useful fields: * `unreadCount` / `lastReadAt` - your side's read state, see [Mark As Read](/api-reference/direct-messages/conversations#mark-as-read). * `platformSeenAt` - when the participant last read your messages. * `lastActivityAt` - what the list is sorted by. * `platformData.lastInboundAt` / `canReply` - the [24-hour rule](/api-reference/direct-messages#the-24-hour-rule). * `platformData.participantFollowsBusiness` / `businessFollowsParticipant` - Instagram only: whether the participant follows your account and whether your account follows them. Read from Instagram when we fetch the participant's profile, so it's a snapshot, not live. Missing when Instagram didn't return it; a later fetch without it keeps the last known value. * `socialAccount` - the connected account the conversation belongs to. * `externalConversationId` / `externalParticipantId` - the platform's own IDs for the thread and the person. `GET /api/v1/conversations/:id` returns the same object for a single conversation. *** ## Pagination Both list endpoints support two styles, pick one per request: * **Offset:** `offset` + `limit`. Simple, good for page numbers. * **Cursor:** pass the previous response's `nextCursor` back as `cursor`. For messages it stays stable while new ones keep arriving, so this is what you want for infinite scroll. The conversation list is sorted by `lastActivityAt`, which changes with every new message. A conversation that gets a new message while you page through the list moves to the top, so it can be missing from later pages. Refresh the first page (or use [webhooks](/api-reference/direct-messages/webhooks)) to catch it. `limit` defaults to 10 (max 1000). `total` is only returned on the first page (when you don't send a `cursor`). Sending a `cursor` together with a non-zero `offset` returns `400`. When `nextCursor` is empty, you've reached the end. *** ## Read Messages **Endpoint:** `GET /api/v1/conversations/:id/messages` Pages walk **backwards in time** (the first page has the newest messages), but messages **inside** a page are ordered oldest first, so you can render them top to bottom without sorting. ```json theme={null} { "items": [ { "id": "msg_1", "conversationId": "conv_abc", "teamId": "team_123", "socialAccountId": "sa_789", "platform": "INSTAGRAM", "direction": "INBOUND", "status": "DELIVERED", "source": "DM", "externalMessageId": "aWdfZG1faWQ...", "text": "Hi! Do you ship to Poland?", "attachments": [], "sentAt": "2026-09-26T09:30:00.000Z", "seenAt": null, "failedAt": null, "error": null, "replyTo": null, "privateReplyContext": null, "platformData": {}, "createdAt": "2026-09-26T09:30:01.000Z", "updatedAt": "2026-09-26T09:30:01.000Z" }, { "id": "msg_2", "conversationId": "conv_abc", "platform": "INSTAGRAM", "direction": "OUTBOUND", "status": "SEEN", "source": "API", "text": "We do! Shipping takes 2-3 days.", "attachments": [], "sentAt": "2026-09-26T09:31:10.000Z", "seenAt": "2026-09-26T09:32:00.000Z", "replyTo": { "messageId": "msg_1", "externalMessageId": "aWdf...", "isSelfReply": false }, "platformData": { "reactions": [{ "senderId": "1789000000000000", "reaction": "love", "emoji": "❤️" }] } } ], "total": 2, "nextCursor": null } ``` Useful fields: * `attachments[]` - `type` (`IMAGE`, `VIDEO`, `AUDIO`, `FILE`, `POST`, `STORY_MENTION`, `UNKNOWN`) and a `url` when the platform gives one. `POST` is shared content on Messenger (a link or a shared post). `STORY_MENTION` is an Instagram story that mentions the account (see [Story replies and mentions](#story-replies-and-mentions)). On Instagram, shared posts and reels currently arrive as `UNKNOWN`, with a `url` when Meta provides one. * `replyTo` - set when the message is a reply to an earlier one. `messageId` points to our message if we have it. * `platformData.storyReply` - set when the participant replied to the account's Instagram story. See [Story replies and mentions](#story-replies-and-mentions). * `privateReplyContext` - for private replies: the comment it answered (`text`, `authorName`, `postPermalink`, `postThumbnailUrl`, ...). * `platformData.reactions` - reactions on the message. * `platformData.isEdited` / `editedAt` - the participant edited their message. `text` already holds the new version. * `platformData.isUnsent` / `unsentAt` - the participant unsent it. We clear `text`, `attachments` and `platformData.storyReply` on our side. If you stored the content from an earlier webhook, delete or hide your copy too. * `platformData.quickReplies`, `buttons`, `carousel` - the rich content of messages you sent. * `platformData.isPostback` / `postbackPayload` - the participant tapped a `POSTBACK` button, an ice breaker or a menu item, and this is the payload behind it. * `platformData.isEcho` - the account owner sent this from the Instagram or Messenger app. * `error` / `failedAt` - why and when an outbound message failed. > [!NOTE] > > Platform-hosted attachment URLs (images someone sent you) are signed by Meta and **expire**. If you need them long-term, download and store them yourself. Story URLs (`STORY_MENTION` attachments and `platformData.storyReply.url`) stop working once the story expires, usually after 24 hours, so show a fallback when they no longer load. ### Story Replies And Mentions Instagram only. * **Story reply:** the participant answered one of the account's stories. The message has the reply `text` and `platformData.storyReply`: ```json theme={null} { "text": "Where can I buy this?", "attachments": [], "platformData": { "storyReply": { "storyId": "17900000000000000", "url": "https://lookaside.fbsbx.com/...", "linkStickerUrl": "https://example.com/product" } } } ``` | Field | Description | | :- | :- | | `storyId` | Instagram ID of the story. Can be `null`. | | `url` | Link to the story media. Expires with the story (24 hours), so treat it as best effort. Can be `null`. | | `linkStickerUrl` | The URL of the story's link sticker, if it had one. Otherwise `null`. | * **Story mention:** the participant mentioned the account in their own story. The message has no `text` and one attachment with `type: "STORY_MENTION"` and the story's `url` when Meta provides one. The conversation's `lastMessagePreview` reads "Mentioned you in their story". The URL expires like other Meta attachment URLs. When the participant unsends a story reply, `storyReply` is removed along with `text` and `attachments`. *** ## Mark As Read **Endpoint:** `POST /api/v1/conversations/:id/read` ```json theme={null} { "readAt": "2026-09-26T09:35:00.000Z" } ``` `readAt` is optional (defaults to now). It resets `unreadCount` and also tries to show the participant a "seen" marker on the platform. That marker is best effort: it's skipped when messaging isn't enabled for the account or sending is paused on our side, and a platform error doesn't fail the call. If you send a `readAt` older than the last message, we only move `lastReadAt` and keep the counter, since you hadn't seen the newest message at that point. *** ## Archive And Reopen * `POST /api/v1/conversations/:id/archive` - move it out of the active inbox, * `POST /api/v1/conversations/:id/open` - bring it back, * `PATCH /api/v1/conversations/:id` with `{ "status": "ARCHIVED" }` - same thing, generic form. Archiving is a bundle.social inbox state, it doesn't archive the thread inside Instagram or Messenger. A new incoming message reopens an archived conversation automatically, so nobody gets lost in the archive. # Private Replies Source: https://info.bundle.social/api-reference/direct-messages/private-replies Answer a Facebook or Instagram comment with a direct message. A private reply is a DM sent **in response to a public comment**. The classic use case: someone comments "price?" under your post and you answer in their inbox instead of in public. Want to answer the comment **publicly** instead? That's the [Comments API](/api-reference/comments#replying-to-imported-comments) (`POST /api/v1/comment` with `fetchedParentCommentId`). Want either to happen on its own? That's [Automations](/api-reference/automations). **Endpoint:** `POST /api/v1/conversations/private-reply` ```ts theme={null} await fetch("https://api.bundle.social/api/v1/conversations/private-reply", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.BUNDLE_API_KEY, }, body: JSON.stringify({ teamId: "team_123", fetchedCommentId: "fetched_1", content: { text: "Hey! Just sent you the price list 👋", }, }), }); ``` `fetchedCommentId` is the `id` of a comment you got from the [Comments API](/api-reference/comments) (`GET /api/v1/comment/import/comments`). Works for Facebook and Instagram comments. Meta has strict rules here, and we follow them: * **One private reply per comment.** If the first reply went out, sending again returns it with `conflict: true` instead of messaging the person twice. If the first attempt is still in progress or its outcome is unknown, you get `429` (see [Errors](/api-reference/direct-messages#errors)). If the platform rejected it, sending again really tries again. * **Text only.** No attachments, buttons, quick replies, or carousels in a private reply. * **The comment must be recent.** Meta accepts private replies up to 7 days after the comment was posted. We check this before sending on Facebook; on Instagram, Meta rejects late replies itself. * **Facebook: top-level comments only.** On Facebook you can't send a private reply to a reply inside a comment thread. * **Follow-ups wait for the person.** If the reply starts a new conversation, it has `platformData.canReply: false`: you can send more messages only after they answer, and then the usual 24-hour rule applies. If you already had an open conversation with that person, it keeps its reply window. Private replies count toward your [monthly message limit](/api-reference/direct-messages#plans-and-limits) like any other message. On Instagram they use the account's comment permissions, so the account needs those in addition to messaging. In the message list, a private reply has `source: "PRIVATE_REPLY"` and a `privateReplyContext` telling you which comment and post it was about, so your inbox can show "replied to your comment on..." like Instagram does. # Sending Messages Source: https://info.bundle.social/api-reference/direct-messages/sending-messages Send text, media, buttons, quick replies and carousels, and react to messages. Send messages into an existing conversation. You can only answer people who wrote to you in the last 24 hours, see [the 24-hour rule](/api-reference/direct-messages#the-24-hour-rule). To start from a comment instead, use a [private reply](/api-reference/direct-messages/private-replies). ## Send A Message **Endpoint:** `POST /api/v1/conversations/:id/messages` ```ts theme={null} const res = await fetch(`https://api.bundle.social/api/v1/conversations/${conversationId}/messages`, { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.BUNDLE_API_KEY, }, body: JSON.stringify({ content: { text: "We do! Shipping takes 2-3 days.", }, replyToMessageId: "msg_1", // optional: link it to an earlier message in our data }), }); const { conversation, message, conflict } = await res.json(); ``` The response has three fields: * `conversation` - the updated conversation, * `message` - the message you just sent, with its current `status`, * `conflict` - `true` means **nothing was sent this time**, because the same message had already gone out and `message` is that earlier one. Only [private replies](/api-reference/direct-messages/private-replies) return `true` (they are limited to one per comment). Regular sends always return `false`. `replyToMessageId` is stored on our side and comes back as the message's `replyTo`, so your inbox can show which message you answered. It is not sent to the platform, so Instagram and Messenger don't show it as a quoted reply. > [!WARNING] > > Regular sends are **not** deduplicated. If a send times out on your side, list the conversation's messages before retrying, otherwise the customer may get the message twice. If the platform rejects the message, the call returns an error status (see [Errors](/api-reference/direct-messages#errors)), not a `200`. The failed message still stays in the thread with `status: "FAILED"` and an `error`, and your webhook gets it as `conversation.message.created`. *** ## Message Content A message needs at least one of `text`, `attachments`, or `carousel`. | Field | Limit | Notes | | :- | :- | :- | | `text` | 1,000 characters | We check characters. Instagram itself counts **bytes**, so a long text with emoji or non-Latin letters can pass our check and still be rejected by Instagram | | `attachments` | up to 10 | `{ "type": "IMAGE", "url": "https://..." }`. `IMAGE`, `VIDEO`, `AUDIO` or `FILE`, public **HTTPS** URL | | `quickReplies` | up to 13 | `{ "label": "Yes", "payload": "SHIPPING_YES" }`, label up to 20 chars | | `buttons` | up to 3 | `POSTBACK` (with `payload`), `URL` (with `url`) or `PHONE` (with `phoneNumber`), label up to 20 chars | | `carousel` | up to 10 cards | each card: `title` (required) up to 80 chars, optional `subtitle` up to 80 chars, `imageUrl` and up to 3 `buttons` | Rules of the road: * Buttons and quick replies need `text` (it's the message the buttons hang under). * A message has **either** buttons **or** quick replies, never both. * A carousel can have `text` (sent as its own bubble before the cards), but no buttons, quick replies or attachments next to it. * Instagram doesn't support `PHONE` buttons. Facebook does. * All URLs must be HTTPS. * Text and each attachment show up as separate bubbles on the platform, but you get one `message` back. Quick replies: ```json theme={null} { "content": { "text": "What can we help you with?", "quickReplies": [ { "label": "Shipping", "payload": "TOPIC_SHIPPING" }, { "label": "Returns", "payload": "TOPIC_RETURNS" }, { "label": "Talk to a human", "payload": "TOPIC_HUMAN" } ] } } ``` A button template: ```json theme={null} { "content": { "text": "Your order is on the way!", "buttons": [ { "type": "URL", "label": "Track package", "url": "https://yourshop.com/track/123" }, { "type": "POSTBACK", "label": "I have a problem", "payload": "ORDER_PROBLEM" } ] } } ``` A carousel: ```json theme={null} { "content": { "carousel": { "cards": [ { "title": "Classic Tee", "subtitle": "100% cotton, 29 EUR", "imageUrl": "https://yourshop.com/img/tee.jpg", "buttons": [{ "type": "URL", "label": "Buy", "url": "https://yourshop.com/p/tee" }] }, { "title": "Hoodie", "subtitle": "Warm and fuzzy, 59 EUR", "imageUrl": "https://yourshop.com/img/hoodie.jpg", "buttons": [{ "type": "URL", "label": "Buy", "url": "https://yourshop.com/p/hoodie" }] } ] } } } ``` When the participant taps a `POSTBACK` button, you get a message with `platformData.isPostback` and `postbackPayload`. A quick reply tap arrives as a normal message whose `text` is the quick reply's label. The payload isn't exposed on the message, but [automations](/api-reference/automations) can react to it with a `QUICK_REPLY_CLICKED` trigger. > [!TIP] > > Want to attach files you already uploaded to bundle.social instead of public URLs? Use `POST /api/v1/automation-rich-messages/conversations/:conversationId`, which takes `uploadId`s. It's described in [Automations](/api-reference/automations/building-flows#send-a-rich-message-by-hand). *** ## React To A Message **Endpoint:** `POST /api/v1/conversations/:id/messages/:messageId/reaction` ```json theme={null} { "action": "REACT", "reaction": "love" } ``` `reaction` is optional and defaults to `love`. Use `"action": "UNREACT"` to take it back. Only Instagram supports sending reactions, and only the heart (`love`): any other `reaction` value returns `400`. Facebook Messenger has no API for it, so there you can only *see* the reactions people leave. # Setup Source: https://info.bundle.social/api-reference/direct-messages/setup Reconnect Facebook and Instagram accounts with messaging permissions and subscribe them to DMs. Once Direct Messages are turned on for your organization, do this for **every** Facebook and Instagram account that should receive DMs: 1. **Reconnect it with messaging permissions.** This includes accounts that were already connected before we switched the feature on. They don't have the permissions yet. 2. **Subscribe it to messages** with `messaging/enable`. This registers the account for Meta's message webhooks. Without it, no DM ever reaches us. 3. **Make sure your webhook endpoint accepts the new events** (see [Webhooks](/api-reference/direct-messages/webhooks)). ## Step 1: Connect With Messaging Permissions Add `withMessagingScope: true` when you generate the connect link. It works on both the hosted portal and the custom connect flow. ```ts theme={null} const res = await fetch("https://api.bundle.social/api/v1/social-account/connect", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.BUNDLE_API_KEY, }, body: JSON.stringify({ teamId: "team_123", type: "INSTAGRAM", redirectUrl: "https://yourapp.com/connected", withMessagingScope: true, }), }); const { url } = await res.json(); // send your user here ``` For the hosted portal, pass the same `withMessagingScope: true` to `POST /api/v1/social-account/create-portal-link`. > [!WARNING] > > **Accounts connected before the feature was enabled must be reconnected.** That includes accounts connected with `withMessagingScope: true`, because the flag is ignored until Direct Messages are turned on for your organization. Meta only grants messaging permissions on its login screen, so there is no way to add them silently afterwards. The same reconnect also subscribes the account to new comments, which [comment automations](/api-reference/automations) need. ## Step 2: Subscribe The Account To Messages Connecting an account never subscribes it to DMs by itself. `messaging/enable` registers the account for Meta's message webhooks and starts processing its DMs. You opt in per account, so a customer who only wants scheduling never has their DMs processed. **Endpoint:** `POST /api/v1/social-account/messaging/enable` ```bash theme={null} curl -X POST "https://api.bundle.social/api/v1/social-account/messaging/enable" \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "teamId": "team_123", "type": "INSTAGRAM" }' ``` ```json theme={null} { "socialAccountId": "sa_789", "type": "INSTAGRAM", "messagingStatus": "ENABLED", "messagingLastError": null } ``` The call is idempotent, so calling it twice is harmless. | Response | Meaning | | :- | :- | | `200` | Subscribed, messaging is `ENABLED`. New DMs will start showing up. | | `400` | The account is missing the messaging permissions (reconnect it with `withMessagingScope: true`), the team has no account of that type, or no page or account was selected for the connection. The `message` says which. | | `403` | Direct Messages are not turned on for your organization yet. The `message` says how to request access. | | `502` | Meta refused the subscription. The account keeps its previous status (normally `DISABLED`); retry in a bit. | ## Turning It Off **Endpoint:** `POST /api/v1/social-account/messaging/disable` (same body) We stop processing DMs for that account immediately. Existing conversations stay readable, but sending, reactions and private replies return `403` until you enable it again. If Meta doesn't confirm the change right away, the status becomes `DISABLE_PENDING` and the call returns `502`, so you can safely retry it. > [!NOTE] > > We only collect messages that arrive **after** messaging is enabled. Older DM history from before that moment is not imported, and each message we collect is kept for [30 days](/api-reference/data-retention). # DM Webhooks Source: https://info.bundle.social/api-reference/direct-messages/webhooks Get every new DM and status change pushed to your server in real time. The fastest way to build an inbox is to let us push changes to you. Webhooks are also how you keep a history longer than our [30-day retention](/api-reference/data-retention): save every `conversation.message.created` payload (and apply `conversation.message.updated` for edits, unsends and status changes) and you have the full thread on your side. > [!WARNING] > > **Heads-up: new events arrive as soon as the feature is on.** From then on we send your [webhook](/api-reference/webhooks) an event for every new DM (`conversation.*`) and every new comment from other people on the account's posts, including posts published outside bundle.social (`comment.received`, described in [Automations](/api-reference/automations/webhooks)). If your webhook has no event filter, you get all of them automatically. > > Answer every event with a `2xx` within 15 seconds, **including event types you don't handle yet**. Just ignore them. If your endpoint keeps failing and goes **7 days without a single successful delivery**, we disable it automatically. You'll get an email and a dashboard notification, and you then have to re-enable it (or set up a new one) in the [Webhooks dashboard](https://bundle.social/dashboard/organization/webhooks). Events sent while it was disabled are not replayed. More in [Webhooks](/api-reference/webhooks). Subscribe to these events on your webhook (or leave the event filter empty to get everything): | Event | When it fires | `data` contains | | :- | :- | :- | | `conversation.created` | First message from a new participant (or first private reply) | Conversation | | `conversation.updated` | Status, preview or participant info changed, or a new message raised the unread count | Conversation | | `conversation.read.updated` | You marked it as read (unread count reset), or the participant read your messages (`platformSeenAt`) | Conversation | | `conversation.message.created` | New message, incoming or outgoing | Message | | `conversation.message.updated` | Status changed (`SENT` → `SEEN`...), edited, unsent, or reacted to | Message | Payloads use the same shape as the [conversation and message objects](/api-reference/direct-messages/conversations) from the REST API, wrapped in the usual envelope. One difference: the top-level `replyTo` and `privateReplyContext` of a message are only filled in on REST reads. In webhooks, look at `platformData.replyTo` instead, or fetch the message. ```json theme={null} { "type": "conversation.message.created", "data": { "id": "msg_1", "conversationId": "conv_abc", "teamId": "team_123", "socialAccountId": "sa_789", "platform": "INSTAGRAM", "direction": "INBOUND", "status": "DELIVERED", "source": "DM", "text": "Hi! Do you ship to Poland?", "attachments": [], "sentAt": "2026-09-26T09:30:00.000Z", "platformData": {}, "createdAt": "2026-09-26T09:30:01.000Z", "updatedAt": "2026-09-26T09:30:01.000Z" } } ``` ## Example: A Tiny Inbox Handler Verify the signature, answer fast, do the real work afterwards: ```ts theme={null} import crypto from "node:crypto"; import express from "express"; const app = express(); // Keep the raw body - the signature is computed over the exact bytes we sent. app.post("/webhooks/bundle", express.raw({ type: "application/json" }), async (req, res) => { const expected = crypto .createHmac("sha256", process.env.BUNDLE_WEBHOOK_SECRET!) .update(req.body) .digest("hex"); const received = String(req.headers["x-signature"] ?? ""); if ( received.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected)) ) { return res.status(401).end(); } const event = JSON.parse(req.body.toString("utf8")); res.status(200).end(); // ack first, we have 15 seconds if (event.type === "conversation.message.created" && event.data.direction === "INBOUND") { await saveToInbox(event.data); // your code await notifyAgents(event.data.conversationId); // your code } if (event.type === "conversation.message.updated") { await updateMessageStatus(event.data.id, event.data.status); // Messenger: SENT -> DELIVERED -> SEEN, Instagram: SENT -> SEEN } }); ``` > [!TIP] > > Deduplicate on `data.id` + `data.updatedAt`. Don't use `status` for this: edits, unsends and reactions change a message without changing its status. Retries (ours and Meta's) can occasionally deliver the same change twice. Outgoing messages reach your webhook already as `SENT` or `FAILED`, never as `PENDING`. # Errors Source: https://info.bundle.social/api-reference/errors When things go wrong (and they will). Standardized error codes across every platform, transient vs non-transient, and the prefixes that tell you who broke. We standardized errors across all platforms. Whether it's TikTok rejecting your music or Instagram hating your aspect ratio, you get a clean JSON response. ## The Error Object Look for `errorsVerbose` in the response. ```json theme={null} { "errorsVerbose": { "INSTAGRAM": { "code": "META:190", "userFacingMessage": "Your Instagram token expired. Please reconnect.", "isTransient": false }, "TIKTOK": null // Success! } } ``` ## Key Fields | Field | Meaning | | :- | :- | | `code` | Stable ID (e.g. `HTTP:429`). Use this for logic. | | `userFacingMessage` | Safe to show your users. "Please reconnect." | | `errorMessage` | Raw developer logs. "OAuthException: Validate permission failed." | | `isTransient` | `true` = Retry later. `false` = Give up / Fix input. | ## Common Error Prefixes | Prefix | Platform | | :- | :- | | `META` | Instagram, Facebook, Threads | | `TT` | TikTok | | `LI` | LinkedIn | | `YT` | YouTube | | `HTTP` | Generic API errors | ## Transient vs. Non-Transient * **Transient (`true`):** Rate limits, server timeouts. **Action:** Retry with exponential backoff. * **Non-Transient (`false`):** Auth errors, validation errors. **Action:** Ask user to fix it (reconnect account, change video file). ## Interrupted Publishes When a publish is cut off on our side before the platform answers (for example during a deploy), the platform's error carries `code: "PUBLISH:INTERRUPTED"` instead of being left empty: | When it stopped | `userFacingMessage` | What to do | | :- | :- | :- | | While publishing | Publishing was interrupted before the platform confirmed this post. It may already be live, so check the account before retrying. | Check the account first. Retrying a post that went live publishes it twice. | | While uploading media | Publishing was interrupted while the media was uploading. Nothing was published, so it is safe to retry. | Retry. | A post that reached the platform before the interruption still ends as `POSTED`. ## HTTP Status Codes Errors returned by our own endpoints (not the per-platform `errorsVerbose` of a post) come back with a `message`. | Status | Meaning | Action | | :- | :- | :- | | `400` | Invalid request (validation failed, or the platform rejected the input). | Fix the request. | | `401` / `403` | Missing or invalid API key, or no access to that team or resource. | Check the key and the team ID. | | `404` | Resource not found. | Check the ID. | | `409` | Conflict, e.g. a post with this `referenceKey` already exists. See [Safe retries](/api-reference/examples#safe-retries-with-referencekey). | Don't retry. Fetch the existing resource. | | `429` | Rate limited. See [Rate Limits](/api-reference/rate-limits). | Retry after a pause. | | `500` | Something broke on our side. | Retry once, then contact us. | | `502` | The platform returned an invalid or incomplete response. | Retry later. | | `503` | The platform is temporarily unavailable. | Retry with exponential backoff. | | `504` | The platform timed out. | Retry with exponential backoff. | `502`, `503` and `504` mean the platform had a problem, not your request, so they're safe to retry. ## Most Common Platform Errors These are the most common normalized platform errors we see in production. Use the `canonical_error_key` for support routing, and use the platform message to match what the user saw in the failed post. > [!NOTE] > > Platform providers can change exact wording at any time. Treat the platform message as a representative example, not a strict string match. ### Facebook **Error key:** `account_connection_expired` **Platform code(s):** `HTTP:401`, `Meta:190:460`, `Meta:190:467` **Message we received:** ```text theme={null} Error validating access token: The session has been invalidated because the user changed their password or Facebook has changed the session for security reasons. ``` **Why this happens:** The access token or session used for publishing is no longer valid. This commonly happens after password changes, security checks, expired OAuth sessions, token revocation or just "because". **What the user should do:** Ask the user to reconnect the platform account. After reconnecting, retry the post. If it fails again immediately, ask them to log into the native platform first and clear any security prompt. *** **Error key:** `page_or_target_inaccessible` **Platform code(s):** `HTTP:400`, `Meta:190` **Message we received:** ```text theme={null} This Page access token belongs to a Page that is not accessible. ``` **Why this happens:** The selected page, profile, community, location, or publishing target is not accessible to the connected account anymore. **What the user should do:** Ask the user to confirm they still have access to that target on the platform. Then reconnect the account and reselect the page/profile if needed. *** **Error key:** `media_fetch_failed` **Platform code(s):** `HTTP:422` **Message we received:** ```text theme={null} Unable to fetch media from URL, got status code: 403 Restricted by TBS blocklist ``` **Why this happens:** Facebook could not fetch the hosted media URL. In our data this includes Meta crawler failures such as 403 blocklist or robots-style access blocks. **What the user should do:** Retry once. If it repeats, escalate so support can verify that Meta's crawler can access the media URL without authentication, redirect, or bot blocking. *** **Error key:** `account_authorization_revoked` **Platform code(s):** `Meta:190:458` **Message we received:** ```text theme={null} Error validating access token: The user has not authorized application ID. ``` **Why this happens:** The user or the platform removed the app authorization. Our system can still see the account record, but the platform no longer accepts the stored permission. **What the user should do:** Ask the user to reconnect the social account in bundle.social and approve all requested permissions again. If the account manages a page, they should also reselect the page during reconnect. *** **Error key:** `posting_rate_limited` **Platform code(s):** `Meta:368:1390008` **Message we received:** ```text theme={null} We limit how often you can post, comment or do other things in a given amount of time in order to help protect the community from spam. You can try again later. Learn More ``` **Why this happens:** The platform limited publishing frequency, the account reached a hourly publishing cap / was marked as spam. **What the user should do:** Ask the user to wait before retrying. If this happens often, reduce scheduling density for that account. *** **Error key:** `identity_confirmation_required` **Platform code(s):** `Meta:368:4854002` **Message we received:** ```text theme={null} Confirm your identity before you can publish as this Page. Open the Facebook app on your phone and follow the instructions. ``` **Why this happens:** The platform requires the user to confirm identity before publishing as that page or profile. **What the user should do:** Ask the user to open the platform mobile app or account quality center and complete identity confirmation. Retry after confirmation is complete. *** **Error key:** `account_not_confirmed` **Platform code(s):** `HTTP:401`, `Meta:190:464` **Message we received:** ```text theme={null} Error validating access token: Sessions for the user are not allowed because the user is not a confirmed user. ``` **Why this happens:** The platform requires the account to be confirmed before API publishing is allowed. This can mean email confirmation, account verification, or a required platform checkpoint. **What the user should do:** Ask the user to open the native platform, finish account confirmation, then reconnect the account and retry publishing. *** **Error key:** `missing_platform_permission` **Platform code(s):** `HTTP:400`, `Meta:190`, `Meta:200` **Message we received:** ```text theme={null} Any of the pages_read_engagement, pages_manage_metadata, pages_read_user_content, pages_manage_ads, pages_show_list or pages_messaging permission(s) must be granted before impersonating a user's page. ``` **Why this happens:** Meta rejected the publish because the current token no longer has effective permission to publish as the selected Page. This often happens when the same Meta user connects multiple bundle.social teams and selects only one Page during each OAuth flow. Meta can overwrite page grants for the Bundle app at the Meta-user level, so one team can still look connected while Meta has removed its Page grant remotely. **What the user should do:** Ask the user to reconnect the Meta account. In the Facebook OAuth screen, they should select all Pages and Instagram accounts they manage. Then choose the correct Page or Instagram channel inside bundle.social for that team and retry the failed post. *** **Error key:** `account_security_limited` **Platform code(s):** `HTTP:400`, `Meta:368:1404112` **Message we received:** ```text theme={null} For security reasons, your account has limited access to the site for a few days. If you have any questions, please contact our Help Center. ``` **Why this happens:** The platform temporarily limited the account for security reasons. The request is blocked until the platform removes the temporary limit. **What the user should do:** Ask the user to log into the platform, review security prompts, and wait until the limitation is lifted. Retry later after the account is back to normal. *** **Error key:** `platform_login_required` **Platform code(s):** `HTTP:401`, `Meta:190:459` **Message we received:** ```text theme={null} You cannot access the app till you log in to www.facebook.com and follow the instructions given. ``` **Why this happens:** The platform requires the user to log in and complete an account checkpoint before API publishing can continue, just to be sure that this is not a bot but a real person. **What the user should do:** Ask the user to log into the platform website or mobile app, complete any prompt, then reconnect and retry. *** **Error key:** `page_role_or_2fa_required` **Platform code(s):** `Meta:190:492` **Message we received:** ```text theme={null} The user must be an administrator, editor, or moderator of the page in order to impersonate it. If the page business requires Two Factor Authentication, the user also needs to enable Two Factor Authentication. ``` **Why this happens:** The platform requires a stronger page role or two-factor authentication before the user can publish as the page. **What the user should do:** Ask the user to confirm their page role and enable two-factor authentication if their business requires it. Then reconnect and retry. *** **Error key:** `request_too_large` **Platform code(s):** `Meta:1` **Message we received:** ```text theme={null} Please reduce the amount of data you're asking for, then retry your request ``` **Why this happens:** The platform rejected the request because it contained too much data, such as too much text, metadata, or media information. **What the user should do:** Ask the user to shorten the post, reduce attached metadata/media, and retry. *** **Error key:** `temporary_platform_error` **Platform code(s):** `HTTP:500`, `HTTP:502`, `HTTP:503`, `HTTP:504`, `Meta:2` **Message we received:** ```text theme={null} proxygen::coro::HTTPError: HTTP source aborted err=INTERNAL_ERROR, details=received RST_STREAM from peer ``` **Why this happens:** The platform returned a temporary server error or service unavailable response. The request reached the platform, but the platform could not complete it. **What the user should do:** Ask the user to retry later. If many posts fail across accounts, treat it as a platform incident and escalate internally. *** **Error key:** `content_policy_restricted` **Platform code(s):** `Meta:368:1404132` **Message we received:** ```text theme={null} You're temporarily blocked from using this feature because you shared something that isn't allowed on Facebook. Learn More. ``` **Why this happens:** The platform rejected or blocked the content because it appears to violate platform rules or automated safety checks. **What the user should do:** Ask the user to review the content, remove risky text or media, and retry. If the platform account is restricted, they must resolve that directly with the platform. *** **Error key:** `media_upload_failed` **Platform code(s):** `Meta:2:1363047`, `Meta:6000:1363048` **Message we received:** ```text theme={null} There was a problem while uploading your video. ``` **Why this happens:** The media upload did not complete successfully. This can be caused by platform upload processing, invalid media, expired upload sessions, or transient platform errors. **What the user should do:** Ask the user to retry. If it repeats, ask them to replace or re-export the media file and try again. *** **Error key:** `unknown_error` **Platform code(s):** `HTTP:404`, `HTTP:500`, `Meta:1`, `Meta:100`, `Meta:100:1366046`, `Meta:1:99`, `NET:ECONNABORTED` **Message we received:** ```text theme={null} Unknown error ``` **Why this happens:** The platform did not return a specific reason. Our system only received a generic or empty error. **What the user should do:** Ask the user to retry once. If it repeats, escalate with the failed post ID, platform, and timestamp so support can inspect the raw platform response. *** **Error key:** `media_processing_failed` **Platform code(s):** `HTTP:400`, `Meta:324:2069019` **Message we received:** ```text theme={null} Request processing failed ``` **Why this happens:** The platform accepted the upload but could not process the media. Common reasons include unsupported format, corrupt file, too large media, or platform processing failure. **What the user should do:** Ask the user to re-export the media in a standard format and retry. For images, use common JPG/PNG. For videos, use MP4/H.264 when possible. *** **Error key:** `media_processing_timeout` **Platform code(s):** `HTTP:502` **Message we received:** ```text theme={null} Video publish timed out ``` **Why this happens:** The platform did not finish processing the media within the expected time. **What the user should do:** Ask the user to retry later or upload a smaller/simpler media file. If many users see this at once, treat it as a platform issue. *** **Error key:** `media_owner_mismatch` **Platform code(s):** `HTTP:403` **Message we received:** ```text theme={null} "success":false,"message":"Supplied user is not the creator of this video ID"; ``` **Why this happens:** The platform says the connected account is not the owner or creator of the media being published. **What the user should do:** Ask the user to publish from the account that owns the media or re-upload the media under the correct connected account. *** **Error key:** `action_temporarily_blocked` **Platform code(s):** `Meta:368:1404078` **Message we received:** ```text theme={null} You have been temporarily blocked from performing this action. ``` **Why this happens:** The platform temporarily blocked the action, commonly because of anti-spam, automation, or policy checks. **What the user should do:** Ask the user to review the post content and account status, wait, then try again. If many posts failed, slow down publishing from that account. *** **Error key:** `network_error` **Platform code(s):** `NET:EAI_AGAIN`, `NET:ECONNRESET` **Message we received:** ```text theme={null} aborted ``` **Why this happens:** A network or DNS error interrupted the request between our system, media storage, and the platform. **What the user should do:** Ask the user to retry. If multiple retries fail or many accounts are affected, escalate to support as an infrastructure/platform connectivity issue. ### Instagram **Error key:** `account_not_confirmed` **Platform code(s):** `Meta:190` **Message we received:** ```text theme={null} Error validating access token: Sessions for the user are not allowed because the user is not a confirmed user. ``` **Why this happens:** The platform requires the account to be confirmed before API publishing is allowed. This can mean email confirmation, account verification, or a required platform checkpoint. **What the user should do:** Ask the user to open the native platform, finish account confirmation, then reconnect the account and retry publishing. *** **Error key:** `account_connection_expired` **Platform code(s):** `Meta:190`, `Meta:190:460` **Message we received:** ```text theme={null} Error validating access token: The session has been invalidated because the user changed their password or Facebook has changed the session for security reasons. ``` **Why this happens:** The access token or session used for publishing is no longer valid. This commonly happens after password changes, security checks, expired OAuth sessions, or token revocation. **What the user should do:** Ask the user to reconnect the platform account. After reconnecting, retry the post. If it fails again immediately, ask them to log into the native platform first and clear any security prompt. *** **Error key:** `unknown_error` **Platform code(s):** `UNKNOWN` **Message we received:** ```text theme={null} Unknown error ``` **Why this happens:** The platform did not return a specific reason. Our system only received a generic or empty error. **What the user should do:** Ask the user to retry once. If it repeats, escalate with the failed post ID, platform, and timestamp so support can inspect the raw platform response. *** **Error key:** `posting_rate_limited` **Platform code(s):** `Meta:9:2207042` **Message we received:** ```text theme={null} Du hast die maximal zulässige Anzahl an durch die Content Publishing API veröffentlichten Beiträgen erreicht. ``` **Why this happens:** Meta is a weird platform sometimes they return messages in diffrent languages. The platform limited publishing frequency, the account reached a hourly publishing cap / was marked as spam. **What the user should do:** Ask the user to wait before retrying. If this happens often, reduce scheduling density for that account. *** **Error key:** `missing_platform_permission` **Platform code(s):** `HTTP:400`, `Meta:10`, `Meta:190`, `Meta:200` **Message we received:** ```text theme={null} Any of the pages_read_engagement, pages_manage_metadata, pages_read_user_content, pages_manage_ads, pages_show_list or pages_messaging permission(s) must be granted before impersonating a user's page. ``` **Why this happens:** Meta rejected the publish because the current token no longer has effective permission to publish as the selected Page linked to the Instagram account. This often happens when the same Meta user connects multiple bundle.social teams and selects only one Page or Instagram account during each OAuth flow. Meta can overwrite page grants for the Bundle app at the Meta-user level, so one team can still look connected while Meta has removed its Page grant remotely. **What the user should do:** Ask the user to reconnect the Meta account. In the Facebook OAuth screen, they should select all Pages and Instagram accounts they manage. Then choose the correct Page or Instagram channel inside bundle.social for that team and retry the failed post. *** **Error key:** `action_temporarily_blocked` **Platform code(s):** `Meta:4:2207051` **Message we received:** ```text theme={null} Wir schränken bestimmte Handlungen ein, um unsere Community zu schützen. Sag uns, wenn wir deiner Meinung nach einen Fehler gemacht haben. ``` **Why this happens:** The platform temporarily blocked the action, commonly because of anti-spam, automation, or policy checks. **What the user should do:** Ask the user to review the post content and account status, wait, then try again. If many posts failed, slow down publishing from that account. *** **Error key:** `account_restricted` **Platform code(s):** `Meta:25:2207050` **Message we received:** ```text theme={null} The Instagram account is restricted. ``` **Why this happens:** The platform has restricted the account from publishing or uploading media. This restriction is enforced by the platform and is outside our direct control. **What the user should do:** Ask the user to open the platform account and check account status, account quality, or support inbox. They need to resolve the restriction on the platform before retrying. *** **Error key:** `media_fetch_failed` **Platform code(s):** `Meta:9004:2207052` **Message we received:** ```text theme={null} Die Mediendatei konnte nicht von dieser URI abgerufen werden: URL Informationen findest du im Abschnitt „Einschränkungen“ in unserer Entwicklerdokumentation: URL ``` **Why this happens:** Instagram could not download the media from the hosted URL. This often happens when Meta's crawler cannot access the file or the URL violates Instagram media-fetch limitations. **What the user should do:** Retry once. If it repeats, escalate so support can verify public HTTPS access, headers, redirects, file availability, and Meta crawler access. *** **Error key:** `account_authorization_revoked` **Platform code(s):** `Meta:190`, `Meta:190:458` **Message we received:** ```text theme={null} Error validating access token: The user has not authorized application ID. ``` **Why this happens:** The user or the platform removed the app authorization. Our system can still see the account record, but the platform no longer accepts the stored permission. **What the user should do:** Ask the user to reconnect the social account in bundle.social and approve all requested permissions again. If the account manages a page, they should also reselect the page during reconnect. *** **Error key:** `video_should_be_reel` **Platform code(s):** `Meta:100:2207089` **Message we received:** ```text theme={null} Media created with media_type=VIDEO is a carousel item and cannot be published as a standalone post. To publish a standalone video, use media_type=REELS instead. ``` **Why this happens:** Instagram rejected the video because this media type must be published as a Reel instead of a standard standalone video post. **What the user should do:** Ask the user to switch the publish type to Reel and retry. *** **Error key:** `media_upload_failed` **Platform code(s):** `HTTP:502`, `Meta:-1:2207032` **Message we received:** ```text theme={null} Media upload failed, Instagram did not returned status about your upload ``` **Why this happens:** The media upload did not complete successfully. This can be caused by platform upload processing, invalid media, expired upload sessions, or transient platform errors. **What the user should do:** Ask the user to retry. If it repeats, ask them to replace or re-export the media file and try again. *** **Error key:** `platform_login_required` **Platform code(s):** `Meta:190:459` **Message we received:** ```text theme={null} You cannot access the app till you log in to www.facebook.com and follow the instructions given. ``` **Why this happens:** The platform requires the user to log in and complete an account checkpoint before API publishing can continue, just to be sure that this is not a bot but a real person. **What the user should do:** Ask the user to log into the platform website or mobile app, complete any prompt, then reconnect and retry. *** **Error key:** `page_or_target_inaccessible` **Platform code(s):** `Meta:100:33`, `Meta:190` **Message we received:** ```text theme={null} This Page access token belongs to a Page that is not accessible. ``` **Why this happens:** The selected page, profile, community, location, or publishing target is not accessible to the connected account anymore. **What the user should do:** Ask the user to confirm they still have access to that target on the platform. Then reconnect the account and reselect the page/profile if needed. *** **Error key:** `tagged_user_inaccessible` **Platform code(s):** `Meta:110:2207018` **Message we received:** ```text theme={null} Отсутствует доступ к следующим пользователям: erikwist04 ``` **Why this happens:** The platform could not access one or more tagged users. The tagged account may be private, invalid, blocked, or not eligible for tagging. **What the user should do:** On Instagram the post still goes out: we publish it without the rejected users, list them in `externalData.INSTAGRAM.skippedTags` and leave a `Posted without the Instagram tag(s) ...` warning in `errors.INSTAGRAM` while the post is `POSTED`. Ask the user to check the handles if the tag matters. On other platforms, remove or change the tagged users and retry. *** **Error key:** `media_fetch_timeout` **Platform code(s):** `Meta:-2:2207003` **Message we received:** ```text theme={null} Das Herunterladen der Medien dauert zu lange. ``` **Why this happens:** The platform took too long to download the media file. **What the user should do:** Ask the user to retry later or use a smaller media file. Escalate if the same media repeatedly times out. *** **Error key:** `temporary_platform_error` **Platform code(s):** `Meta:2` **Message we received:** ```text theme={null} An unexpected error has occurred. Please retry your request later. ``` **Why this happens:** The platform returned a temporary server error or service unavailable response. The request reached the platform, but the platform could not complete it. **What the user should do:** Ask the user to retry later. If many posts fail across accounts, treat it as a platform incident and escalate internally. *** **Error key:** `network_error` **Platform code(s):** `NET:EAI_AGAIN`, `NET:ECONNRESET` **Message we received:** ```text theme={null} getaddrinfo EAI_AGAIN graph.facebook.com ``` **Why this happens:** A network or DNS error interrupted the request between our system, media storage, and the platform. **What the user should do:** Ask the user to retry. If multiple retries fail or many accounts are affected, escalate to support as an infrastructure/platform connectivity issue. *** **Error key:** `tagged_user_not_allowed` **Platform code(s):** `Meta:210:2207066` **Message we received:** ```text theme={null} The user cannot be tagged on this media. ``` **Why this happens:** The platform says one of the selected users cannot be tagged on this media. **What the user should do:** Ask the user to remove that tag and retry. *** **Error key:** `invalid_location` **Platform code(s):** `Meta:100` **Message we received:** ```text theme={null} Param location_id is not a valid location page ID ``` **Why this happens:** The selected location is not valid for the platform endpoint or cannot be used with this post. **What the user should do:** Ask the user to remove the location or choose another valid location, then retry. *** **Error key:** `too_few_followers_for_feature` **Platform code(s):** `Meta:10:2207081` **Message we received:** ```text theme={null} Dieses Instagram-Konto hat zu wenige Follower, um Test-Reels erstellen zu können. ``` **Why this happens:** The account does not meet the platform requirements for this publishing feature. Likley a TRAIL reels. **What the user should do:** Ask the user to use another publish type or wait until the account meets the platform eligibility requirements. *** **Error key:** `too_many_tags` **Platform code(s):** `Meta:100:2207040` **Message we received:** ```text theme={null} Es dürfen nicht mehr als 30 Tags pro Medienerstellung verwendet werden. ``` **Why this happens:** The platform rejected the post because it contains too many tags. **What the user should do:** Ask the user to reduce the number of tags and retry. ### TikTok **Error key:** `unknown_error` **Platform code(s):** - **Message we received:** ```text theme={null} Unknown error ``` **Why this happens:** The platform did not return a specific reason. Our system only received a generic or empty error. **What the user should do:** Ask the user to retry once. If it repeats, escalate with the failed post ID, platform, and timestamp so support can inspect the raw platform response. *** **Error key:** `account_connection_expired` **Platform code(s):** `HTTP:422`, `HTTP:502` **Message we received:** ```text theme={null} Access token is incorrect or has been revoked. ``` **Why this happens:** The access token or session used for publishing is no longer valid. This commonly happens after password changes, security checks, expired OAuth sessions, token revocation or just "because". **What the user should do:** Ask the user to reconnect the platform account. After reconnecting, retry the post. If it fails again immediately, ask them to log into the native platform first and clear any security prompt. *** **Error key:** `media_processing_timeout` **Platform code(s):** `HTTP:504` **Message we received:** ```text theme={null} Media upload failed, TikTok did not process your upload in time ``` **Why this happens:** In around 50% of cases, the user posted the TikTok as private, so we could not retrieve the post ID. In around 25% of cases, TikTok is slow or overloaded. In the remaining cases, the content was too large and the platform did not finish processing the media within the expected time. **What the user should do:** Check privacy settings, try again in a bit or upload a smaller media file. If many users see this at once, treat it as a platform issue. *** **Error key:** `unsupported_file_format` **Platform code(s):** `HTTP:422` **Message we received:** ```text theme={null} Media upload failed with reason: file_format_check_failed ``` **Why this happens:** The platform rejected the media because the file format, codec, or dimensions are not supported. If the media is an image, avoid PNG and make sure it is not larger than Full HD in either dimension. We also provide a resize option in the post fields if the media needs to be adjusted automatically. **What the user should do:** Convert the media to a supported format and retry. For videos, MP4 with H.264 is usually the safest option. For images, use JPG/JPEG and keep the resolution within platform limits. *** **Error key:** `posting_rate_limited` **Platform code(s):** `HTTP:502` **Message we received:** ```text theme={null} This TikTok creator has made too many posts via OpenAPI in the last 24 hours, so this publishing attempt is blocked to minimize spam. The user can try again later or publish it in the mobile app instead. ``` **Why this happens:** The platform limited publishing frequency or the account reached a daily publishing cap of 15. **What the user should do:** Ask the user to wait 24h before retrying. *** **Error key:** `content_policy_restricted` **Platform code(s):** `HTTP:422` **Message we received:** ```text theme={null} Media upload failed with reason: spam_risk ``` **Why this happens:** The platform rejected or blocked the content because it appears to violate platform rules or automated safety checks. **What the user should do:** Ask the user to review the content, remove risky text or media, and retry. If the platform account is restricted, they must resolve that directly with the platform. *** **Error key:** `image_size_invalid` **Platform code(s):** `HTTP:422` **Message we received:** ```text theme={null} Media upload failed with reason: picture_size_check_failed ``` **Why this happens:** The uploaded image does not match the platform’s image size, dimension, or resolution requirements. The safest option is JPG/JPEG with a maximum resolution of Full HD. **What the user should do:** Ask the user to resize or replace the image according to the platform requirements, then retry. *** **Error key:** `temporary_platform_error` **Platform code(s):** `HTTP:502`, `HTTP:503`, `HTTP:504` **Message we received:** ```text theme={null} Something went wrong. Please try again later. ``` **Why this happens:** The platform returned a temporary server error or service unavailable response. The request reached the platform, but the platform could not complete it. **What the user should do:** Ask the user to retry later. If many posts fail across accounts, treat it as a platform incident and escalate internally. *** **Error key:** `account_restricted` **Platform code(s):** `HTTP:422` **Message we received:** ```text theme={null} Media upload failed with reason: spam_risk_user_banned_from_posting ``` **Why this happens:** The platform has restricted the account from publishing or uploading media. This restriction is enforced by the platform and is outside our direct control. **What the user should do:** Ask the user to open the platform account and check account status, account quality, or support inbox. They need to resolve the restriction on the platform before retrying. *** **Error key:** `video_frame_rate_invalid` **Platform code(s):** `HTTP:422` **Message we received:** ```text theme={null} Media upload failed with reason: frame_rate_check_failed ``` **Why this happens:** The video frame rate does not match the platform requirements. **What the user should do:** Ask the user to re-export the video with a supported frame rate and retry. *** **Error key:** `invalid_request_parameters` **Platform code(s):** `HTTP:403`, `HTTP:502`, `TT:50001` **Message we received:** ```text theme={null} missing or invalid request id ``` **Why this happens:** The platform rejected a request parameter. This can happen when a value is malformed, expired, or no longer accepted by the platform. **What the user should do:** Ask the user to retry after refreshing the post setup. If it repeats, escalate because engineering may need to inspect the exact request values. *** **Error key:** `network_error` **Platform code(s):** `HTTP:502`, `NET:EAI_AGAIN`, `NET:ECONNRESET` **Message we received:** ```text theme={null} read ECONNRESET ``` **Why this happens:** A network or DNS error interrupted the request between our system, media storage, and the platform. **What the user should do:** Ask the user to retry. If multiple retries fail or many accounts are affected, escalate to support as an infrastructure/platform connectivity issue. *** **Error key:** `media_fetch_failed` **Platform code(s):** `HTTP:422`, `HTTP:502` **Message we received:** ```text theme={null} Media upload failed with reason: photo_pull_failed ``` **Why this happens:** The platform could not download the media from our hosted URL. This usually means the platform crawler was blocked, received 403, or could not access the media in time. **What the user should do:** Retry the post first. If it repeats, escalate to support so we can check media URL accessibility, storage headers, robots/bot blocking, and platform crawler access. *** **Error key:** `media_upload_failed` **Platform code(s):** `HTTP:422` **Message we received:** ```text theme={null} Media upload failed with reason: internal ``` **Why this happens:** The media upload did not complete successfully. This can be caused by platform upload processing, invalid media, expired upload sessions, or transient platform errors. **What the user should do:** Ask the user to retry. If it repeats, ask them to replace or re-export the media file and try again. If you see this a lot it's a platform wide issue. *** **Error key:** `media_url_verification_failed` **Platform code(s):** `HTTP:502` **Message we received:** ```text theme={null} Please review our URL ownership verification rules at URL ``` **Why this happens:** The platform requires the media URL or domain to be verified before it can pull media from that URL. **What the user should do:** Escalate to support. This is usually an integration or domain verification issue, not something the end user can fix directly. ### YouTube **Error key:** `account_suspended` **Platform code(s):** `YT:authenticatedUserAccountSuspended` **Message we received:** ```text theme={null} The YouTube account of the authenticated user is suspended. In case the authenticated user is acting on behalf of another Google account, then this error refers to the latter. ``` **Why this happens:** The platform reports that the account or channel is suspended. Suspended accounts cannot publish through the API. **What the user should do:** Ask the user to resolve the suspension directly with the platform. Publishing can resume only after the platform restores the account. *** **Error key:** `youtube_upload_limit_reached` **Platform code(s):** `YT:uploadLimitExceeded` **Message we received:** ```text theme={null} The user has exceeded the number of videos they may upload. ``` **Why this happens:** YouTube rejected the upload because the channel exceeded its current upload allowance. YouTube documents daily upload limits and API upload limits for safety. **What the user should do:** Ask the user to wait until the upload limit resets, usually up to 24 hours, then retry. *** **Platform code(s):** `YT:orgDailyUploadLimit` **Message we received:** ```text theme={null} Your organization reached its daily YouTube upload limit (N videos). It resets at midnight Pacific Time. ``` **Why this happens:** bundle.social caps how many new YouTube videos one organization can upload per day, counted across all its YouTube accounts. The day follows YouTube's own quota day and resets at midnight Pacific Time. Resuming an upload that already started doesn't count. The error is not retried automatically, so the YouTube part of the post ends in `ERROR`. **What the user should do:** Publish the video again after midnight Pacific Time. If your organization regularly needs more uploads per day, [contact us](https://bundle.social/contact). *** **Platform code(s):** `YT:uploadCapacityExhausted` **Message we received:** ```text theme={null} YouTube's daily upload capacity is currently exhausted. It resets at midnight Pacific Time, please retry after that. ``` **Why this happens:** YouTube's daily upload quota for our API project was used up. For a while after that, new YouTube uploads fail right away with this error, so they don't each wait for YouTube to refuse them. It isn't retried automatically. **What the user should do:** Publish the video again after midnight Pacific Time. *** **Error key:** `unknown_error` **Platform code(s):** - **Message we received:** ```text theme={null} Unknown error ``` **Why this happens:** The platform did not return a specific reason. Our system only received a generic or empty error. **What the user should do:** Ask the user to retry once. If it repeats, escalate with the failed post ID, platform, and timestamp so support can inspect the raw platform response. *** **Error key:** `youtube_account_service_forbidden` **Platform code(s):** `YT:forbidden`, `YT:unsupportedSupervisedAccount` **Message we received:** ```text theme={null} Access Forbidden. The authenticated user cannot access this service. ``` **Why this happens:** YouTube says this authenticated account cannot access the upload service. This can happen for supervised, restricted, or ineligible accounts. **What the user should do:** Ask the user to check YouTube account settings or use an eligible YouTube channel. Reconnect after the account is eligible. *** **Error key:** `account_connection_expired` **Platform code(s):** `YT:authError` **Message we received:** ```text theme={null} Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See URL ``` **Why this happens:** The access token or session used for publishing is no longer valid. This commonly happens after password changes, security checks, expired OAuth sessions, token revocation or just "because". **What the user should do:** Ask the user to reconnect the platform account. After reconnecting, retry the post. If it fails again immediately, ask them to log into the native platform first and clear any security prompt. *** **Error key:** `youtube_signup_required` **Platform code(s):** `YT:youtubeSignupRequired` **Message we received:** ```text theme={null} Unauthorized ``` **Why this happens:** The Google account is not fully set up as a YouTube channel for uploads. **What the user should do:** Ask the user to complete YouTube channel setup, then reconnect YouTube and retry. *** **Error key:** `invalid_video_title` **Platform code(s):** `YT:invalidTitle` **Message we received:** ```text theme={null} The request metadata specifies an invalid or empty video title. ``` **Why this happens:** YouTube rejected the upload because the title is missing or invalid. **What the user should do:** Ask the user to add a valid title and retry. Avoid empty titles or unsupported characters. ### LinkedIn **Error key:** `account_restricted` **Platform code(s):** `HTTP:401` **Message we received:** ```text theme={null} Member is restricted ``` **Why this happens:** The platform has restricted the account from publishing or uploading media. This restriction is enforced by the platform and is outside our direct control. **What the user should do:** Ask the user to open the platform account and check account status, account quality, or support inbox. They need to resolve the restriction on the platform before retrying. *** **Error key:** `missing_platform_permission` **Platform code(s):** `HTTP:403` **Message we received:** ```text theme={null} Accessing this image resource is forbidden. Please check your permissions for this resource ``` **Why this happens:** LinkedIn rejected access to the image or video resource. LinkedIn requires the token and owner to match the member/page/organization that owns the media. **What the user should do:** Ask the user to reconnect LinkedIn and confirm they are publishing to a page or profile they administer. If the media was uploaded under another owner, upload it again under the correct account. *** **Error key:** `temporary_platform_error` **Platform code(s):** `HTTP:500`, `HTTP:503`, `HTTP:524` **Message we received:** ```text theme={null} [IncomingMessage] ``` **Why this happens:** The platform returned a temporary server error or service unavailable response. The request reached the platform, but the platform could not complete it. **What the user should do:** Ask the user to retry later. If many posts fail across accounts, treat it as a platform incident and escalate internally. *** **Error key:** `account_authorization_revoked` **Platform code(s):** `HTTP:401` **Message we received:** ```text theme={null} The token used in the request has been revoked by the user ``` **Why this happens:** The user or the platform removed the app authorization. Our system can still see the account record, but the platform no longer accepts the stored permission. **What the user should do:** Ask the user to reconnect the social account in bundle.social and approve all requested permissions again. If the account manages a page, they should also reselect the page during reconnect. *** **Error key:** `network_error` **Platform code(s):** `HTTP:502`, `NET:EAI_AGAIN`, `NET:ECONNRESET` **Message we received:** ```text theme={null} connect ETIMEDOUT 108.174.10.22:443 ``` **Why this happens:** A network or DNS error interrupted the request between our system, media storage, and the platform. **What the user should do:** Ask the user to retry. If multiple retries fail or many accounts are affected, escalate to support as an infrastructure/platform connectivity issue. *** **Error key:** `duplicate_content` **Platform code(s):** `LI:422` **Message we received:** ```text theme={null} com.linkedin.content.common.exception.BadRequestResponseException: Content is a duplicate of URN ``` **Why this happens:** The platform detected that the post duplicates content that was already published or recently submitted. **What the user should do:** Ask the user to change the text or media meaningfully, then publish again. *** **Error key:** `media_processing_failed` **Platform code(s):** `HTTP:422` **Message we received:** ```text theme={null} LinkedIn processing failed for image ``` **Why this happens:** The platform accepted the upload but could not process the media. Common reasons include unsupported format, corrupt file, too large media, or platform processing failure. **What the user should do:** Ask the user to re-export the media in a standard format and retry. For images, use common JPG/PNG. For videos, use MP4/H.264 when possible. *** **Error key:** `media_processing_timeout` **Platform code(s):** `HTTP:504` **Message we received:** ```text theme={null} No final status after 6 attempts ``` **Why this happens:** The platform did not finish processing the media within the expected time. **What the user should do:** Ask the user to retry later or upload a smaller/simpler media file. If many users see this at once, treat it as a platform issue. ### X / Twitter **Error key:** `action_not_permitted` **Platform code(s):** `HTTP:403`, `TW:403` **Message we received:** ```text theme={null} You are not permitted to perform this action. ``` **Why this happens:** The platform does not allow the connected account to perform this action. This can be caused by account type, role, missing permission, or platform-side restriction. **What the user should do:** Ask the user to confirm they are using the correct account, page, and role. If the action is still blocked, reconnect the account and retry with a simpler post. *** **Error key:** `account_suspended` **Platform code(s):** `HTTP:403`, `TW:user-suspended` **Message we received:** ```text theme={null} Request failed with code 403 - Your account is suspended and is not permitted to access this feature. (Twitter code 64) ``` **Why this happens:** The platform reports that the account or channel is suspended. Suspended accounts cannot publish through the API. **What the user should do:** Ask the user to resolve the suspension directly with the platform. Publishing can resume only after the platform restores the account. *** **Error key:** `account_temporarily_locked` **Platform code(s):** `HTTP:403`, `HTTP:502`, `TW:403` **Message we received:** ```text theme={null} Your account is temporarily locked. Please log in to URL to unlock your account. ``` **Why this happens:** The platform temporarily locked the account, usually due to security or anti-spam checks. **What the user should do:** Ask the user to log into the native platform and complete the unlock flow. After the account is unlocked, reconnect if needed and retry. *** **Error key:** `temporary_platform_error` **Platform code(s):** `HTTP:500`, `HTTP:503`, `HTTP:520`, `HTTP:522`, `NET:503`, `TW:503` **Message we received:** ```text theme={null} Request failed with code 503 ``` **Why this happens:** X/Twitter returned a temporary server or media-service error. This is usually not caused by the post content. **What the user should do:** Ask the user to retry later. If media upload status remains stuck or many accounts fail, escalate as a platform/media upload issue. *** **Error key:** `account_connection_expired` **Platform code(s):** `HTTP:401`, `TW:401` **Message we received:** ```text theme={null} Request failed with code 401 - Invalid or expired token (Twitter code 89) ``` **Why this happens:** The access token or session used for publishing is no longer valid. This commonly happens after password changes, security checks, expired OAuth sessions, token revocation or just "because". **What the user should do:** Ask the user to reconnect the platform account. After reconnecting, retry the post. If it fails again immediately, ask them to log into the native platform first and clear any security prompt. *** **Error key:** `duplicate_content` **Platform code(s):** `TW:403` **Message we received:** ```text theme={null} You are not allowed to create a Tweet with duplicate content. ``` **Why this happens:** The platform detected that the post duplicates content that was already published or recently submitted. **What the user should do:** Ask the user to change the text or media meaningfully, then publish again. *** **Error key:** `video_duration_too_long` **Platform code(s):** `TW:403` **Message we received:** ```text theme={null} This user is not allowed to post a video longer than 2 minutes. ``` **Why this happens:** The video is longer than the platform or account allows. **What the user should do:** Ask the user to shorten the video or publish it directly on the platform if that account supports longer videos there. *** **Error key:** `crypto_address_restriction` **Platform code(s):** `TW:403` **Message we received:** ```text theme={null} Crypto addresses are prohibited for the first 7 days after authentication. ``` **Why this happens:** X/Twitter restricts crypto addresses for newly authenticated accounts during an initial safety period. **What the user should do:** Ask the user to remove the crypto address from the post or wait until the platform restriction period ends. *** **Error key:** `access_package_limitation` **Platform code(s):** `TW:403` **Message we received:** ```text theme={null} Creating posts with @mentions is not allowed for your access package. In replies to conversations you are part of, you may only @mention users who are already participants in the thread. ``` **Why this happens:** The connected account or API access level does not allow this publishing feature. In the observed X/Twitter case, posts with certain @mentions are blocked by the current access package. **What the user should do:** Ask the user to remove the restricted feature from the post, such as unsupported @mentions, or confirm that their X API access level supports it. Escalate only if the account should have this access. *** **Error key:** `invalid_media_reference` **Platform code(s):** `TW:invalid-request` **Message we received:** ```text theme={null} Your media IDs are invalid. ``` **Why this happens:** The platform rejected the media ID or media reference. This usually means the media upload did not finish correctly or the reference expired. **What the user should do:** Ask the user to upload the media again and retry publishing. If it repeats, escalate with the failed media/post ID. *** **Error key:** `network_error` **Platform code(s):** `NET:EAI_AGAIN`, `NET:ECONNRESET` **Message we received:** ```text theme={null} aborted ``` **Why this happens:** A network or DNS error interrupted the request between our system, media storage, and the platform. **What the user should do:** Ask the user to retry. If multiple retries fail or many accounts are affected, escalate to support as an infrastructure/platform connectivity issue. *** **Error key:** `media_processing_timeout` **Platform code(s):** `HTTP:504` **Message we received:** ```text theme={null} No terminal state after repeated checks ``` **Why this happens:** The platform did not finish processing the media within the expected time. **What the user should do:** Ask the user to retry later or upload a smaller/simpler media file. If many users see this at once, treat it as a platform issue. ### Threads **Error key:** `unknown_error` **Platform code(s):** `Meta:1` **Message we received:** ```text theme={null} Unknown error ``` **Why this happens:** The platform did not return a specific reason. Our system only received a generic or empty error. **What the user should do:** Ask the user to retry once. If it repeats, escalate with the failed post ID, platform, and timestamp so support can inspect the raw platform response. *** **Error key:** `media_upload_failed` **Platform code(s):** `HTTP:502`, `Meta:1:2207032` **Message we received:** ```text theme={null} Media upload failed, Threads did not returned status about your upload ``` **Why this happens:** The media upload did not complete successfully. This can be caused by platform upload processing, invalid media, expired upload sessions, or transient platform errors. **What the user should do:** Ask the user to retry. If it repeats, ask them to replace or re-export the media file and try again. *** **Error key:** `action_temporarily_blocked` **Platform code(s):** `Meta:1:2207051` **Message we received:** ```text theme={null} We restrict certain activity to protect our community. Tell us if you think we made a mistake. ``` **Why this happens:** The platform temporarily blocked the action, commonly because of anti-spam, automation, or policy checks. **What the user should do:** Ask the user to review the post content and account status, wait, then try again. If many posts failed, slow down publishing from that account. *** **Error key:** `media_fetch_failed` **Platform code(s):** `Meta:1:2207052` **Message we received:** ```text theme={null} The media could not be fetched from this URI: URL check the limitations section in our development document for more information: URL ``` **Why this happens:** Threads could not fetch the media from the hosted URL. Threads publishing uses Meta infrastructure, so crawler access and media URL availability matter. **What the user should do:** Retry once. If it repeats, escalate so support can verify that the media URL is reachable by Meta/Threads and is not blocked. *** **Error key:** `account_restricted` **Platform code(s):** `Meta:25:4279013` **Message we received:** ```text theme={null} Das Instagram- oder Threads-Konto wurde eingeschränkt. ``` **Why this happens:** The platform has restricted the account from publishing or uploading media. This restriction is enforced by the platform and is outside our direct control. **What the user should do:** Ask the user to open the platform account and check account status, account quality, or support inbox. They need to resolve the restriction on the platform before retrying. *** **Error key:** `temporary_platform_error` **Platform code(s):** `Meta:2` **Message we received:** ```text theme={null} An unexpected error has occurred. Please retry your request later. ``` **Why this happens:** The platform returned a temporary server error or service unavailable response. The request reached the platform, but the platform could not complete it. **What the user should do:** Ask the user to retry later. If many posts fail across accounts, treat it as a platform incident and escalate internally. *** **Error key:** `media_fetch_timeout` **Platform code(s):** `Meta:1:2207003` **Message we received:** ```text theme={null} Das Herunterladen der Medien dauert zu lange. ``` **Why this happens:** The platform took too long to download the media file. **What the user should do:** Ask the user to retry later or use a smaller media file. Escalate if the same media repeatedly times out. *** **Error key:** `network_error` **Platform code(s):** `NET:EAI_AGAIN` **Message we received:** ```text theme={null} getaddrinfo EAI_AGAIN graph.threads.net ``` **Why this happens:** A network or DNS error interrupted the request between our system, media storage, and the platform. **What the user should do:** Ask the user to retry. If multiple retries fail or many accounts are affected, escalate to support as an infrastructure/platform connectivity issue. ### Pinterest **Error key:** `media_processing_timeout` **Platform code(s):** `PIN:PIN:UNKNOWN` **Message we received:** ```text theme={null} Media upload failed, Pinterest did not return status ``` **Why this happens:** The platform did not finish processing the media within the expected time. **What the user should do:** Ask the user to retry later or upload a smaller/simpler media file. If many users see this at once, treat it as a platform issue. *** **Error key:** `temporary_platform_error` **Platform code(s):** `PIN:12`, `PIN:2787` **Message we received:** ```text theme={null} Something went wrong on our end. Sorry about that. ``` **Why this happens:** The platform returned a temporary server error or service unavailable response. The request reached the platform, but the platform could not complete it. **What the user should do:** Ask the user to retry later. If many posts fail across accounts, treat it as a platform incident and escalate internally. *** **Error key:** `account_connection_expired` **Platform code(s):** `PIN:2` **Message we received:** ```text theme={null} Authentication failed. ``` **Why this happens:** Pinterest rejected authentication. Pinterest documents common token issues such as expired/invalid token, expired user session, or insufficient scopes. **What the user should do:** Ask the user to reconnect Pinterest and grant the required scopes, then retry. *** **Error key:** `board_name_exists` **Platform code(s):** `PIN:58` **Message we received:** ```text theme={null} Try a different name. You already have a board with this name! ``` **Why this happens:** Pinterest rejected the request because the account already has a board with the same name. **What the user should do:** Ask the user to choose a different board name or select the existing board instead of creating a new one. *** **Error key:** `media_fetch_failed` **Platform code(s):** `PIN:2786` **Message we received:** ```text theme={null} Unable to reach the URL. Please check the URL is correct and try again. ``` **Why this happens:** The platform could not download the media from our hosted URL. This usually means the platform crawler was blocked, received 403, or could not access the media in time. **What the user should do:** Retry the post first. If it repeats, escalate to support so we can check media URL accessibility, storage headers, robots/bot blocking, and platform crawler access. *** **Error key:** `network_error` **Platform code(s):** `NET:EAI_AGAIN` **Message we received:** ```text theme={null} getaddrinfo EAI_AGAIN private-storage.bundle.social ``` **Why this happens:** A network or DNS error interrupted the request between our system, media storage, and the platform. **What the user should do:** Ask the user to retry. If multiple retries fail or many accounts are affected, escalate to support as an infrastructure/platform connectivity issue. ### Reddit **Error key:** `community_does_not_allow_images` **Platform code(s):** `RD:RD:NO_IMAGES` **Message we received:** ```text theme={null} This community doesn't allow images ``` **Why this happens:** The selected Reddit community does not allow image posts. **What the user should do:** Ask the user to publish without an image or choose another community that allows images. *** **Error key:** `post_flair_required` **Platform code(s):** `RD:RD:SUBMIT_VALIDATION_FLAIR_REQUIRED` **Message we received:** ```text theme={null} Your post must contain post flair. ``` **Why this happens:** The selected Reddit community requires post flair. **What the user should do:** Ask the user to choose a flair for the post or select another community. *** **Error key:** `post_title_required` **Platform code(s):** `RD:RD:NO_TEXT` **Message we received:** ```text theme={null} Post title is required ``` **Why this happens:** The platform requires a title for this post. **What the user should do:** Ask the user to add a post title and retry. *** **Error key:** `trusted_members_only` **Platform code(s):** `RD:RD:SUBREDDIT_NOTALLOWED` **Message we received:** ```text theme={null} This community only allows trusted members to post here ``` **Why this happens:** The selected Reddit community only allows trusted members to post. **What the user should do:** Ask the user to choose another community or request posting access from that community's moderators. ### Bluesky **Error key:** `media_file_too_large` **Platform code(s):** `BSKY:400`, `BSKY:502` **Message we received:** ```text theme={null} This file is too large. It is SIZE but the maximum size is SIZE. ``` **Why this happens:** Bluesky rejected the media because it exceeded a file-size limit. Bluesky applies upload size limits at the PDS/video service level and may also have application-specific media limits. **What the user should do:** Ask the user to compress the media or upload a smaller file, then retry. 1 Mb max. *** **Error key:** `media_upload_failed` **Platform code(s):** `BSKY:502` **Message we received:** ```text theme={null} video.uploadVideo failed: http_401 ``` **Why this happens:** The media upload did not complete successfully. This can be caused by platform upload processing, invalid media, expired upload sessions, or transient platform errors. **What the user should do:** Ask the user to retry. If it repeats, ask them to replace or re-export the media file and try again. *** **Error key:** `internal_error` **Platform code(s):** `BSKY:UNKNOWN` **Message we received:** ```text theme={null} Cannot read properties of null (reading 'substring') ``` **Why this happens:** A technical error happened while preparing or sending the request. The platform did not provide a user-fixable reason. **What the user should do:** Ask the user to retry once. If it repeats with the same post, escalate to support with the failed post ID and platform. ### Google Business **Error key:** `invalid_request_arguments` **Platform code(s):** `GB:INVALID_ARGUMENT` **Message we received:** ```text theme={null} Request contains an invalid argument. ``` **Why this happens:** The platform rejected one or more post settings as invalid. This is usually a validation problem with the post payload, media, or selected account/location. **What the user should do:** Review the post settings first. Ask the user to simplify the post, remove optional settings, or retry with valid media and account selections. ### Mastodon **Error key:** `temporary_platform_error` **Platform code(s):** `MST:503` **Message we received:** ```text theme={null} This page is not correct - Mastodon We're sorry, but something went wrong on our end. You can check our status page to have more informations about our maintenances or incidents. ``` **Why this happens:** The platform returned a temporary server error or service unavailable response. The request reached the platform, but the platform could not complete it. **What the user should do:** Ask the user to retry later. If many posts fail across accounts, treat it as a platform incident and escalate internally. > [!TIP] > > This list is also available in CSV format for ease of use. You can download it [here](/most-common-platform-errors.csv). > [!NOTE] > > If you see a weird error code that is not here let us now. # Examples Source: https://info.bundle.social/api-reference/examples Working code, not pseudocode. Examples for schedulers, analytics dashboards, bulk uploaders, and webhook handlers, plus a GitHub repo and Postman collection. We're actively building out a library of examples covering common use cases - schedulers, analytics dashboards, bulk uploaders, webhook handlers, and more. This section is growing, so check back often. ## Select A Channel After OAuth For Facebook, Instagram through Facebook Login, LinkedIn, YouTube, and Google Business, OAuth alone is not enough. After the user connects, select the page, profile, channel, or location they want this team to use. ```ts theme={null} await fetch("https://api.bundle.social/api/v1/social-account/set-channel", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.BUNDLE_API_KEY }, body: JSON.stringify({ teamId: "team_123", type: "FACEBOOK", channelId: "page_123" }) }); ``` Use `refresh-channels` before showing a custom picker if your cached channel list may be stale. ```ts theme={null} await fetch("https://api.bundle.social/api/v1/social-account/refresh-channels", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.BUNDLE_API_KEY }, body: JSON.stringify({ teamId: "team_123", type: "FACEBOOK" }) }); ``` ## Create A Scheduled Post ```ts theme={null} await fetch("https://api.bundle.social/api/v1/post", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.BUNDLE_API_KEY }, body: JSON.stringify({ teamId: "team_123", title: "Launch post", status: "SCHEDULED", postDate: "2026-06-01T15:00:00.000Z", socialAccountTypes: ["FACEBOOK", "INSTAGRAM"], data: { FACEBOOK: { type: "POST", text: "We are live.", uploadIds: ["upload_image_123"] }, INSTAGRAM: { type: "POST", text: "We are live.", uploadIds: ["upload_image_123"], altText: "Product dashboard screenshot" } } }) }); ``` ## Safe Retries With `referenceKey` Set `referenceKey` to your own ID for the post (1-128 characters, trimmed). It's unique per organization among posts that aren't deleted, so a retry after a timeout can't create the post twice. ```ts theme={null} const res = await fetch("https://api.bundle.social/api/v1/post", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.BUNDLE_API_KEY }, body: JSON.stringify({ teamId: "team_123", title: "Launch post", referenceKey: "campaign-42-launch", status: "SCHEDULED", postDate: "2026-06-01T15:00:00.000Z", socialAccountTypes: ["FACEBOOK"], data: { FACEBOOK: { type: "POST", text: "We are live." } } }) }); if (res.status === 409) { // Already created by an earlier attempt: fetch it instead. const post = await fetch( "https://api.bundle.social/api/v1/post/reference-key/campaign-42-launch", { headers: { "x-api-key": process.env.BUNDLE_API_KEY } } ).then((r) => r.json()); } ``` * Creating (or updating) a post with a key another post already uses returns `409` with `A post with this referenceKey already exists in this organization`. * `GET /api/v1/post/reference-key/{referenceKey}` returns the post, like `GET /api/v1/post/{id}`. URL-encode the key if it has special characters. * Once a post is deleted, its key can be used again. ## Fetch Raw Analytics Raw analytics return the raw payload stored for the newest analytics snapshot. Availability depends on platform. ```ts theme={null} const response = await fetch( "https://api.bundle.social/api/v1/analytics/social-account/raw?teamId=team_123&platformType=FACEBOOK", { headers: { "x-api-key": process.env.BUNDLE_API_KEY } } ); const rawAnalytics = await response.json(); ``` ## Handle Post Webhooks There is no separate `post.failed` event. Use `post.published` and inspect `data.status`. ```ts theme={null} export async function handleWebhook(event: { type: string; data: { id: string; status?: string; errors?: unknown }; }) { if (event.type !== "post.published") return; if (event.data.status === "ERROR") { await markPostFailed(event.data.id, event.data.errors); return; } if (event.data.status === "POSTED") { await markPostPublished(event.data.id); } } ``` ## More Resources > [card] [GitHub repo with examples](https://github.com/bundleglobal/bundlesocial-examples) > [card] [Postman collection](https://www.postman.com/socialmediaapibundle/bundle-social-social-media-api/overview) # Health Source: https://info.bundle.social/api-reference/health Check API and platform health before sending users into broken flows. GET /api/v1 returns live per-platform status so you can disable what is down. `GET /api/v1/` returns the current API health object. It now includes `platforms`, where every supported platform has a current `status` and an internal `note`. Use this endpoint to decide whether parts of your app should stay active, be disabled, or show a message before a user starts a flow that may fail. > [!WARNING] > > Do not display `note` directly to end users. Treat it as technical context for your product logic, support team, or internal dashboards. ## Endpoint **Endpoint:** `GET /api/v1/` ```json theme={null} { "status": "ok", "createdAt": "2026-04-27T10:00:00.000Z", "note": "", "platforms": { "FACEBOOK": { "status": "operational", "note": "" }, "INSTAGRAM": { "status": "degraded", "note": "Instagram publishing is slower than usual" }, "TIKTOK": { "status": "maintenance", "note": "TikTok OAuth is temporarily paused" }, "YOUTUBE": { "status": "operational", "note": "" }, "SNAPCHAT": { "status": "operational", "note": "" }, "TWITTER": { "status": "operational", "note": "" }, "PINTEREST": { "status": "operational", "note": "" }, "REDDIT": { "status": "operational", "note": "" }, "MASTODON": { "status": "operational", "note": "" }, "DISCORD": { "status": "operational", "note": "" }, "SLACK": { "status": "operational", "note": "" }, "BLUESKY": { "status": "operational", "note": "" }, "GOOGLE_BUSINESS": { "status": "outage", "note": "Google Business API is rejecting requests" }, "LINKEDIN": { "status": "operational", "note": "" }, "THREADS": { "status": "operational", "note": "" } } } ``` ## Platform Statuses | Status | Meaning | Recommended behavior | | :- | :- | :- | | `operational` | Platform is working normally. | Keep features enabled. | | `degraded` | Platform is partially working or slower than usual. | Keep features available, but show a soft warning if the flow is user-visible. | | `maintenance` | Platform is intentionally paused or limited. | Disable the affected flow and let users try again later. | | `outage` | Platform is currently unavailable. | Disable actions that depend on this platform and avoid sending doomed requests. | ## Recommended Polling Poll this endpoint every **20 minutes** from your backend or app shell. That is frequent enough to react to platform incidents without turning a health endpoint into unnecessary traffic. Avoid polling it before every single post, upload, or OAuth click. Cache the latest result and use it to guide your UI. ## Example Usage ```typescript theme={null} type PlatformHealthStatus = "operational" | "degraded" | "outage" | "maintenance"; const shouldDisablePlatformFeature = (status: PlatformHealthStatus) => status === "outage" || status === "maintenance"; const shouldShowWarning = (status: PlatformHealthStatus) => status === "degraded"; ``` For example, if `GOOGLE_BUSINESS.status` is `outage`, disable Google Business posting and review import buttons. If `INSTAGRAM.status` is `degraded`, you may keep publishing enabled but show a short message like "Instagram is slower than usual right now." > [!TIP] > > Use your own user-facing copy. The `note` field is useful context, but it may contain operational wording that is not polished for your customers. # Import Post History Source: https://info.bundle.social/api-reference/import-posts Pull past posts and analytics from Instagram, TikTok, LinkedIn and more. An async job backfills your dashboard with history from before you connected. Use the History Import API to fetch existing content from connected accounts and populate your dashboard with past posts. * You can filter imports by **surface** and **media type**. * You can request richer media metadata in `extraData` (when platform returns direct media URLs). * `extraData` is now normalized as `extraData.media[]`. * For platforms/endpoints that do not expose direct media URLs, `extraData` has no `media[]` (often it's `null`). Need comment import and replies? See [Comments API](/api-reference/comments). ## How it works This is an **asynchronous** job. You don't get the posts instantly. 1. **Start:** You trigger a job ("Go fetch 50 posts from Instagram"). 2. **Wait:** We queue it, talk to the platform, and crunch the data. 3. **Poll:** You check if we're done. 4. **Fetch:** You download the results. *** ## Step 1: Start the Job **Endpoint:** `POST /api/v1/post-history-import` ```json theme={null} { "teamId": "team_123", "socialAccountType": "INSTAGRAM", "count": 50, "withAnalytics": true, "importCarousels": true, "surface": "ALL", "mediaType": "VIDEO" } ``` ### Import filters and media options * `surface` lets you choose where the content comes from (`ALL`, `PROFILE_GRID`, `NON_GRID`, `STORY`). * `mediaType` filters by content type (`VIDEO` or `IMAGE`). * `importCarousels` controls whether carousel child media is expanded into `extraData.media[]` when supported. > [!NOTE] > > Platform APIs are inconsistent. Some filters/surfaces may return no data on specific platforms if that API does not expose that view. > [!NOTE] > > Facebook: videos in the Page's video library that aren't published (drafts, scheduled, ad-only uploads) are skipped. ### What `count` means (and `onlyLatest`) By default, `count` is the number of posts **you don't have yet** that we import. Posts you already imported are skipped and don't count toward your limit, but the import keeps going further back into older posts until it has found `count` new ones. It stops early only when it has gone through at least `count` posts you already have in a row (and at least 3 pages of them), or when the platform has no older posts. For a recurring sync ("did this creator post anything new?"), set `onlyLatest: true`: ```json theme={null} { "teamId": "team_123", "socialAccountType": "INSTAGRAM", "count": 10, "onlyLatest": true } ``` We check only the latest `count` posts and import the ones you don't have yet. If nothing is new, nothing is imported and nothing counts toward your limit. On X, every post we read is still billed, new or not. **Limits:** * **Free:** 5 posts / month (Demo mode) * **Pro:** 100 posts / month * **Business:** 500 posts / month > [!NOTE] > > **Why limits?** Historical imports are expensive on API tokens. We have to be stingy here to keep the service cheap for everyone. ### Imported post analytics By default, imported posts get an **initial analytics snapshot** at import time when `withAnalytics: true`. #### Ongoing Analytics Refresh Imported posts can also be added to the regular analytics refresh cycle - meaning they get updated on the same schedule as posts created through bundle.social. This is controlled by an organization-level setting. When enabled: * Imported posts are included in the regular analytics scanner. * You can fetch analytics for imported posts via the standard analytics endpoints using `importedPostId` instead of `postId`. * You can force-refresh analytics for imported posts the same way you would for regular posts. * **Facebook and Instagram:** the import doesn't write an initial snapshot for posts (it would show `0` impressions and reach). Their first analytics come from the regular refresh, which picks new imports up right away. Stories still get their snapshot at import time, since they expire and aren't refreshed. > [!NOTE] > > **`importedPostId` vs `postId`:** When querying analytics for imported posts, use `importedPostId` (the imported post's ID). Don't mix it with `postId` + `platformType` - they're mutually exclusive. > [!WARNING] > > Ongoing analytics for imported posts means we're making additional API calls to platforms for posts that weren't created through bundle.social. > > Want to enable this? [Contact us](https://bundle.social/contact) and we'll set it up for your organization. It's included in paid plans at no extra cost. The only exception is X: importing from X and every X analytics refresh are billed from your prepaid [X credits](/api-reference/platforms/twitter), and imported X posts are never refreshed in the background. *** ## Step 2: Check Status **Endpoint:** `GET /api/v1/post-history-import?teamId=...` You'll see a list of jobs with statuses: * `PENDING`: In queue. * `FETCHING_POSTS`: Talking to Instagram... * `COMPLETED`: Done! * `FAILED`: Import failed after retries. * `RATE_LIMITED`: Platform said "slow down". We paused it for you. *** ## Step 3: Get the Loot **Endpoint:** `GET /api/v1/post-history-import/posts` Once status is `COMPLETED`, call this to get the actual data. ```json theme={null} { "posts": [ { "title": "My Cat Video", "type": "VIDEO", "extraData": null, "analytics": { "likes": 1337, "impressions": 42000 } }, { "title": "Carousel example", "type": "IMAGE", "extraData": { "media": [ { "id": "1789...", "mediaUrl": "https://cdn.platform.com/media/..." } ] } } ] } ``` ### `extraData` structure When available, imported posts include: ```json theme={null} { "extraData": { "media": [ { "id": "platform-media-id-or-null", "mediaUrl": "direct-platform-media-url" } ] } } ``` If we can't get direct media URLs from the platform endpoint, `extraData` is `null`. > [!NOTE] > > YouTube history import doesn't return media URLs. Its `extraData` holds `visibility` (`PUBLIC`, `UNLISTED`, `PRIVATE`) and, for Shorts and other known content types, `contentType` and `isShort`. See [YouTube](/api-reference/platforms/youtube#quirks). *** ## Handling Rate Limits If a job hits `RATE_LIMITED`, don't panic. It means we hit the platform's cap (e.g. LinkedIn API limits). * We automatically pause the job. * We set a `rateLimitResetAt` timestamp. * You can retry it after that time. *** ## Need More? We're flexible with import requirements. If you have a specific use case - bulk historical imports, custom date ranges, or higher volume needs-[contact us](https://bundle.social/contact). We'll work with you to find a solution. # Introduction Source: https://info.bundle.social/api-reference/introduction Get started with the bundle.social API. API key auth via x-api-key, the base URL, how organizations and teams fit together, and where rate limits bite. ## Authentication We use API Key authentication. Simple, secure, boring. > [!NOTE] > > **Don't have an API Key?**\ > [Sign up here](https://bundle.social) and grab one from the **API Keys** section in your dashboard. ### The Header To make a request, add the `x-api-key` header with your key. ```json theme={null} { "x-api-key": "pk_live_..." } ``` ### Authorization Scheme All endpoints are protected. If you don't send the key, you get a `401 Unauthorized`. If you send a bad key, you get a `403 Forbidden`. ```json theme={null} "security": [ { "ApiKeyAuth": [] } ] ``` ## Base URL ```bash theme={null} https://api.bundle.social ``` Everything is prefixed with `/api/v1`, but check the specific endpoint reference to be sure. *** ## Organizations vs Teams This is important. Almost every API call involves a `teamId`, so you need to understand the hierarchy: ``` Organization (your account) ├── Team A (e.g. "Marketing") │ ├── Social Accounts (Instagram, TikTok, ...) │ ├── Posts │ └── Uploads ├── Team B (e.g. "Client: Acme Corp") │ ├── Social Accounts │ ├── Posts │ └── Uploads ├── API Keys (shared across all teams) ├── Webhooks (shared across all teams) └── Subscription & Billing ``` ### What lives where | Level | What belongs here | | :- | :- | | **Organization** | API keys, webhooks, subscription/billing, compression settings | | **Team** | Social accounts, posts, uploads, bots, invitations, bio/link-in-bio | ### Why this matters for you * **`teamId` is required** on most endpoints (creating posts, uploading media, connecting accounts). Think of a team as a "workspace" or "project" - it groups related social accounts together. * **API keys are org-level.** One key gives you access to all teams in the organization. * **Webhooks are org-level.** You get events for all teams from a single webhook endpoint. * **Rate limits are per team.** Each team has its own daily posting quota. Five teams means five independent limits. See [Rate Limits](/api-reference/rate-limits). * **Monthly post caps are org-level.** The total monthly posts across all teams are capped by your subscription tier. > [!TIP] > > If you're building a SaaS where each of your customers needs their own social accounts, create a **team per customer**. They won't step on each other's toes. ### Finding your team IDs List your teams with the paginated `GET /api/v1/team`: ```http theme={null} GET /api/v1/team?offset=0&limit=50 ``` It returns `{ items, total }`, so it works the same whether you have 3 teams or 30,000. Add `search` to filter by name. Every list endpoint pages the same way: `limit` from 1 to 1000 (`0` or empty means the endpoint's default) and `offset` to skip ahead. A `limit` above 1000 returns `400`, so page with `offset` to fetch more. > [!WARNING] > > `GET /api/v1/organization` still returns a `teams` array, but it's **deprecated and will be removed on November 15, 2026**. It isn't paginated, so it gets slow for organizations with many teams. Use `GET /api/v1/team` instead. The rest of the organization response (ID, plan, settings) stays. *** ## Rate Limits We have sensible rate limits to protect the system. If you hit them, you'll get a `429 Too Many Requests`. Check the [Rate Limits](/api-reference/rate-limits) page for the full breakdown - including burst protection, per-minute caps, and daily posting limits per platform. *** ## Other ways to use the API You don't have to call the REST endpoints directly: > [card] [SDK](/api-reference/sdk) > > Typed TypeScript SDK, generated from OpenAPI. > [card] [CLI](/api-reference/cli) > > `bundlesocial-cli` - JSON in, JSON out. For shells, CI, cron and AI agents. > [card] [MCP server](/api-reference/mcp) > > `bundlesocial-mcp` - for Claude Desktop / Claude Code / Cursor and other MCP clients. The per-platform fields you put in a post's `data` are documented in [Platform parameters](/api-reference/platform-parameters). # Platform Limits Source: https://info.bundle.social/api-reference/limits Check these before you post. Every platform has rules. We enforce them so you don't get banned. Every platform has rules. Some are sensible, some are arbitrary. We enforce them so you don't get banned. ## How Validation Works We validate everything before sending to the platform. If your content breaks a rule, you get a `400` error with a clear message telling you exactly what's wrong. Here's the vocabulary: * **Aspect Ratio:** `width / height`. A 1920x1080 video has a ratio of \~1.78 (16:9). * **Bitrate:** `(fileSize x 8) / videoLength`. Measured in bps. We show it in Mbps. * **File Count:** How many images/videos you can attach to a single post. > [!NOTE] > > **Upload ceiling.** Regardless of platform, the largest file we accept is **5 GB** for video (higher on request, per organization - and only via [Multipart Upload](/api-reference/upload-content)), **25 MB** for images, and **100 MB** for documents (PDF). The per-platform limits below are often lower - we enforce the smaller of the two. *** ## Instagram ### Posts (Carousel) | Constraint | Value | | :- | :- | | Files | 1-10 (images and/or videos, mixed allowed) | | Image max size | 8 MB | | Image max width | 1920px | | Image aspect ratio | 4:5 to 1.91:1 | | Video max width | 1920px | | Video max bitrate | 45 Mbps | | Video duration | 3s - 15 min | | Video aspect ratio | 0.01:1 to 10:1 | ### Reels | Constraint | Value | | :- | :- | | Files | 1 video (required) | | Max width | 1920px | | Max bitrate | 45 Mbps | | Duration | 3s - 15 min | | Aspect ratio | 0.01:1 to 10:1 | > [!WARNING] > > **Aspect ratios are law.** Instagram is SUPER strict. If your pixel math is off by even a tiny bit, they might reject it. 9:16 vertical is the safe bet for Reels. ### Stories | Constraint | Value | | :- | :- | | Files | 1 (image or video) | | Image max size | 8 MB | | Image aspect ratio | 0.01:1 to 10:6 | | Video max size | 100 MB | | Video max width | 1920px | | Video max bitrate | 25 Mbps | | Video duration | 3s - 60s | | Video aspect ratio | 0.01:1 to 10:6 | *** ## TikTok ### Videos | Constraint | Value | | :- | :- | | Files | 1 video (required) | | Max size | 1 GB | | Resolution | 360x360 to 4096x4096 | | Aspect ratio | 0.01:1 to 16:9 | | Duration | Max 10 min (600s) | ### Images (Photo Mode) | Constraint | Value | | :- | :- | | Files | 1-35 images | | Format | **JPG/JPEG/WebP only** - PNG and other formats will be rejected for TikTok Photo Mode | | Max size | 20 MB each | | Max resolution | 1080x1920 (portrait) or 1920x1080 (landscape). Larger images are rejected unless `autoScale: true` | > [!WARNING] > > **PNG is not valid for TikTok Photo Mode.** Convert PNG assets before creating the TikTok image post. *** ## YouTube ### Shorts | Constraint | Value | | :- | :- | | Files | 1 video (required) | | Max size | 5 GB | | Duration | Max 3 min (180s) | | Aspect ratio | 1:3 to 1:1 (vertical or square) | ### Long Form Videos | Constraint | Value | | :- | :- | | Files | 1 video (required) | | Max size | 5 GB | | Duration | Max 4 hours (14,400s) | | Aspect ratio | 1:3 to 3:1 | *** ## LinkedIn | Constraint | Value | | :- | :- | | Files | 0-10 (images, videos, OR documents - not mixed) | | **Videos** | | | Max videos | 1 | | Video max size | 2 GB | | Video resolution | 256x144 to 4096x4096 | | Video aspect ratio | 1:2.4 to 2.4:1 | | Video duration | 3s - 30 min | | **Images** | | | Max images | 10 | | Image max size | 5 MB each | | Image min resolution | 200x200 | | **Documents** | | | Max documents | 1 | | Document max size | 100 MB | | Document format | PDF only | *** ## Twitter / X | Constraint | Value | | :- | :- | | Files | 0-4 (images and/or videos) | | **Videos** | | | Video max size | 512 MB | | Video aspect ratio | 1:3 to 3:1 | | Video min length | 0.5s | | Video duration (Free/Basic) | Max 140s (2:20) | | Video duration (Premium/Premium+) | Max 600s (10 min) | | **Images** | | | Image max size | 5 MB each | | Max images | 4 | | **Text** | | | Text limit (Free/Basic) | 280 characters | | Text limit (Premium/Premium+) | 25,000 characters | *** ## Facebook ### Page Posts | Constraint | Value | | :- | :- | | Files | 0-10 (images or videos, not mixed) | | Max videos | 1 | | Video max bitrate | 45 Mbps | | Video aspect ratio | 0.01:1 to 1.91:1 | | Video duration | Max 20 min (1,200s) | | Max images | 4 | | Image max size | 4 MB each | | Image aspect ratio | 0.01:1 to 1.91:1 | ### Reels | Constraint | Value | | :- | :- | | Files | 1 video (required) | | Min resolution | 540x960 | | Aspect ratio | 0.01:1 to 10:6 | | Max bitrate | 45 Mbps | | Duration | 3s - 20 min (1,200s) | ### Stories | Constraint | Value | | :- | :- | | Files | 1 (image or video) | | Video min resolution | 540x960 | | Video max bitrate | 25 Mbps | | Video duration | 3s - 60s | | Video aspect ratio | 0.01:1 to 10:6 | | Image max size | 4 MB | | Image aspect ratio | 0.01:1 to 10:6 | *** ## Pinterest | Constraint | Value | | :- | :- | | Files | 1 image or video, or 2-5 images for a carousel Pin (required) | | Carousel | Images only, all with the same aspect ratio | | **Videos** | | | Video max size | 2 GB | | Video aspect ratio | 1:2 to 1.91:1 | | Video duration | 4s - 15 min (900s) | | **Images** | | | Image max size | 5 MB | > [!NOTE] > > **Board name required.** You can't pin to thin air. Every Pinterest post needs `boardName` from `socialAccount.channels`. *** ## Reddit ### Single Post | Constraint | Value | | :- | :- | | Files | 0-1 (image or video) | | Video max size | 1 GB | | Video aspect ratio | 9:16 to 16:9 | | Video duration | 4s - 15 min (900s) | | Image max size | 20 MB | ### Gallery Post | Constraint | Value | | :- | :- | | Files | 0-10 images (only if subreddit allows galleries) | | Image max size | 20 MB each | > [!NOTE] > > **Subreddit rules apply.** Not all subreddits allow media, and not all allow galleries. We validate against the subreddit's settings. If the subreddit requires a flair, you need to provide one. *** ## Threads | Constraint | Value | | :- | :- | | Files | 0-10 (images and/or videos, mixed allowed) | | Video max size | 1 GB | | Video max bitrate | 100 Mbps | | Video aspect ratio | 0.01:1 to 1.91:1 | | Image max size | 8 MB | | Image width | 320-1440px | | Image aspect ratio | 0.01:1 to 1.91:1 | *** ## Discord | Constraint | Value | | :- | :- | | Files | 0-10 (images and/or videos, mixed allowed) | | Video max size | 25 MB | | Video aspect ratio | 0.01:1 to 1.91:1 | | Image max size | 25 MB | | Image aspect ratio | 0.01:1 to 1.91:1 | | Text | Max 2,000 characters | > [!NOTE] > > **Channel ID required.** Discord posts go to a specific channel. Check `socialAccount.channels` for available options. *** ## Slack | Constraint | Value | | :- | :- | | Files | 0-4 (images and/or videos, mixed allowed) | | Video max size | 1 GB | | Video aspect ratio | 0.01:1 to 1.91:1 | | Image max size | 1 GB | | Image aspect ratio | 0.01:1 to 1.91:1 | | Text | Max 30,000 characters | *** ## Mastodon | Constraint | Value | | :- | :- | | Files | 0-4 (images and/or videos, mixed allowed) | | Max videos | 1 | | Video max size | 99 MB | | Video aspect ratio | 1:3 to 1:1 | | Max images | 4 | | Image max size | 16 MB each | | Text | Instance-dependent (usually 500 chars) | *** ## Bluesky | Constraint | Value | | :- | :- | | Files | 0-4 (images and/or videos) | | Text | 300 characters | > [!NOTE] > > Bluesky has minimal media restrictions on their end. We enforce basic file count limits, but the platform is relatively permissive compared to others. *** ## Google Business | Constraint | Value | | :- | :- | | Files | 0-1 image only (no video) | | Image max size | 5 MB | | Image min resolution | 250x250 | | Text | Max 1,500 characters | *** ## Snapchat ### Stories | Constraint | Value | | :- | :- | | Files | Exactly 1 image or MP4 video | | Max video file size | 400 MB | | Max image file size | 100 MB | | Video minimum resolution | 540x960 | | Video duration | 5-180 seconds | ### Saved Stories | Constraint | Value | | :- | :- | | Files | 1-20 images and/or MP4 videos | | Max file size | 400 MB per video, 100 MB per image | | Video minimum resolution | 540x960 | | Video duration | 5-180 seconds per video | | Combined length | Max 300 seconds (each image counts as 10 seconds) | ### Spotlights | Constraint | Value | | :- | :- | | Files | Exactly 1 MP4 video | | Max file size | 400 MB | | Minimum resolution | 540x960 | | Video duration | 5-180 seconds | *** ## Quick Reference Table | Platform | Max Files | Video Max Size | Video Max Duration | Image Max Size | | :- | :- | :- | :- | :- | | Instagram Post | 10 | N/A (bitrate limit) | 15 min | 8 MB | | Instagram Reel | 1 | N/A (bitrate limit) | 15 min | - | | Instagram Story | 1 | 100 MB | 60s | 8 MB | | TikTok Video | 1 | 1 GB | 10 min | - | | TikTok Image | 35 | - | - | 20 MB | | YouTube Short | 1 | 5 GB | 3 min | - | | YouTube Video | 1 | 5 GB | 4 hours | - | | LinkedIn | 10 | 2 GB | 30 min | 5 MB | | Twitter/X | 4 | 512 MB | 140s / 10 min | 5 MB | | Facebook Post | 10 | N/A (bitrate limit) | 20 min | 4 MB | | Facebook Reel | 1 | N/A (bitrate limit) | 20 min | - | | Facebook Story | 1 | N/A (bitrate limit) | 60s | 4 MB | | Pinterest | 1 | 2 GB | 15 min | 5 MB | | Reddit | 1 / 10 gallery | 1 GB | 15 min | 20 MB | | Threads | 10 | 1 GB | - | 8 MB | | Discord | 10 | 25 MB | - | 25 MB | | Slack | 4 | 1 GB | - | 1 GB | | Mastodon | 4 | 99 MB | - | 16 MB | | Bluesky | 4 | - | - | - | | Google Business | 1 | - | - | 5 MB | | Snapchat Story | 1 | 400 MB | 180s | 100 MB | | Snapchat Saved Story | 20 | 400 MB | 180s each, 300s combined | 100 MB | | Snapchat Spotlight | 1 | 400 MB | 180s | - | ## Text & Character Limits | Platform | Main text field limit | Other text field limits | | :- | :- | :- | | Instagram | `text`: 2,000 | `collaborators` username max 30, `tagged` username max 30, optional `altText` on image posts | | TikTok | `text`: 2,200 (video), 4,000 (photo) | `title` (photo only): 90, `locationName`: 255 | | YouTube | `text` (title): 100 | `description`: 5,000 | | LinkedIn | `text`: 3,000 | `mediaTitle`: 200 | | Twitter / X | `text`: 280 (Free/Basic), 25,000 (Premium/Premium+) | - | | Facebook | `text`: 50,000 | `mediaTitle`: 255, `link`: 2,048, optional `altText` on image posts | | Pinterest | `text`: 100 | `description`: 800, `altText`: 500, `note`: 500 | | Reddit | `text` (title): 300 | `description`: 30,000 | | Threads | `text`: 500 | optional `altText` on image media | | Discord | `text`: 2,000 | `username`: 80, `avatarUrl`: 2,048 | | Slack | `text`: 30,000 | `username`: 80, `avatarUrl`: 2,048 | | Mastodon | `text`: 30,000 | `spoiler`: 50 (instance-level limits can still be lower) | | Bluesky | `text`: 300 | `externalTitle`: 300, `externalDescription`: 1,000, `videoAlt`: 10,000 | | Google Business | `text`: 1,500 | `eventTitle`: 58, `offerCouponCode`: 58, `offerTermsConditions`: 1,500 | | Snapchat | `description` or `text`: 160 | `locale`: `en_US` format for Spotlights | For daily posting limits per platform and monthly post caps, see [Rate Limits](/api-reference/rate-limits). # MCP Server Source: https://info.bundle.social/api-reference/mcp Drive bundle.social from Claude, Cursor and other Model Context Protocol clients. `bundlesocial-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the bundle.social operations as MCP tools - so Claude Desktop, Claude Code, Cursor and any other MCP client can post, schedule, import, analyze content and manage connected accounts across 14+ platforms. It ships as a **local stdio server** (`npx bundlesocial-mcp`). A hosted remote server at `mcp.bundle.social` is on the roadmap. > [card] [npm: bundlesocial-mcp](https://www.npmjs.com/package/bundlesocial-mcp) > > `npx bundlesocial-mcp` > [card] [MCP Inspector](https://github.com/modelcontextprotocol/inspector) > > `npx @modelcontextprotocol/inspector npx bundlesocial-mcp` ## Tools The server covers the whole bundle.social API (the platform-specific edit/delete-after-publish helpers are reached via `trigger_integration_tool`). **Diagnostics & discovery** | Tool | Description | | - | - | | `check_setup` | Diagnostic JSON: API key, connectivity, organization API access, team selection, integrations, quotas. | | `list_integrations` | List connected social accounts (ids, platform types, channels). | | `list_integration_tools` / `trigger_integration_tool` | List & call read-only platform helpers - subreddit flairs/requirements, YouTube categories/playlists/regions, LinkedIn mentions, Instagram locations/audio/business discovery, Google Business categories, TikTok trending music. | **Posts** | Tool | Description | | - | - | | `create_post` / `schedule_post` | Publish now (or as a draft) / schedule for a future date. | | `update_post` / `retry_post` | Update a post (only changed fields) / re-attempt one that ended in `ERROR`. | | `get_post_by_reference_key` | Fetch a post by the `referenceKey` set on it instead of its bundle.social id. | | `list_reconnect_candidates` / `reconnect_posts` | List posts that lost their social account after a disconnect, and reattach them to a newly connected account. | | `list_posts` / `get_post` / `delete_post` | List with filters / fetch / delete posts. | | `create_post_import` … | Import post history from a connected account: `create_post_import`, `list_post_imports`, `get_post_import`, `list_imported_posts`, `delete_imported_posts`, `retry_post_import`. | | `create_post_csv_import` … | Bulk-schedule from a CSV (URL or local file): `create_post_csv_import`, `list_post_csv_imports`, `get_post_csv_import`, `get_post_csv_import_status`, `get_post_csv_import_rows`. | **Comments** | Tool | Description | | - | - | | `create_comment` / `list_comments` / `get_comment` / `update_comment` / `delete_comment` | Comment on a post (pass `content` multiple times for a chain) / list / fetch / update / delete comments. | | `create_comment_import` … | Pull existing comments for a post: `create_comment_import`, `list_comment_imports`, `get_comment_import`, `list_imported_comments`. | | `act_on_imported_comment` | Moderate an imported comment - delete, hide/unhide, like/unlike, approve/reject. | **Media** | Tool | Description | | - | - | | `upload_media` | Upload an image/video/document from a URL (or local path in stdio mode); auto-chunks large local files. | | `init_large_upload` / `finalize_large_upload` | Low-level chunked-upload primitives (for manual control). | | `list_media` / `get_media` / `delete_media` / `delete_media_many` | List / fetch / delete uploads. | **Integrations (social accounts)** | Tool | Description | | - | - | | `connect_integration` / `disconnect_integration` | Start an OAuth connect flow (returns a URL) / disconnect an account. | | `create_integration_portal_link` | Hosted portal link for end users to connect accounts. | | `set_integration_channel` / `unset_integration_channel` / `refresh_integration_channels` | Pick / clear / refresh the channel (page, board, server channel) for an account. | | `check_integration_connection` / `refresh_integration_profile` / `get_integration_by_type` / `copy_integration` / `list_integrations_to_delete` | Connection check, profile refresh, lookup by platform, copy between teams, list accounts pending deletion. | **Analytics** | Tool | Description | | - | - | | `get_post_analytics` | Per-post engagement metrics (`raw: true` for the unprocessed payload). | | `get_account_analytics` | Latest analytics for a connected account by `platform` (`raw: true` for the unprocessed payload). | | `get_bulk_post_analytics` | Engagement metrics for several posts at once. | | `refresh_analytics` | Force a fresh pull - by `postId` for a post, otherwise `platform` for an account. | | `get_analytics_summary` | Org-level usage quotas + latest per-integration analytics snapshot. | **Teams & organization** | Tool | Description | | - | - | | `list_teams` / `get_team` / `create_team` / `update_team` / `delete_team` | Manage teams. | | `get_organization` / `get_usage` | Your organization, and posts/comments/uploads/imports usage & quotas. | | `get_daily_limits_usage` | A connected account's daily post/comment allowance for a given day. | Errors come back as `{ "error": { "code", "message", "details"? } }` with `isError: true`. The per-platform fields for posts are documented in [Platform parameters](/api-reference/platform-parameters). ## Configuration Reads `BUNDLESOCIAL_API_KEY` (required), `BUNDLESOCIAL_TEAM_ID` (optional - needed only if your org has more than one team) and `BUNDLESOCIAL_API_URL` (optional). Get an API key in the [dashboard](https://bundle.social/dashboard/organization/api-keys). > [tab] Claude Desktop > > `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`): > > ```json theme={null} > { > "mcpServers": { > "bundlesocial": { > "command": "npx", > "args": ["-y", "bundlesocial-mcp"], > "env": { "BUNDLESOCIAL_API_KEY": "sk_live_..." } > } > } > } > ``` > [tab] Claude Code > > ```bash theme={null} > claude mcp add bundlesocial --env BUNDLESOCIAL_API_KEY=sk_live_... -- npx -y bundlesocial-mcp > ``` > > Or in `.mcp.json`: > > ```json theme={null} > { > "mcpServers": { > "bundlesocial": { > "command": "npx", > "args": ["-y", "bundlesocial-mcp"], > "env": { "BUNDLESOCIAL_API_KEY": "sk_live_..." } > } > } > } > ``` > [tab] Cursor > > `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): > > ```json theme={null} > { > "mcpServers": { > "bundlesocial": { > "command": "npx", > "args": ["-y", "bundlesocial-mcp"], > "env": { "BUNDLESOCIAL_API_KEY": "sk_live_..." } > } > } > } > ``` ## Example prompts * "List my connected social accounts via bundle.social." * "Post 'We just shipped dark mode 🌙' to X and Bluesky." * "Schedule a LinkedIn post for next Monday 9am UTC announcing the launch." * "Post to r/test on Reddit - first check the subreddit's requirements and flairs, then post with the right flair." * "Reply to post `post_abc123` with a 3-comment thread on LinkedIn." * "How did post `post_abc123` perform?" Also see: [CLI](/api-reference/cli) · [SDK](/api-reference/sdk) · [n8n](/api-reference/n8n). # n8n Source: https://info.bundle.social/api-reference/n8n Schedule posts, handle comments, DMs and analytics from n8n workflows. `n8n-nodes-bundlesocial` is an [n8n](https://n8n.io) community node for the bundle.social API. One **bundle.social** node covers every public operation - posts, uploads, comments, DMs, automations, analytics, teams and the platform-specific helpers - across 15 platforms. It is generated from the [OpenAPI spec](/api-reference/openapi) and regenerated when the API changes, so new operations reach the node shortly after they ship. > [card] [npm: n8n-nodes-bundlesocial](https://www.npmjs.com/package/n8n-nodes-bundlesocial) > > Install from **Settings > Community Nodes** > [card] [Source](https://github.com/bundleglobal/bundlesocial-n8n) > > `bundleglobal/bundlesocial-n8n` ## Install In n8n open **Settings > Community Nodes > Install**, enter `n8n-nodes-bundlesocial` and confirm. See the [n8n guide](https://docs.n8n.io/integrations/community-nodes/installation/) for other install methods. ## Credentials 1. Create an API key in the [dashboard](https://bundle.social/dashboard/organization/api-keys). 2. In n8n, create a **bundle.social API** credential and paste the key into **API Key**. Leave **Base URL** at `https://api.bundle.social`. ## Usage Pick a **Resource** (for example *Post*), then an **Operation** (for example *Create*). * **Team** and **Social Account** fields are dropdowns loaded from your organization; an expression with an ID works too. * **Post > Create** shows one settings section per platform selected in **Social Account Types** (*TikTok Settings*, *Instagram Settings*, ...). The fields match [Platform parameters](/api-reference/platform-parameters). * Media goes in two steps: upload it with **Upload > Upload File** (binary input) or **Upload > Create From URL**, then pass the returned `id` in the post's **Upload IDs**. Files above 90 MB go through **Upload > Upload Large File** (up to 5 GB). * Every operation with a request body has **Specify Body > Using JSON** for sending the raw body, for example an automation flow built by an earlier node. * List operations support **Return All** and page through the API for you. * Dates picked in the UI are read in the workflow timezone; ISO 8601 strings with an offset are sent as-is. * Validation errors list each invalid field, for example `data.TIKTOK.text: Required`. ### Example: schedule a post with an image 1. **HTTP Request** (or any node) that outputs the image as binary data. 2. **bundle.social > Upload > Upload File**, Input Binary Field `data`. 3. **bundle.social > Post > Create**: * Team: your team * Social Account Types: `Instagram`, `LinkedIn` * Post Date: `{{ $now.plus(1, 'hour').toISO() }}` * Status: `Scheduled` * Instagram Settings > Text: your caption, Upload IDs: `{{ $('Upload File').item.json.id }}` * LinkedIn Settings > Text: your caption, Upload IDs: `{{ $('Upload File').item.json.id }}` ## AI Agent tool The node can be attached to an n8n **AI Agent** as a tool. On self-hosted n8n set `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true` to allow community nodes as tools. Also see: [SDK](/api-reference/sdk) · [CLI](/api-reference/cli) · [MCP Server](/api-reference/mcp) · [Webhooks](/api-reference/webhooks). # OpenAPI Source: https://info.bundle.social/api-reference/openapi The full OpenAPI 3.0 spec for the bundle.social API. Try endpoints live, browse them in Swagger UI, or generate a typed client in your own language. Our API is fully described by an OpenAPI 3.0 spec. You can use it to explore endpoints interactively, generate client libraries, or import into your favorite API tool. ## Try It Live > [card] [Docs client](/api-reference/client) > > Interactive API explorer embedded right here in the docs. Pass your API key and start making requests. ## Swagger UI > [card] [Swagger](https://api.bundle.social/swagger) > > The classic Swagger UI. Browse all endpoints, see request/response schemas, and try things out. ## Raw Specs > [card] [JSON spec](https://api.bundle.social/swagger-json) > > OpenAPI 3.0 spec in JSON format. > [card] [YAML spec](https://api.bundle.social/swagger-yaml) > > OpenAPI 3.0 spec in YAML format. *** ## Code Generation You can use the OpenAPI spec to auto-generate client libraries in pretty much any language. Some popular tools: | Tool | Command | | :- | :- | | [openapi-generator](https://openapi-generator.tech/) | `openapi-generator generate -i https://api.bundle.social/swagger-json -g typescript-fetch -o ./client` | | [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) | `npx openapi-typescript https://api.bundle.social/swagger-json -o ./types.ts` | | [Postman](https://www.postman.com/) | Import the JSON URL directly into a collection | | [Insomnia](https://insomnia.rest/) | File > Import > From URL | > [!TIP] > > If you're using TypeScript, we recommend our official [SDK](/api-reference/sdk) instead of generating a client - it has better types, built-in webhook verification, and we actually maintain it. # Platform parameters Source: https://info.bundle.social/api-reference/platform-parameters Every per-platform field you can put under data.INSTAGRAM, data.TIKTOK and the rest when creating a post. When you create or update a post, `data` is keyed by platform - `data.TWITTER`, `data.TIKTOK`, etc. Each platform accepts its own set of fields. This page is the field reference for all of them. (For connecting accounts and platform quirks, see the per-platform pages under **Platforms** in the sidebar.) * `uploadIds` are ids returned by [upload-content](/api-reference/upload-content). * `thumbnail` (where present) is a public URL of an image already uploaded to bundle.social - use it as a video cover when an offset isn't enough. * **Bold** = required for that platform. > [!NOTE] > > The [CLI](/api-reference/cli) builds `data` for you: `--content` → `text`, `-m` → `uploadIds`, `--platform-settings '{"

":{...}}'` → merged into `data.

`. The same fields apply to the [SDK](/api-reference/sdk) and the [MCP server](/api-reference/mcp). Snippets below that say `integrations:trigger …` are the CLI form of the same `trigger_integration_tool` MCP tool / `misc.*` SDK helper. ## X / Twitter - `data.TWITTER` | Field | Type | Notes | | - | - | - | | `text` | string | Post text. \~280 chars (longer if the connected account is X Premium). | | `uploadIds` | string\[] | Up to 4 images **or** 1 video/GIF. | | `replySettings` | `EVERYONE` \| `FOLLOWING` \| `MENTIONED_USERS` \| `SUBSCRIBERS` \| `VERIFIED` | Who can reply. | | `isAiGenerated` | boolean | Adds X's "made with AI" label to a post with AI-generated media. | Threads: post the first tweet, then add the rest as replies with `comments:create --post-id -c "..." -c "..."` (X threads go through the [comments](/api-reference/comments) API, not `data`). No analytics surface for X. ```json theme={null} { "TWITTER": { "text": "Shipping day 🚀", "replySettings": "EVERYONE" } } ``` ## Bluesky - `data.BLUESKY` | Field | Type | Notes | | - | - | - | | `text` | string | \~300 chars. | | `uploadIds` | string\[] | Up to 4 images, or 1 video (set `videoAlt`). | | `tags` | string\[] | Extra hashtags (without `#`), up to 8. | | `labels` | (`!no-unauthenticated` \| `porn` \| `sexual` \| `nudity` \| `graphic-media`)\[] | Self-labels / content warnings. | | `quoteUri` | string | AT-URI of a post to quote (`at://…/app.bsky.feed.post/`). | | `externalUrl` / `externalTitle` / `externalDescription` | string | External link card. | | `thumbnail` | string (URL) | Image for the external link card. | | `videoAlt` | string | Alt text for a video embed. | ```json theme={null} { "BLUESKY": { "text": "New post", "tags": ["launch", "indie"], "externalUrl": "https://bundle.social" } } ``` ## Mastodon - `data.MASTODON` | Field | Type | Notes | | - | - | - | | `text` | string | Length depends on the connected instance (commonly \~500). | | `uploadIds` | string\[] | Up to 4 images **or** 1 video. | | `privacy` | `PUBLIC` \| `UNLISTED` \| `PRIVATE` \| `DIRECT` | Visibility. | | `spoiler` | string | Content-warning text (collapses the post behind it). | | `thumbnail` | string (URL) | Cover image for a video. | ```json theme={null} { "MASTODON": { "text": "Hello fediverse", "privacy": "PUBLIC", "spoiler": "long read" } } ``` ## Threads - `data.THREADS` | Field | Type | Notes | | - | - | - | | `text` | string | \~500 chars. | | `uploadIds` | string\[] | Up to \~10 images, or 1 video. | | `mediaItems` | `{ uploadId, altText? }[]` | Per-image alt text (alternative to `uploadIds`). | | `topicTag` | string | One topic tag shown in the post header. 1–50 chars, no periods (`.`) or ampersands (`&`). | | `replyControl` | `everyone` \| `accounts_you_follow` \| `mentioned_only` \| `parent_post_author_only` \| `followers_only` | Who can reply. Threads defaults to `everyone`. | | `linkAttachment` | string (URL) | Link preview card. Text-only posts. | | `poll` | `{ optionA, optionB, optionC?, optionD? }` | 2–4 options, 1–25 chars each. Text-only posts, and not together with `gif`. | | `gif` | `{ gifId, provider?: "GIPHY" }` | GIF attachment. Text-only posts, and not together with `poll`. | | `allowlistedCountryCodes` | string\[] | Restrict visibility to these ISO 3166-1 alpha-2 codes. Requires Meta account eligibility. | | `crosspostToInstagramStory` | boolean | Also share the post to the linked Instagram account as a Story. | | `crosspostToInstagramStoryDarkMode` | boolean | Cross-post the Instagram Story in dark mode. | Polls, GIFs and link attachments only work on text-only posts - Threads rejects them when `uploadIds` is set. ```json theme={null} { "THREADS": { "text": "Quick thought", "topicTag": "shipping", "replyControl": "everyone" } } ``` ## LinkedIn - `data.LINKEDIN` | Field | Type | Notes | | - | - | - | | **`text`** | string | \~3000 chars. A post needs text, media, a link or a poll. Works for a personal profile or a company page depending on which account the user connected. | | `uploadIds` | string\[] | Images, a single video, or a document/PDF. | | `link` | string (URL) | For an article-preview post. Not with media or a poll. | | `poll` | `{ question, options, duration }` | Question 1-140 chars, 2-4 options of 1-30 chars, `duration` `ONE_DAY` \| `THREE_DAYS` (default) \| `SEVEN_DAYS` \| `FOURTEEN_DAYS`. Not with media or a link. See [LinkedIn polls](/api-reference/platforms/linkedin#polls). | | `thumbnail` | string (URL) | Cover image. | | `mediaTitle` | string | Title for a video or document post (LinkedIn otherwise shows the post date under videos). | | `privacy` | `CONNECTIONS` \| `PUBLIC` \| `LOGGED_IN` \| `CONTAINER` | Visibility. | | `hideFromFeed` | boolean | Don't show in the main feed. | | `disableReshare` | boolean | Disallow resharing. | Mentions: discover URNs with `integrations:trigger linkedin:mentions --data '{"q":"...","scope":"organizations"}'` and put them in `text`. ```json theme={null} { "LINKEDIN": { "text": "We just shipped X.", "privacy": "PUBLIC", "mediaTitle": "Demo" } } ``` ## Facebook (Page) - `data.FACEBOOK` | Field | Type | Notes | | - | - | - | | `type` | `POST` \| `REEL` \| `STORY` | Default `POST`. | | `text` | string | Caption / message. | | `uploadIds` | string\[] | Images, or a single video. | | `mediaItems` | `{ uploadId, altText? }[]` | Per-image alt text. | | `link` | string (URL) | Link attachment - `type: POST` only. | | `mediaTitle` | string | Video title - `type: POST` with a video only (not REEL/STORY). | | `thumbnail` | string (URL) | Video cover image. | | `nativeScheduleTime` | string (ISO 8601, local) | Schedule directly in Meta's scheduler instead of publishing now; max 30 days ahead. | ```json theme={null} { "FACEBOOK": { "type": "POST", "text": "Look at this", "link": "https://bundle.social" } } ``` ## Instagram - `data.INSTAGRAM` | Field | Type | Notes | | - | - | - | | `type` | `POST` \| `REEL` \| `STORY` | `POST` = single image, carousel (`carouselItems`), or feed video; `REEL` = single video; `STORY` = image or short video. | | `text` | string | Caption. | | `uploadIds` | string\[] | Single image/video for `POST`/`REEL`/`STORY`. Square ≥1080×1080 or portrait 4:5; Reels 9:16, up to 90s. | | `altText` | string | Alt text for a single-image post. | | `carouselItems` | `{ uploadId, altText?, tagged?: { username, x, y }[] }[]` | Carousel slides (for `type: POST`). | | `thumbnailOffset` | number (ms) | Frame to use as the published video's cover. | | `thumbnail` | string (URL) | Cover image (alternative to offset). | | `shareToFeed` | boolean | Reels only - also show in the Feed tab. | | `collaborators` | string\[] | Usernames to invite as collaborators. | | `tagged` | `{ username, x?, y? }[]` | People tags for a single-image post. | | `locationId` | string | A location id - discover with `integrations:trigger instagram:locations --data '{"q":"..."}'`. | | `autoFitImage` / `autoCropImage` | boolean | Let bundle.social fit/crop the image to a valid aspect ratio. | | `trialParams` | `{ graduationStrategy: "MANUAL" \| "SS_PERFORMANCE" }` | Reels only - trial reels are shown to non-followers first. | | `isPaidPartnership` | boolean | Adds the native "Paid partnership" label. Implied by `brandedContentSponsors`; use alone for a label without a named sponsor. | | `brandedContentSponsors` | string\[] | Up to 2 Instagram usernames to tag as paid-partnership sponsors. Accounts connected via Facebook Login only. | | `musicSoundInfo` | `{ musicSoundId, musicSoundVolume?, videoOriginalSoundVolume? }` | Reels only - get an `audio_id` from `integrations:trigger instagram:audio --data '{"audioType":"music","searchQuery":"..."}'`. Volumes 0–100. | | `isAiGenerated` | boolean | Adds Instagram's AI content label. | Account types are connected via Facebook or directly via Instagram (`instagramConnectionMethod` on the integration). `brandedContentSponsors` and business discovery only work for accounts connected through Facebook Login. ```json theme={null} { "INSTAGRAM": { "type": "REEL", "text": "BTS", "shareToFeed": true, "thumbnailOffset": 1500 } } ``` ```json theme={null} { "INSTAGRAM": { "type": "POST", "text": "Carousel", "carouselItems": [ { "uploadId": "", "altText": "slide 1" }, { "uploadId": "", "altText": "slide 2" } ] } } ``` ## TikTok - `data.TIKTOK` | Field | Type | Notes | | - | - | - | | `type` | `VIDEO` \| `IMAGE` | `VIDEO` = 1 video; `IMAGE` = photo carousel. | | **`privacy`** | `PUBLIC_TO_EVERYONE` \| `MUTUAL_FOLLOW_FRIENDS` \| `FOLLOWER_OF_CREATOR` \| `SELF_ONLY` | Effectively required by TikTok. | | `text` | string | Caption. Max 2,200 characters for `VIDEO`, 4,000 for `IMAGE`. | | `title` | string | `IMAGE` only. Title of the photo post, max 90 characters. | | `uploadIds` | string\[] | The video, or 1-35 photos for `type: IMAGE`. Video: MP4/MOV/WEBM, ≥540p, portrait 9:16 recommended, up to \~10 min. | | `locationId` / `locationName` | string | Location tag on the post, both together. Find one with `GET /api/v1/misc/tiktok/locations?teamId=...&q=...` ([TikTok](/api-reference/platforms/tiktok#location-tags)). | | `photoCoverIndex` | number | Which photo is the cover (for `type: IMAGE`). | | `thumbnailOffset` | number (ms) | Frame to use as the video cover. | | `thumbnail` | string (URL) | `VIDEO` only. Cover image (alternative to offset). Must be the `url` of an image uploaded to bundle.social; other URLs are rejected with `400`. | | `isBrandContent` / `isOrganicBrandContent` | boolean | Disclosure: paid third-party partnership / promoting your own business. | | `disableComments` / `disableDuet` / `disableStitch` | boolean | Interaction restrictions. | | `isAiGenerated` | boolean | Mark the video as AI-generated. | | `autoAddMusic` | boolean | Let TikTok add music to photos. | | `autoScale` | boolean | Auto-scale the video. | | `uploadToDraft` | boolean | Upload as a TikTok draft instead of publishing. | | `musicSoundInfo` | `{ musicSoundId, musicSoundVolume?, musicSoundStart?, musicSoundEnd?, videoOriginalSoundVolume? }` | Commercial music - get a `song_clip_id` from `integrations:trigger tiktok:trending-music`. Volumes 0–100; start/end in ms. | ```json theme={null} { "TIKTOK": { "type": "VIDEO", "text": "Launch BTS", "privacy": "PUBLIC_TO_EVERYONE", "disableStitch": true } } ``` ## YouTube - `data.YOUTUBE` | Field | Type | Notes | | - | - | - | | `type` | `VIDEO` \| `SHORT` | `SHORT` = vertical ≤60s; `VIDEO` = full upload. | | `uploadIds` | string\[] | One video. | | `text` | string | The video **title** (the post `--title` flag also maps here). | | `description` | string | Video description. | | `thumbnail` | string (URL) | Custom thumbnail (`type: VIDEO`). | | `privacy` | `PUBLIC` \| `UNLISTED` \| `PRIVATE` | Visibility. | | `defaultLanguage` | string (BCP-47) | Language of the title and description, e.g. `en` or `pl`. | | `defaultAudioLanguage` | string (BCP-47) | Language of the video's default audio track. | | `madeForKids` | boolean | Required-ish - YouTube needs you to declare this. | | `containsSyntheticMedia` | boolean | Mark AI-generated content. | | `hasPaidProductPlacement` | boolean | Declare paid placements. | (There's no `categoryId` in the post `data` itself - fetch categories with `integrations:trigger youtube:categories --data '{"regionCode":"US"}'`; playlist management is via the SDK's `misc.youtube*` methods / `integrations:trigger youtube:playlists`.) ```json theme={null} { "YOUTUBE": { "type": "SHORT", "text": "Launch BTS", "description": "Behind the scenes…", "privacy": "PUBLIC", "madeForKids": false } } ``` ## Reddit - `data.REDDIT` | Field | Type | Notes | | - | - | - | | **`sr`** | string | Subreddit (`r/subredditName`) or `u/username`. | | **`text`** | string | The post title for link/text posts (Reddit's "title"). | | `description` | string | The body for a self post. | | `uploadIds` | string\[] | An image or video. | | `link` | string (URL) | Link post target. | | `nsfw` | boolean | Mark NSFW. | | `flairId` | string | Required if the subreddit requires a flair - get options with `integrations:trigger reddit:flairs --data '{"subreddit":"r/"}'`. | Before posting, run `integrations:trigger reddit:requirements --data '{"subreddit":"r/"}'` to learn title length limits, allowed post types, and whether a flair is required. ```json theme={null} { "REDDIT": { "sr": "r/dataisbeautiful", "text": "Our 2026 growth, visualized", "uploadIds": [""], "flairId": "" } } ``` ## Discord - `data.DISCORD` | Field | Type | Notes | | - | - | - | | **`channelId`** | string | The connected server channel (an integration "channel" id - see `integrations:list`). | | `text` | string | Message content. ≤2000 chars. | | `uploadIds` | string\[] | Attachments. | | `username` | string | Override the author name shown (webhook). | | `avatarUrl` | string (URL) | Override the author avatar (webhook). | ```json theme={null} { "DISCORD": { "channelId": "", "text": "New release 🎉" } } ``` ## Slack - `data.SLACK` | Field | Type | Notes | | - | - | - | | **`channelId`** | string | The connected workspace channel (an integration "channel" id - see `integrations:list`). | | `text` | string | Message text. | | `uploadIds` | string\[] | Attachments. | | `username` | string | Override the author name shown. | | `avatarUrl` | string (URL) | Override the author avatar. | ```json theme={null} { "SLACK": { "channelId": "", "text": "Standup notes…" } } ``` ## Google Business Profile - `data.GOOGLE_BUSINESS` | Field | Type | Notes | | - | - | - | | `text` | string | The update body. | | `uploadIds` | string\[] | Images/videos. | | `topicType` | `STANDARD` \| `EVENT` \| `OFFER` \| `ALERT` | Post kind. | | `languageCode` | string | Language tag like `en` / `en-US`. | | `callToActionType` | `BOOK` \| `ORDER` \| `SHOP` \| `LEARN_MORE` \| `SIGN_UP` \| `CALL` | CTA button. | | `callToActionUrl` | string (URL) | CTA target. | | `eventTitle` / `eventStartDate` / `eventEndDate` | string | For `topicType: EVENT`. | | `offerCouponCode` / `offerRedeemOnlineUrl` / `offerTermsConditions` | string | For `topicType: OFFER`. | | `alertType` | `COVID_19` | For `topicType: ALERT`. | Set the location up in the dashboard first; details/categories/hours are managed via the SDK's `misc.googleBusiness*` methods (`integrations:trigger gbp:location`, `gbp:categories`). ```json theme={null} { "GOOGLE_BUSINESS": { "text": "Now open Saturdays!", "topicType": "STANDARD", "callToActionType": "LEARN_MORE", "callToActionUrl": "https://example.com" } } ``` ## Pinterest - `data.PINTEREST` | Field | Type | Notes | | - | - | - | | **`boardName`** | string | The board to pin to. | | `uploadIds` | string\[] | One image or video, or 2-5 images for a carousel Pin (same aspect ratio). | | `carouselItems` | object\[] | Per-slide `title`, `description`, `link` by `uploadId`. See [Carousel Pins](/api-reference/platforms/pinterest#carousel-pins). | | `text` | string | The Pin title. | | `description` | string | Pin description. | | `link` | string (URL) | Where the Pin links to. | | `altText` | string | Image alt text. | | `note` | string | Private note (not public). | | `thumbnail` | string (URL) | Cover image. | | `dominantColor` | string | Hex color used as a placeholder before the image loads. | | `isAiGenerated` | boolean | Adds Pinterest's AI disclosure label. | ```json theme={null} { "PINTEREST": { "boardName": "Inspiration", "text": "New idea", "uploadIds": [""], "link": "https://bundle.social" } } ``` ## Snapchat (Public Profile) - `data.SNAPCHAT` | Field | Type | Notes | | - | - | - | | `type` | `STORY` \| `SPOTLIGHT` | Default `STORY`. | | `uploadIds` | string\[] | One image or video. Video: 5–180s, ≥540×960, up to 100 MB. Images are Story-only. | | `text` | string | Alias for `description` (Spotlight). ≤160 chars. | | `description` | string | Spotlight description. ≤160 chars. | | `locale` | string | Spotlight locale in `en_US` form. Default `en_US`. | | `skipSaveToProfile` | boolean | Spotlight only - don't save the post to the profile. | Requires a Snapchat Public Profile. There is no comments API surface for Snapchat; profile and content analytics are available. ```json theme={null} { "SNAPCHAT": { "type": "SPOTLIGHT", "description": "Launch day", "locale": "en_US" } } ``` ## Media notes Images: JPG / PNG / WEBP / GIF. Video: MP4 / MOV / WEBM, up to 5 GB via the large-upload flow. [Upload media](/api-reference/upload-content) first (or let the CLI's `-m` do it), then put ids in `uploadIds` (and `carouselItems[].uploadId` / `mediaItems[].uploadId`). Large videos can take a while to process server-side after upload - a newly created post may sit in `PROCESSING` before going `POSTED`; check with `posts:get `, and `posts:retry ` for a transient platform failure. # Bluesky Source: https://info.bundle.social/api-reference/platforms/bluesky The AT Protocol. Calculated impressions, limited data, but growing fast. Bluesky is the new decentralized challenger, built on the AT Protocol. It's growing fast but the API is still maturing when it comes to analytics. ## Supported Content Types * **Posts:** Text with optional media. Up to 4 files. * **Text limit:** 300 characters. ## Quirks & Gotchas ### "Calculated" Impressions Bluesky does not provide a native "Impression" or "View" count for posts via API. * **Our Solution:** We calculate `impressions` as the sum of engagement (Likes + Replies + Reposts + Quotes). * **Reality:** The actual number of people who saw it is likely much higher, but we can't prove it. Think of it as a minimum engagement indicator, not true impressions. ### Limited But Growing Bluesky's API is young. As the platform and protocol mature, we expect more analytics data to become available. We'll add it when it does. ### Media Limits | Constraint | Value | | :- | :- | | Files | 0-4 (images and/or videos) | | Text | 300 characters | Bluesky has minimal media restrictions compared to other platforms. See [Platform Limits](/api-reference/limits#bluesky) for details. ### Video Upload Eligibility Bluesky decides per account whether it may upload videos. Before every video upload we ask Bluesky for the account's upload limits, so a refusal comes back with Bluesky's own reason instead of a bare `http_401`: | Error | What it means | Fix | | :- | :- | :- | | "Bluesky does not allow this account to upload videos: …" | Bluesky refuses video for this account. The most common cause is an **unverified email**. Not retried. | Verify the account's email in the Bluesky app (Settings → Account), then retry the post. Reconnecting doesn't help. | | "Bluesky daily video upload limit reached for this account: …" | The account used its daily video allowance. Retried later. | Wait for the daily limit to reset, or post fewer videos per day from this account. | Image and text posts are not affected. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 300 characters | | `tags` | Up to 8 tags, max 64 chars each | | `externalTitle` | Max 300 characters | | `externalDescription` | Max 1,000 characters | | `externalUrl` | Max 2,048 characters | | `videoAlt` | Max 10,000 characters | *** ## Post Options Send Bluesky-specific options inside `data.BLUESKY`. | Field | Type | Description | | :- | :- | :- | | `text` | `string` | Post text. Max 300 characters. | | `uploadIds` | `string[]` | Up to 4 uploaded media files. | | `tags` | `string[]` | Extra hashtags without `#`. Up to 8 tags, max 64 characters each. | | `labels` | `enum[]` | Self-labels: `!no-unauthenticated`, `porn`, `sexual`, `nudity`, `graphic-media`. | | `quoteUri` | `string` | AT-URI of a post to quote, for example `at://did.../app.bsky.feed.post/`. | | `externalUrl` | `string` | URL for an external link card. | | `externalTitle` | `string` | Link card title. Max 300 characters. | | `externalDescription` | `string` | Link card description. Max 1,000 characters. | | `thumbnail` | `string` | Optional bundle.social upload URL for the external link card image. Requires `externalUrl`. | | `videoAlt` | `string` | Alt text for the video embed. Max 10,000 characters. | ```json theme={null} { "teamId": "team_123", "title": "Bluesky link card", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["BLUESKY"], "data": { "BLUESKY": { "text": "New release notes are live", "tags": ["release", "product"], "externalUrl": "https://example.com/release-notes", "externalTitle": "Release notes", "externalDescription": "What shipped this week.", "thumbnail": "https://storage.bundle.social/path/to/uploaded-card-image.jpg" } } } ``` > [!NOTE] > > When `thumbnail` is provided, `externalUrl` is required. The thumbnail must be a public URL returned by a completed bundle.social upload. *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). ### Profile Analytics **Period:** Snapshot. | Metric | Description | Note | | :- | :- | :- | | `impressions` | - | Returns `0` (not available) | | `impressionsUnique` | - | Returns `0` (not available) | | `views` | - | Returns `0` (not available) | | `viewsUnique` | - | Returns `0` (not available) | | `likes` | - | Returns `0` (not available at profile level) | | `comments` | - | Returns `0` (not available at profile level) | | `postCount` | Total posts | | | `followers` | Followers | | | `following` | Following | | ### Post Analytics **Period:** Lifetime. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Engagement Sum | Calculated: Likes + Replies + Reposts + Quotes | | `impressionsUnique` | - | Returns `0` (not provided) | | `views` | - | Same as impressions (calculated) | | `viewsUnique` | - | Returns `0` (not provided) | | `likes` | Likes | | | `comments` | Replies | | | `shares` | Reposts + Quotes | Combined | | `saves` | - | Returns `0` (not available) | ### Quirks * No true impression or view metrics. We derive impressions from total engagement - it's the best we can do. * Profile-level engagement is not available. Only follower/following counts and post count. * As Bluesky's API evolves, we'll add new metrics as they become available. ### Raw Analytics Bluesky profile raw analytics store the actor profile payload. ```json theme={null} { "profile": { "did": "did:plc:abc123", "handle": "example.bsky.social", "displayName": "Example", "followersCount": 4200, "followsCount": 310, "postsCount": 180 } } ``` Bluesky post raw analytics store the post object returned by AT Protocol. ```json theme={null} { "post": { "uri": "at://did:plc:abc123/app.bsky.feed.post/3kabc", "cid": "bafy...", "author": { "handle": "example.bsky.social" }, "likeCount": 120, "replyCount": 18, "repostCount": 34, "quoteCount": 7 } } ``` # Discord Source: https://info.bundle.social/api-reference/platforms/discord Channel-based messaging via webhooks, not OAuth. Requires a channelId on every post, and supports custom bot identity and media attachments. Discord works differently from other platforms. Instead of OAuth tokens, we use **webhooks** that you set up in your Discord server. ## Quirks & Gotchas ### Webhook-Based Posting Discord doesn't allow third-party apps to post as a user. Instead, we use webhooks. * You connect a Discord server and select which channels to enable. * We create a webhook for each channel. * Posts appear as a "bot" message with a customizable username and avatar. ### Channel Selection Required Unlike other platforms, you must specify a `channelId` in your post data. You can find available channels in the `socialAccount.channels` array. ### Custom Bot Identity You can customize how your posts appear: * `username`: Up to 80 characters. This is the name shown as the message author. * `avatarUrl`: A URL to an image that will be used as the bot's avatar. *** ## Post Options | Field | Type | Description | | :- | :- | :- | | `channelId` | `string` | **Required.** The channel to post to. Found in `socialAccount.channels`. | | `text` | `string` | Message content. Max 2000 characters. | | `uploadIds` | `string[]` | Media attachments (images, videos). | | `username` | `string` | Custom display name. Max 80 characters. | | `avatarUrl` | `string` | Custom avatar URL. Max 2048 characters. | *** ## Media Limits | Constraint | Value | | :- | :- | | Files | 0-10 (images and/or videos, mixed allowed) | | Video max size | 25 MB | | Image max size | 25 MB | | Text | Max 2,000 characters | See [Platform Limits](/api-reference/limits#discord) for more details. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 2,000 characters | | `username` | Max 80 characters | | `avatarUrl` | Max 2,048 characters | *** ## Analytics For general analytics concepts, see the [Analytics Overview](/api-reference/analytics). Discord does not provide analytics via its API. All metrics return `0`. It's a messaging platform, not an analytics platform. | Metric | Note | | :- | :- | | `impressions` | Returns `0` | | `views` | Returns `0` | | `likes` | Returns `0` | | `comments` | Returns `0` | *** ## Example ```javascript theme={null} await bundle.post.create({ socialAccountTypes: ["DISCORD"], data: { DISCORD: { channelId: "123456789012345678", text: "Hello from bundle.social!", username: "My Bot", avatarUrl: "https://example.com/avatar.png" } } }); ``` # Facebook Source: https://info.bundle.social/api-reference/platforms/facebook Pages, Reels, Stories, and the eternal struggle with token expiration. The OG social network. It works, but it carries a lot of legacy baggage. And rate limits. So many rate limits. ## Supported Content Types * **Page Posts:** Text, Link, Image, Video. 0-10 files. * **Reels:** Vertical video for Pages. 1 video. * **Stories:** Image or video. 1 file. * **Page Reviews:** Import and reply to Facebook Page reviews through a separate async flow. ## Page Reviews Facebook Page Reviews run on a separate async flow. You start an import job, poll status, then fetch imported reviews and reply where Facebook allows it. Full guide: [Facebook Page Reviews](/api-reference/platforms/facebook-page-reviews) ## Quirks & Gotchas ### Page Tokens Expire (Important!) Facebook Page Access Tokens typically expire after **60 days**. > [!NOTE] > > **This is not a bug, it's a feature.** If a user changes their password or security settings, the token dies immediately. You need to build your app to handle re-connection flows gracefully. We handle automatic refreshing where possible, but we can't perform miracles. If the token dies, the user needs to reconnect. ### Reels Limitations Facebook Reels via API are stricter than mobile uploads: * No "Remix" functionality available via API. * Duration: **3 seconds to 20 minutes** (1200s). Stories remain limited to 60 seconds. * Minimum resolution: 540x960. Standard Page video posts also accept videos up to **20 minutes**. ### Media Limits See [Platform Limits](/api-reference/limits#facebook) for the full breakdown of file sizes, resolutions, aspect ratios, and bitrates. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 50,000 characters | | `link` | Max 2,048 characters | | `mediaTitle` | Max 255 characters. Facebook counts bytes, so a video title over 255 UTF-8 bytes (accents and emoji take 2-4 bytes each) is cut to fit. | | `altText` | Optional. Accessibility description for **image** posts (screen readers and when images fail to load). | > [!NOTE] > > **Alt text** applies to image-based Page posts. Pair it with your image `uploadIds` when you want Meta to store accessibility text alongside the media. *** ## Post Options | Field | Type | Description | | :- | :- | :- | | `type` | `POST` \| `REEL` \| `STORY` | Defaults to `POST`. | | `text` | `string` | Caption/body text. Max 50,000 characters. | | `uploadIds` | `string[]` | Media uploaded through bundle.social. | | `mediaItems` | `array` | Per-upload metadata, currently used for image `altText`. Each item needs `uploadId`. | | `link` | `string` | URL for Page posts. Only for `type: "POST"`. | | `thumbnail` | `string` | URL to an uploaded thumbnail image. | | `mediaTitle` | `string` | Video title for `POST` video uploads. Max 255 characters; titles over 255 UTF-8 bytes are cut to 255 bytes on a character boundary. | | `nativeScheduleTime` | `date` | Schedule inside Meta instead of immediately publishing through bundle.social. Max 30 days ahead. | ```json theme={null} { "teamId": "team_123", "title": "Facebook launch post", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["FACEBOOK"], "data": { "FACEBOOK": { "type": "POST", "text": "New launch is live", "uploadIds": ["upl_img_1"], "mediaItems": [ { "uploadId": "upl_img_1", "altText": "Product screenshot showing the new dashboard" } ], "link": "https://example.com" } } } ``` *** ## Page Mentions Tag another Facebook Page in a post by writing `@[pageId]` in `text`. Facebook turns it into a clickable mention of that Page: ```json theme={null} "text": "Big thanks to @[123456789012] for hosting us!" ``` Stories have no text, so they can't carry mentions. ### Find a Page ID **Endpoint:** `GET /api/v1/misc/facebook/pages` | Param | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team with a connected Facebook account. The lookup runs through that account. | | `q` | Yes | Page name, Page URL, `@handle` or numeric Page ID. Max 100 characters. | | `limit` | No | Max results for a name search, 1-25. Defaults to 10. | `q` works two ways: * **Page URL, `@handle` or ID** (`https://www.facebook.com/nike`, `@nike`, `123456789012`): resolved directly, returns that one Page. A Facebook link that isn't a Page (a group, a video, a deleted Page) returns an empty list. * **Anything else** (`Warsaw cafe`): full-text search, returns matching Pages. ```http theme={null} GET /api/v1/misc/facebook/pages?teamId=team_123&q=https://www.facebook.com/nike ``` ```json theme={null} { "items": [ { "pageId": "15087023444", "name": "Nike", "link": "https://www.facebook.com/nike", "location": null } ] } ``` `location` is filled for Pages that represent a physical place (city, street, coordinates, etc.). > [!NOTE] > > Search uses Meta's Page search, which only returns public Pages. Personal profiles and groups can't be found or mentioned. If the Facebook account is missing the required permissions, the endpoint returns `400` asking you to reconnect it. *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). ### Profile Analytics **Period:** Rolling window (30 days). > [!NOTE] > > **Why so many zeros?** To avoid hitting Facebook's aggressive rate limits, we've disabled fetching profile-level likes, comments, and post counts. We'd have to scan every single post on your page to get these, and Facebook would block us (and you). It's not worth it. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total impressions | | | `impressionsUnique` | Unique users reached | Uses 28-day period to avoid overcounting | | `views` | Page views | | | `viewsUnique` | - | Returns `0` (not provided by API) | | `likes` | - | Returns `0` (disabled to save rate limits) | | `comments` | - | Returns `0` (disabled to save rate limits) | | `postCount` | - | Returns `0` (disabled to save rate limits) | | `followers` | Page followers | | | `following` | - | Returns `0` (not applicable to Pages) | ### Post Analytics **Period:** Lifetime (Snapshot). | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total impressions | | | `impressionsUnique` | Unique impressions | | | `views` | Video views | Video posts only | | `viewsUnique` | Unique video views | Video posts only | | `likes` | Total reactions | Aggregates Like, Love, Wow, Haha, Anger | | `comments` | Total comments | | | `shares` | Total shares | | | `saves` | Total saves | | ### Reaction Aggregation When we say "Likes" for Facebook, we mean **all reactions** combined. Whether someone Loved it, Hated it (Anger), or Laughed at it (Haha) - it all counts as one `likes` number. We don't break down reaction types in the standard schema. If you need that granularity, check the [raw analytics data](#raw-analytics). ### Raw Analytics Facebook raw analytics include Page insight payloads for profiles and flat insight metric objects for posts. Use raw data when you need reaction-type totals such as `post_reactions_love_total`, video metrics such as `post_video_avg_time_watched`, or Page demographic payloads. #### Profile Raw Example ```json theme={null} { "pageInfo": { "id": "1234567890", "name": "Example Page", "followers_count": 12450, "fan_count": 11820, "link": "https://www.facebook.com/example" }, "pageInsights": { "data": [ { "name": "page_media_view", "period": "day", "values": [ { "value": 3120, "end_time": "2026-04-26T07:00:00+0000" } ] }, { "name": "page_views_total", "period": "day", "values": [ { "value": 184, "end_time": "2026-04-26T07:00:00+0000" } ] }, { "name": "page_daily_follows_unique", "period": "day", "values": [ { "value": 12, "end_time": "2026-04-26T07:00:00+0000" } ] } ] }, "mediaViewBreakdowns": { "isFromAds": { "true": 820, "false": 2300 }, "isFromFollowers": { "true": 1450, "false": 1670 } }, "pageDemographicInsights": { "data": [ { "name": "page_fans_country", "period": "lifetime", "values": [ { "value": { "US": 4200, "GB": 860, "DE": 540 } } ] } ] } } ``` #### Post Raw Example ```json theme={null} { "post_media_view": 14820, "post_clicks": 320, "post_reactions_like_total": 410, "post_reactions_love_total": 92, "post_reactions_wow_total": 11, "post_reactions_haha_total": 18, "post_reactions_anger_total": 1, "post_video_views": 11200, "post_video_views_unique": 9800, "post_video_avg_time_watched": 7400, "post_video_views_clicked_to_play": 1330, "comments": 44, "shares": 27, "saves": 9, "mediaViewBreakdowns": { "isFromAds": { "true": 3200, "false": 11620 }, "isFromFollowers": { "true": 6100, "false": 8720 } } } ``` * `pageInsights` also includes `page_daily_follows_unique`, `page_daily_unfollows_unique`, `page_post_engagements` and `page_total_actions` (daily values, raw only; they don't change the parsed metrics). * `mediaViewBreakdowns` splits views (`page_media_view` for the Page over the last 30 days, `post_media_view` for a post, lifetime) into paid vs organic (`isFromAds`) and followers vs non-followers (`isFromFollowers`). `true` is views from ads / from followers, `false` the rest. It splits views only, not unique reach. A breakdown Meta doesn't return is left out, and the whole field is missing when neither comes back. * **Reels:** reach (`impressionsUnique`) and `mediaViewBreakdowns` are read from the page post behind the reel, including for imported reels. They stay empty if Meta doesn't link the reel to a page post. * **Stories:** stories expire after 24 hours, so their analytics (views and unique views, plus reactions, comments and shares) are read once, when the story is imported through [post history import](/api-reference/import-posts). If Meta has no insights for a story, it's imported without analytics instead of with zeros. Stories aren't refreshed afterwards, and force refresh isn't supported for them. # Facebook Page Reviews Source: https://info.bundle.social/api-reference/platforms/facebook-page-reviews Import, sync, and reply to Facebook Page reviews with an async job flow. Facebook Page Reviews are handled through an async import flow. You queue an import, poll status, then work with normalized review records in our API. > [!NOTE] > > Facebook calls Page reviews **recommendations** in parts of its API. That is why these endpoints use `/recommendations`, even though this guide calls the feature Facebook Page Reviews. ## How it works This is an **asynchronous** job, same idea as Google Business Reviews: 1. **Start:** Trigger an import ("Fetch 50 reviews for this Page"). 2. **Wait:** We fetch from Facebook and process the batch. 3. **Poll:** Check import status. 4. **Fetch:** Read imported reviews from the recommendations endpoint. 5. **Reply:** Reply to the review or to comments inside the recommendation thread. *** ## Step 1: Start the Import **Endpoint:** `POST /api/v1/misc/facebook/recommendations/import` ```json theme={null} { "teamId": "team_123", "count": 50 } ``` ### Rules & Limits * **`count` range:** `1-250` per request. * **One active import per social account:** if one is already running or recently completed, you'll get `409`. * **Monthly limit per social account (default):** * **Free:** 5 reviews / month * **Pro:** 200 reviews / month * **Business:** 200 reviews / month > [!NOTE] > > These are defaults. Organizations can have custom review-import limits configured. You need a connected Facebook social account with a selected Page. No Page = no review import. *** ## Step 2: Check Import Status **Endpoints:** * `GET /api/v1/misc/facebook/recommendations/import?teamId=team_123` * `GET /api/v1/misc/facebook/recommendations/import/:importId` The list endpoint returns up to 20 latest imports for that team/Page, newest first. ### Statuses * `PENDING`: Waiting in queue. * `FETCHING_RECOMMENDATIONS`: Import is running. * `COMPLETED`: Finished. * `FAILED`: Import failed after retries. * `RATE_LIMITED`: Temporarily paused due to API/rate pressure; resumes automatically after `rateLimitResetAt`. Example import object: ```json theme={null} { "id": "imp_fb_abc123", "teamId": "team_123", "socialAccountId": "sa_123", "requestedCount": 50, "status": "FETCHING_RECOMMENDATIONS", "itemsImported": 24, "error": null, "rateLimitResetAt": null, "startedAt": "2026-04-27T10:00:00.000Z", "completedAt": null, "createdAt": "2026-04-27T09:59:55.000Z", "updatedAt": "2026-04-27T10:00:08.000Z", "deletedAt": null } ``` *** ## Step 3: Fetch Imported Reviews **Endpoints:** * `GET /api/v1/misc/facebook/recommendations?teamId=team_123&limit=50&offset=0` * `GET /api/v1/misc/facebook/recommendations/:recommendationId?teamId=team_123` ### Query Parameters (`GET /recommendations`) | Parameter | Type | Default | Description | | :- | :- | :- | :- | | `teamId` | string | required | Team ID | | `limit` | number | `50` | Page size (`1-1000`) | | `offset` | number | `0` | Pagination offset | Example response: ```json theme={null} { "recommendations": [ { "id": "rec_123", "socialAccountId": "sa_123", "teamId": "team_123", "externalRecommendationId": "1234567890", "openGraphStoryId": "9876543210", "reviewerDisplayName": "Jane Doe", "reviewerProfilePhotoUrl": "https://platform-lookaside.fbsbx.com/...", "recommendationValue": "RECOMMEND", "rating": null, "comment": "Great service and very fast support.", "hasMedia": false, "mediaSummary": [], "ownerReplyComment": "Thanks a lot for your feedback!", "ownerReplyCommentId": "comment_123", "ownerReplyUpdatedAt": "2026-04-27T12:15:00.000Z", "createTime": "2026-04-26T18:22:00.000Z", "updateTime": "2026-04-27T12:15:00.000Z", "importedAt": "2026-04-27T12:15:02.000Z", "createdAt": "2026-04-27T12:15:02.000Z", "updatedAt": "2026-04-27T12:15:02.000Z", "deletedAt": null } ], "total": 1, "limit": 200, "remainingCapacity": 176 } ``` `recommendationValue` values: `RECOMMEND`, `NOT_RECOMMEND`, `UNKNOWN`. `limit` in this response is your monthly import cap for that social account (not the page size). *** ## Step 4: Reply to Reviews ### Reply to a Review **Endpoint:** `PUT /api/v1/misc/facebook/recommendations/:recommendationId/reply` ```json theme={null} { "teamId": "team_123", "comment": "Thank you for visiting us!" } ``` `comment` length: `1-4096` chars. This creates a Facebook comment on the Page review story and stores it as `ownerReplyComment`. ### Fetch Thread Comments **Endpoint:** `GET /api/v1/misc/facebook/recommendations/:recommendationId/comments?teamId=team_123` ```json theme={null} { "comments": [ { "id": "comment_123", "recommendationId": "rec_123", "rootObjectId": "9876543210", "parentCommentId": null, "authorName": "Jane Doe", "authorExternalId": "fb_user_123", "authorAvatarUrl": "https://platform-lookaside.fbsbx.com/...", "text": "One more detail from the customer.", "likesCount": 2, "repliesCount": 1, "canReply": true, "createdTime": "2026-04-27T13:00:00.000Z" } ], "total": 1 } ``` ### Reply to a Thread Comment **Endpoint:** `PUT /api/v1/misc/facebook/recommendations/:recommendationId/comments/:commentId/reply` ```json theme={null} { "teamId": "team_123", "comment": "Happy to help!" } ``` Response: ```json theme={null} { "id": "reply_comment_123" } ``` *** ## Quirks & Gotchas ### Reviews Are Recommendations Facebook's native model is recommendation-based, not star-review-based. Some records may have `rating: null`; use `recommendationValue` as the primary signal. ### Some Reviews Cannot Be Replied To Replies require `openGraphStoryId`. If Facebook does not expose it for a review, reply and thread endpoints return an error instead of pretending the action worked. ### Incremental Sync Re-running imports is safe. Reviews are upserted by external recommendation ID, so existing records are updated instead of duplicated. ### Temporary `RATE_LIMITED` Is Normal When Facebook slows things down, imports switch to `RATE_LIMITED` and auto-resume. No manual retry endpoint needed for this path. ### Capacity Is Per Social Account `remainingCapacity` is calculated per connected Facebook social account, not globally across all accounts. # Google Business Source: https://info.bundle.social/api-reference/platforms/google-business Local SEO posts, events, offers, and updates for your business profile. Google Business Profile (formerly Google My Business) lets you post updates that appear in Google Search and Maps. It's not social media in the traditional sense, but it's great for local businesses. ## Location, profile, and Maps data Besides posts, you can read and update **Business Profile** data for the team's selected location (hours, attributes, services, food menus, action links, profile media). These use `/api/v1/misc/google-business` with the same API key as the rest of the public API. * [Location & profile](/api-reference/platforms/google-business-location) (GET/PATCH location fields and read field selection) * [Hours](/api-reference/platforms/google-business-hours) (regular, special, more hours) * [Attributes](/api-reference/platforms/google-business-attributes) * [Service list](/api-reference/platforms/google-business-service-list) * [Food menus](/api-reference/platforms/google-business-food-menus) * [Place action links](/api-reference/platforms/google-business-place-action-links) * [Profile media](/api-reference/platforms/google-business-profile-media) Reviews stay on a separate flow: [Google Business Reviews](/api-reference/platforms/google-business-reviews). ## Feature availability by category and location Google Business capabilities are not identical for every profile. Some fields or endpoints can be unavailable depending on category, country/region, and location-level eligibility. * **Attributes** differ by category and region. Build updates from available definitions first. * **Service list** is only available for eligible categories/locations. * **Food menus** are available mostly for restaurant-like categories and can be disabled for a specific location. * **Place action links** and allowed `placeActionType` values can vary by profile setup and category. * **Profile media** categories and moderation behavior can vary by profile type. Recommended flow for most integrations: **GET/list first**, then send **PATCH/POST** with values confirmed by Google for that exact location. ## Supported Content Types * **Standard Posts:** Regular text updates with optional image. * **Events:** Time-bound events with a title and date range. * **Offers:** Promotional offers with coupon codes and terms. * **Alerts:** Special alerts (currently only `COVID_19`). * **Reviews & Replies:** Import reviews asynchronously, then manage owner replies. ## Quirks & Gotchas ### Location Selection Required After connecting your Google account, you must select a business location. This is similar to selecting a Facebook Page or LinkedIn Company Page. Each location is listed once in the account's `channels`, even when the login reaches it through several Google accounts or location groups. When you refresh channels and Google now lists the selected location under a different account or group, the selection is kept and follows it. It's cleared only when the login no longer has access to the location. ### Post Types Google Business supports different post types via the `topicType` field: * `STANDARD`: Regular updates (default). * `EVENT`: Time-bound events with a title and date range. * `OFFER`: Promotional offers with coupon codes and terms. * `ALERT`: Special alerts (currently only `COVID_19`). ### Call to Action You can add a CTA button to `STANDARD` and `EVENT` posts (not `OFFER` or `ALERT`): * `BOOK`, `ORDER`, `SHOP`, `LEARN_MORE`, `SIGN_UP`, `CALL` * Requires a `callToActionUrl` for every type except `CALL`. ### Media Limits | Constraint | Value | | :- | :- | | Files | 0-1 image only (no video) | | Image max size | 5 MB | | Image min resolution | 250x250 | | Text | Max 1,500 characters | See [Platform Limits](/api-reference/limits#google-business) for details. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 1,500 characters | | `eventTitle` | Max 58 characters | | `offerCouponCode` | Max 58 characters | | `offerTermsConditions` | Max 1,500 characters | *** ## Google Reviews Google Reviews run on a separate async flow (similar to Post History Import). You start an import job, poll status, then fetch imported reviews and manage replies. * Start import + poll status (`PENDING` -> `FETCHING_REVIEWS` -> `COMPLETED`) * Handle temporary pauses with `RATE_LIMITED` and automatic resume * List imported reviews with pagination and capacity info * Create/update/delete owner replies via API Full guide: [Google Business Reviews](/api-reference/platforms/google-business-reviews) *** ## Post Options | Field | Type | Description | | :- | :- | :- | | `text` | `string` | Post content. Max 1,500 characters. | | `uploadIds` | `string[]` | Media attachments (images only). | | `topicType` | `enum` | Post type: `STANDARD`, `EVENT`, `OFFER`, `ALERT`. Default: `STANDARD`. | | `languageCode` | `string` | Language code (e.g., `en`, `en-US`). Default: `en`. | | `callToActionType` | `enum` | CTA button: `BOOK`, `ORDER`, `SHOP`, `LEARN_MORE`, `SIGN_UP`, `CALL`. | | `callToActionUrl` | `string` | URL for the CTA button. | | `alertType` | `enum` | Alert type for `ALERT` posts. Currently only `COVID_19`. | ### Event-Specific Fields | Field | Type | Description | | :- | :- | :- | | `eventTitle` | `string` | Event title. Max 58 characters. | | `eventStartDate` | `date` | Event start date. | | `eventEndDate` | `date` | Event end date. | ### Offer-Specific Fields | Field | Type | Description | | :- | :- | :- | | `offerCouponCode` | `string` | Coupon code. Max 58 characters. | | `offerRedeemOnlineUrl` | `string` | URL to redeem the offer online. | | `offerTermsConditions` | `string` | Terms and conditions. Max 1,500 characters. | > [!NOTE] > > An `OFFER` post needs `eventStartDate` (optionally `eventEndDate`) and at least one of `offerCouponCode`, `offerRedeemOnlineUrl` or `offerTermsConditions`. Offers can't have a button: `callToActionType` is rejected. *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). Google Business provides basic analytics for your business location. Don't expect Instagram-level data here. ### Profile Analytics **Period:** Rolling 30-day window. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total Business Profile impressions | Sum of desktop/mobile Search and Maps impressions | | `impressionsUnique` | - | Returns `0` (not provided by Google Business Profile API) | | `views` | - | Returns `0` in the standard response | | `viewsUnique` | - | Returns `0` (not provided by Google Business Profile API) | | `likes` | - | Returns `0` (not applicable) | | `comments` | - | Returns `0` (not applicable) | | `postCount` | - | Returns `0` | | `followers` | - | Returns `0` (not applicable) | | `following` | - | Returns `0` (not applicable) | The raw analytics response also includes a summary with `websiteClicks`, `callClicks`, `directionRequests`, and `conversations`. ### Post Analytics Google Business post analytics are **not currently returned** through our API. The standard post analytics endpoint returns no Google Business post rows, and raw post analytics are not available for Google Business. Use profile/location raw analytics when you need Google Business performance data. ### Raw Analytics Google Business currently exposes profile/location raw analytics, not individual post raw analytics. ```json theme={null} { "locationInfo": { "name": "locations/1234567890", "title": "Example Shop", "metadata": { "mapsUri": "https://maps.google.com/..." } }, "dailyMetrics": { "multiDailyMetricTimeSeries": [ { "dailyMetricTimeSeries": [ { "dailyMetric": "BUSINESS_IMPRESSIONS_DESKTOP_SEARCH", "timeSeries": { "points": [ { "date": { "year": 2026, "month": 4, "day": 26 }, "value": "420" } ] } } ] } ] }, "summary": { "impressionsTotal": 12420, "websiteClicks": 182, "callClicks": 31, "directionRequests": 77, "conversations": 9 }, "range": { "start": "2026-03-28", "end": "2026-04-27" } } ``` *** ## Examples ### Standard Post ```javascript theme={null} await bundle.post.create({ teamId: "team_123", title: "Holiday hours", status: "SCHEDULED", postDate: "2026-06-01T15:00:00.000Z", socialAccountTypes: ["GOOGLE_BUSINESS"], data: { GOOGLE_BUSINESS: { text: "We're open for the holidays! Visit us today.", callToActionType: "LEARN_MORE", callToActionUrl: "https://example.com/holiday-hours" } } }); ``` ### Event Post ```javascript theme={null} await bundle.post.create({ teamId: "team_123", title: "Grand opening", status: "SCHEDULED", postDate: "2026-06-01T15:00:00.000Z", socialAccountTypes: ["GOOGLE_BUSINESS"], data: { GOOGLE_BUSINESS: { topicType: "EVENT", text: "Join us for our grand opening celebration!", eventTitle: "Grand Opening", eventStartDate: "2026-02-01T10:00:00Z", eventEndDate: "2026-02-01T18:00:00Z", callToActionType: "BOOK", callToActionUrl: "https://example.com/rsvp" } } }); ``` ### Offer Post ```javascript theme={null} await bundle.post.create({ teamId: "team_123", title: "Welcome offer", status: "SCHEDULED", postDate: "2026-06-01T15:00:00.000Z", socialAccountTypes: ["GOOGLE_BUSINESS"], data: { GOOGLE_BUSINESS: { topicType: "OFFER", text: "Get 20% off your first order!", eventStartDate: "2026-06-01T00:00:00.000Z", eventEndDate: "2026-06-30T23:59:59.000Z", offerCouponCode: "WELCOME20", offerRedeemOnlineUrl: "https://example.com/shop", offerTermsConditions: "Valid for new customers only. Expires Feb 28, 2026." } } }); ``` # Google Business Attributes Source: https://info.bundle.social/api-reference/platforms/google-business-attributes Read location attributes, list attribute definitions for the category, and update structured facts on the profile. **Attributes** are structured facts Google shows on the profile (for example payments, accessibility, services). Valid attribute IDs and value types depend on **primary category** and region. The same attribute payload can work for one location and fail for another. Use this order for reliable updates: 1. **List available** to discover allowed definitions for the selected location. 2. **Get current attributes** to inspect current value shapes. 3. **Patch** only supported names and values. **Base path:** `/api/v1/misc/google-business` *** ## Get current attributes **Endpoint:** `GET /api/v1/misc/google-business/location/attributes` | Query | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team with selected Google Business location. | Response includes `attributes`: an array of objects. Each item has a `name` (for example `attributes/pay_credit_card`) and a value field whose shape depends on the attribute **type**. *** ## Value types (response and request) | Kind | JSON shape | Notes | | :- | :- | :- | | Boolean | `"values": [true]` or `"values": [false]` | Google uses a one-element array for booleans. | | Enum (multi) | `"repeatedEnumValue": { "setValues": ["TOKEN", ...] }` | Allowed tokens come from **list available** for that attribute. | | URL list | `"uriValues": [{ "uri": "https://..." }]` | When the attribute stores links. | Always confirm the expected shape for a given `name` via **list available** or **get** before you build your UI. Do not assume that every boolean/enum/url-style field is valid for every category. *** ## List available attribute definitions **Endpoint:** `GET /api/v1/misc/google-business/location/attributes/available` Use this to build dropdowns or validation in your product. Google returns definitions for attributes applicable to the location. | Query | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `languageCode` | No | BCP-47 language for labels (for example `en`). | | `regionCode` | No | CLDR region (for example `US`). | | `pageSize` | No | Integer 1 to 200. | | `pageToken` | No | Pagination token from a previous response. | Response includes `attributes` (definition objects) and optional `nextPageToken`. ### Google-side selection context Google's attribute catalog is context-sensitive. Availability depends on location/category/region, and can change over time. * In Google APIs, attribute metadata is selected using location/category and localization context. * In this API, `teamId` selects the connected location context, while optional `languageCode` and `regionCode` help localize/filter definitions. * Treat this endpoint as the source of truth for what can be patched now. *** ## Update attributes **Endpoint:** `PATCH /api/v1/misc/google-business/location/attributes` ### Body | Field | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `attributes` | Optional | Array of attribute objects in the **update payload**. Each item includes `name` (`attributes/...`) and the value fields for that attribute type (`values`, `repeatedEnumValue`, `uriValues`, etc.). | | `attributeMask` | Optional | Comma-separated list of attribute paths, aligned with what you send in `attributes`. If omitted, the API can derive it from `attributes[].name` as `attributes/{id}` joined with commas. You must end up with at least one attribute path (explicit or derived) in the request. | ### Example: many boolean attributes (sample ids) The following **update payload** shows real-style `attributes/...` ids and boolean `values` arrays. Replace `teamId` with your team. Only use attribute ids that **list available** or **get** returns for your location (ids differ by category and region). ```json theme={null} { "teamId": "00000000-0000-4000-8000-000000000001", "attributeMask": "attributes/pay_credit_card,attributes/pay_debit_card,attributes/is_owned_by_women,attributes/requires_cash_only,attributes/has_onsite_services,attributes/has_in_store_pickup,attributes/has_parking_street_free,attributes/buys_goods_used,attributes/has_recycling_electronics,attributes/has_delivery,attributes/has_in_store_shopping", "attributes": [ { "name": "attributes/pay_credit_card", "values": [true] }, { "name": "attributes/pay_debit_card", "values": [true] }, { "name": "attributes/is_owned_by_women", "values": [false] }, { "name": "attributes/requires_cash_only", "values": [false] }, { "name": "attributes/has_onsite_services", "values": [false] }, { "name": "attributes/has_in_store_pickup", "values": [true] }, { "name": "attributes/has_parking_street_free", "values": [true] }, { "name": "attributes/buys_goods_used", "values": [true] }, { "name": "attributes/has_recycling_electronics", "values": [true] }, { "name": "attributes/has_delivery", "values": [true] }, { "name": "attributes/has_in_store_shopping", "values": [false] } ] } ``` ### Example: enum-style attribute ```json theme={null} { "teamId": "00000000-0000-4000-8000-000000000001", "attributes": [ { "name": "attributes/ATTRIBUTE_ID_FROM_LIST_OR_GET", "repeatedEnumValue": { "setValues": ["ALLOWED_ENUM_TOKEN"] } } ] } ``` Exact `name` strings and allowed enum tokens come from **list available** and Google's attribute catalog for that category. *** ## Related * [Location & profile](/api-reference/platforms/google-business-location) for core profile fields outside attributes. # Google Business Food menus Source: https://info.bundle.social/api-reference/platforms/google-business-food-menus Read and update food menus for restaurant-class Google Business Profile locations. **Food menus** apply to many restaurant and food categories. Google may disable the feature for a given location. In that case GET and PATCH return an error explaining that food menus are not available. Availability and accepted menu structure can differ by category, region, and profile eligibility. **Base path:** `/api/v1/misc/google-business` *** ## Get food menus **Endpoint:** `GET /api/v1/misc/google-business/location/food-menus` | Query | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `fields` | No | Subset to return: `name`, `menus`. If omitted, both are requested. Comma-separated or repeated param style. | *** ## Update food menus **Endpoint:** `PATCH /api/v1/misc/google-business/location/food-menus` | Field | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `fields` | Yes | Must include `menus` in the **update payload**. | | `menus` | Optional | Array of menu objects (sections, items, prices) as defined by Google's food menu schema. | The location should have food menus enabled (`canHaveFoodMenus`). Otherwise the API responds with an error. Best practice: fetch current menus first and edit from returned objects, because some nested fields can be accepted/rejected depending on the location's Google configuration. If your UI allows menu editing, fetch `metadata` from `GET /location` and gate editing by `metadata.canHaveFoodMenus`. ### Example (minimal structure) Menus are hierarchical (menu, sections, items). Field names must match Google's API. ```json theme={null} { "teamId": "00000000-0000-4000-8000-000000000001", "fields": ["menus"], "menus": [ { "labels": [ { "displayName": "Main menu", "languageCode": "en" } ], "sections": [ { "labels": [{ "displayName": "Starters", "languageCode": "en" }], "items": [ { "attributes": { "price": { "currencyCode": "USD", "units": "8" } }, "labels": [{ "displayName": "Soup of the day", "languageCode": "en" }] } ] } ] } ] } ``` Treat Google's returned objects from **GET** as the source of truth for nesting and optional fields, then adjust for your PATCH. *** ## Related * [Service list](/api-reference/platforms/google-business-service-list) for non-menu structured services. # Google Business Hours Source: https://info.bundle.social/api-reference/platforms/google-business-hours Update regular, special, and more hours for a Google Business Profile location with explicit field selection. Use this endpoint when you only need to change **opening hours** (regular weekly hours, special dates, or additional hour types). It updates the same Google location resource as [Location & profile](/api-reference/platforms/google-business-location), but requires an explicit `fields` array so the API knows which hour sections are part of your **update payload**. **Endpoint:** `PATCH /api/v1/misc/google-business/location/hours` **Base path:** `/api/v1/misc/google-business` *** ## Body rules | Field | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team with a connected Google Business location. | | `fields` | Yes | Which hour sections this **update payload** applies to. Each value must be one of: `regularHours`, `specialHours`, `moreHours`. You can pass one or more (comma-separated or repeated style, same as other query lists in this API). | | `regularHours` | Optional | Weekly schedule. Omit if not in `fields`. | | `specialHours` | Optional | Date-specific overrides. Omit if not in `fields`. | | `moreHours` | Optional | Array of extra hour groups (for example pickup). Omit if not in `fields`. | | `validateOnly` | Optional | If `true`, validation only, no persist. | You must include **at least one** hour block that matches `fields`. The server forwards the **update payload** to Google. *** ## Time and day shapes **Weekdays** for `openDay` / `closeDay` in periods: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY` **Time** can be sent as: * A string like `"09:00"` or `"09:00:00"` (normalized to Google's time-of-day object where supported), or * An object: `hours`, `minutes`, optional `seconds`, optional `nanos`. **Special hours** periods may include `startDate` / `endDate` with `year`, `month`, `day`, plus `openTime`, `closeTime`, and `closed: true` when the location is closed all day. *** ## Example: full hours update payload (anonymized) `teamId` is a placeholder. Structure matches a real multi-section hours **update payload**: regular week, holiday exceptions, and `moreHours` with a type id (use values Google returns for your location for `hoursTypeId`). ```json theme={null} { "teamId": "00000000-0000-4000-8000-000000000001", "fields": ["regularHours", "specialHours", "moreHours"], "regularHours": { "periods": [ { "openDay": "MONDAY", "openTime": "10:00", "closeDay": "MONDAY", "closeTime": "18:00" }, { "openDay": "TUESDAY", "openTime": "10:00", "closeDay": "TUESDAY", "closeTime": "18:00" }, { "openDay": "WEDNESDAY", "openTime": "10:00", "closeDay": "WEDNESDAY", "closeTime": "18:00" }, { "openDay": "THURSDAY", "openTime": "10:00", "closeDay": "THURSDAY", "closeTime": "18:00" }, { "openDay": "FRIDAY", "openTime": "10:00", "closeDay": "FRIDAY", "closeTime": "18:00" }, { "openDay": "SATURDAY", "openTime": "10:00", "closeDay": "SATURDAY", "closeTime": "15:00" } ] }, "specialHours": { "specialHourPeriods": [ { "startDate": { "year": 2026, "month": 12, "day": 24 }, "endDate": { "year": 2026, "month": 12, "day": 24 }, "openTime": "10:00", "closeTime": "14:00", "closed": false }, { "startDate": { "year": 2026, "month": 12, "day": 25 }, "endDate": { "year": 2026, "month": 12, "day": 25 }, "closed": true } ] }, "moreHours": [ { "hoursTypeId": "PICKUP", "periods": [ { "openDay": "MONDAY", "openTime": "10:00", "closeDay": "MONDAY", "closeTime": "18:00" }, { "openDay": "TUESDAY", "openTime": "10:00", "closeDay": "TUESDAY", "closeTime": "18:00" }, { "openDay": "WEDNESDAY", "openTime": "10:00", "closeDay": "WEDNESDAY", "closeTime": "18:00" }, { "openDay": "THURSDAY", "openTime": "10:00", "closeDay": "THURSDAY", "closeTime": "18:00" }, { "openDay": "FRIDAY", "openTime": "10:00", "closeDay": "FRIDAY", "closeTime": "18:00" }, { "openDay": "SATURDAY", "openTime": "10:00", "closeDay": "SATURDAY", "closeTime": "15:00" } ] } ] } ``` *** ## Related * [Location & profile](/api-reference/platforms/google-business-location) if you also change non-hour fields in one call. # Google Business Location & profile Source: https://info.bundle.social/api-reference/platforms/google-business-location Read and update Business Profile location data: title, categories, address, phone, hours-related fields in one profile patch, and more. These endpoints read or update the **Google Business Profile location** resource for the team's selected location. They map to Google's Business Information API. You need a connected Google Business account with a **location already selected** (same rule as posts). **Base path:** `/api/v1/misc/google-business` All requests use your usual API key authentication. *** ## Get location **Endpoint:** `GET /api/v1/misc/google-business/location` ### Query | Parameter | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team that owns the connected Google Business social account. | | `fields` | No | Subset of location fields to return. If omitted, a **default profile-oriented field list** is used (name, title, profile, website, phones, categories, hours fields, address, service area, coordinates, open info, metadata). | `fields` accepts **comma-separated** values or **repeated** query params, for example `fields=name,title` or `fields=name&fields=title`. Allowed `fields` values (Google read field paths): `name`, `languageCode`, `storeCode`, `title`, `phoneNumbers`, `categories`, `storefrontAddress`, `websiteUri`, `regularHours`, `specialHours`, `serviceArea`, `labels`, `adWordsLocationExtensions`, `latlng`, `openInfo`, `metadata`, `profile`, `relationshipData`, `moreHours`, `serviceItems` The response shape follows Google's API (we pass through the payload). Use it to drive your own UI or to read state before a patch. *** ## Update location **Endpoint:** `PATCH /api/v1/misc/google-business/location` Only the top-level keys you include in the **update payload** are sent to Google. Only the fields listed below participate. Send **at least one** patchable field. The API automatically determines which provided fields should be updated. ### Patchable fields | Field | Purpose | | :- | :- | | `title` | Display name (max 255 characters). Use `null` to clear where Google allows. | | `profile` | Object with `description` (max 1500 characters) and other Google-supported keys. | | `websiteUri` | Public website URL. | | `phoneNumbers` | `primaryPhone`, `additionalPhones[]`. | | `categories` | `primaryCategory.name`, `additionalCategories[].name` (Google category resource names). | | `storefrontAddress` | Structured address (`regionCode`, `postalCode`, `locality`, `addressLines`, etc.). | | `regularHours` | Standard weekly hours (`periods` with open/close days and times). | | `specialHours` | Exceptions (`specialHourPeriods` with dates and closed flag). | | `moreHours` | Named hour sets (for example department-specific hours); each item can include `hoursTypeId` and `periods`. | | `openInfo` | Opening status metadata (Google's schema). | | `serviceArea` | Service-area business definition (Google's schema). | | `latlng` | `latitude` and `longitude`. | ### Other body keys | Field | Description | | :- | :- | | `validateOnly` | If `true`, Google validates the request without applying the change. | ### Useful metadata for feature eligibility Google location metadata can indicate whether certain feature families are available for this location. In particular: * `metadata.canModifyServiceList` controls service-list edit eligibility. * `metadata.canHaveFoodMenus` controls food-menu eligibility. Read `metadata` through `GET /location` before enabling related editing UI. ### Find Available Categories Use `GET /api/v1/misc/google-business/location/categories/available` to resolve Google category resource names before updating `categories`. | Query | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team with the connected Google Business location. | | `regionCode` | Yes | Two-letter region code, for example `US` or `PL`. | | `languageCode` | Yes | Label language, for example `en` or `pl`. | | `names` | No | One to 100 exact category resource names. Accepts repeated or comma-separated values and uses Google's batch lookup. | | `filter` | No | Category display-name prefix filter used when `names` is omitted. | | `pageSize` | No | Fixed at `50`. | | `pageToken` | No | Token from the previous page. | | `view` | No | `BASIC` by default; `FULL` requests the expanded category view. | Use either exact `names` or discovery through `filter`, then send the returned category `name` as `primaryCategory.name` or inside `additionalCategories`. ### Example: title, description, and hours (anonymized) Single **update payload** with profile copy plus weekly hours, holiday exceptions, and an extra hour type (`moreHours`). `teamId` and business copy below are placeholders. ```json theme={null} { "teamId": "00000000-0000-4000-8000-000000000001", "title": "Example Shop - Used CDs", "profile": { "description": "Second-hand CD store for collectors. Rock, pop, jazz, and soundtracks. Each disc is checked for condition before sale." }, "regularHours": { "periods": [ { "openDay": "MONDAY", "openTime": "10:00", "closeDay": "MONDAY", "closeTime": "18:00" }, { "openDay": "TUESDAY", "openTime": "10:00", "closeDay": "TUESDAY", "closeTime": "18:00" }, { "openDay": "WEDNESDAY", "openTime": "10:00", "closeDay": "WEDNESDAY", "closeTime": "18:00" }, { "openDay": "THURSDAY", "openTime": "10:00", "closeDay": "THURSDAY", "closeTime": "18:00" }, { "openDay": "FRIDAY", "openTime": "10:00", "closeDay": "FRIDAY", "closeTime": "18:00" }, { "openDay": "SATURDAY", "openTime": "10:00", "closeDay": "SATURDAY", "closeTime": "15:00" } ] }, "specialHours": { "specialHourPeriods": [ { "startDate": { "year": 2026, "month": 12, "day": 24 }, "endDate": { "year": 2026, "month": 12, "day": 24 }, "openTime": "10:00", "closeTime": "14:00", "closed": false }, { "startDate": { "year": 2026, "month": 12, "day": 25 }, "endDate": { "year": 2026, "month": 12, "day": 25 }, "closed": true } ] }, "moreHours": [ { "hoursTypeId": "PICKUP", "periods": [ { "openDay": "MONDAY", "openTime": "10:00", "closeDay": "MONDAY", "closeTime": "18:00" }, { "openDay": "TUESDAY", "openTime": "10:00", "closeDay": "TUESDAY", "closeTime": "18:00" }, { "openDay": "WEDNESDAY", "openTime": "10:00", "closeDay": "WEDNESDAY", "closeTime": "18:00" }, { "openDay": "THURSDAY", "openTime": "10:00", "closeDay": "THURSDAY", "closeTime": "18:00" }, { "openDay": "FRIDAY", "openTime": "10:00", "closeDay": "FRIDAY", "closeTime": "18:00" }, { "openDay": "SATURDAY", "openTime": "10:00", "closeDay": "SATURDAY", "closeTime": "15:00" } ] } ] } ``` ### Smaller payloads You can send partial **update payloads**, for example only `title` and `websiteUri`, or only `profile`. ### Hours only You may include `regularHours`, `specialHours`, or `moreHours` in this endpoint, or use the dedicated [Hours](/api-reference/platforms/google-business-hours) endpoint when you only change hours and want an explicit `fields` list for hour sections. *** ## Related * [Google Business Hours](/api-reference/platforms/google-business-hours) for updates that only touch `regularHours`, `specialHours`, or `moreHours` with an explicit `fields` list. * [Google Business main guide](/api-reference/platforms/google-business) for posts and analytics. # Google Business Place action links Source: https://info.bundle.social/api-reference/platforms/google-business-place-action-links List, create, update, and delete action links such as ordering, reservations, or appointments on the profile. **Place action links** are URLs shown on the profile for actions like **order online**, **book**, or **reserve**. Google validates URLs and types. Use list to read existing links and obtain resource **names** for update or delete. **Base path:** `/api/v1/misc/google-business` *** ## Google `PlaceActionLink` resource fields | Field | Type | Notes | | :- | :- | :- | | `name` | `string` | Resource name in format `locations/{locationId}/placeActionLinks/{place_action_link_id}`. Ignored on create, used on patch/delete. | | `providerType` | `enum` | Output-only. Provider type (`MERCHANT`, `AGGREGATOR_3P`, `PROVIDER_TYPE_UNSPECIFIED`). | | `isEditable` | `boolean` | Output-only. Whether the link can be edited by the client. | | `uri` | `string` | Required by Google for create. Link URL. | | `placeActionType` | `enum` | Required by Google for create. Action type represented by the link. | | `isPreferred` | `boolean` | Optional. Only one preferred link per `placeActionType` for a location. | | `createTime` | `string` | Output-only RFC3339 timestamp. | | `updateTime` | `string` | Output-only RFC3339 timestamp. | *** ## `placeActionType` values | Value | Typical use | | :- | :- | | `APPOINTMENT` | Generic appointment booking. | | `ONLINE_APPOINTMENT` | Online appointment booking. | | `DINING_RESERVATION` | Table reservations. | | `FOOD_ORDERING` | Order food. | | `FOOD_DELIVERY` | Delivery. | | `FOOD_TAKEOUT` | Takeout. | | `SHOP_ONLINE` | E-commerce or online shopping. | ### `providerType` values (output-only) | Value | Meaning | | :- | :- | | `PROVIDER_TYPE_UNSPECIFIED` | Unspecified provider type. | | `MERCHANT` | Merchant-owned link (or agency acting for the merchant). | | `AGGREGATOR_3P` | Third-party aggregator integration. | ### How availability is determined in Google Google also provides place action type metadata at the API level (for example with location or region filters and optional language localization). In practice, allowed values can differ by business category and location setup. For reliable behavior: 1. Read current links for the selected location. 2. Update only action types that are already accepted or explicitly available for that location context. *** ## List links **Endpoint:** `GET /api/v1/misc/google-business/location/place-action-links` | Query | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `pageSize` | No | 1 to 100. | | `pageToken` | No | Pagination. | Response: `placeActionLinks` array and optional `nextPageToken`. Each link may include `name`, `uri`, `placeActionType`, `isPreferred`, and output-only Google metadata such as `providerType`, `isEditable`, `createTime`, `updateTime`. *** ## Create link **Endpoint:** `POST /api/v1/misc/google-business/location/place-action-links` ### Body | Field | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `placeActionLink` | Yes | Nested object sent to Google. Should include at least `uri` and `placeActionType` for create. | ### Example (nested-only payload) ```json theme={null} { "teamId": "team_123", "placeActionLink": { "uri": "https://example.com/order", "placeActionType": "FOOD_ORDERING", "isPreferred": true } } ``` *** ## Update link **Endpoint:** `PATCH /api/v1/misc/google-business/location/place-action-links` | Field | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `name` | Yes | Full resource name from Google, for example `locations/{locationId}/placeActionLinks/{id}`. Must belong to the selected authorized location. | | `fields` | Yes | Subset of updated fields: `uri`, `placeActionType`, `isPreferred` (one or more). | | `placeActionLink` | Yes | Nested object with updated values. Include keys matching `fields`. | ### Example ```json theme={null} { "teamId": "team_123", "name": "locations/12345678901234567890/placeActionLinks/abcdef", "fields": ["uri", "isPreferred"], "placeActionLink": { "uri": "https://example.com/new-order", "isPreferred": true } } ``` *** ## Delete link **Endpoint:** `DELETE /api/v1/misc/google-business/location/place-action-links` ```json theme={null} { "teamId": "team_123", "name": "locations/12345678901234567890/placeActionLinks/abcdef" } ``` `name` must be the full Google resource name including `/placeActionLinks/` and must belong to the selected authorized location. *** ## Availability caveats Google may restrict place action links and action types based on business category, location, region, and profile eligibility. * Some `placeActionType` values may be rejected for specific business categories. * Features can vary between locations on the same account. * Recommended flow: call **list** first, then create/update using supported values for that location. *** ## Related * [Profile media](/api-reference/platforms/google-business-profile-media) for listing photos and videos on the profile. # Google Business Profile media Source: https://info.bundle.social/api-reference/platforms/google-business-profile-media List and delete photos or videos on the Google Business Profile, and add media via uploadId. These endpoints manage **media items** attached to the selected Business Profile location (photos and some videos). They complement post images: profile media appears in the **Photos** area of the profile, not only inside a single post. Media capabilities are partially category/profile dependent. Some categories or media types may be limited by Google policy, moderation, or profile eligibility. **Base path:** `/api/v1/misc/google-business` *** ## List media **Endpoint:** `GET /api/v1/misc/google-business/media` | Query | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `pageSize` | No | 1 to 250. | | `pageToken` | No | Pagination. | Response includes `mediaItems` (each may have `name`, `googleUrl`, `mediaFormat` `PHOTO` or `VIDEO`, `thumbnailUrl`, `description`, `locationAssociation` with optional `category`, and so on), plus optional `nextPageToken` and `totalMediaItemCount`. *** ## Delete media **Endpoint:** `DELETE /api/v1/misc/google-business/media` ```json theme={null} { "teamId": "team_123", "mediaName": "accounts/123/locations/456/media/789" } ``` `mediaName` is the **full resource name** returned by Google for that media item. *** ## Add media (upload) **Endpoint:** `POST /api/v1/misc/google-business/media` Use after you uploaded a file through the standard [upload](/api-reference/upload-content) flow and obtained an `uploadId`. | Field | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `uploadId` | Yes | From your completed upload. | | `category` | No | One of: `CATEGORY_UNSPECIFIED`, `COVER`, `PROFILE`, `LOGO`, `EXTERIOR`, `INTERIOR`, `PRODUCT`, `AT_WORK`, `FOOD_AND_DRINK`, `MENU`, `COMMON_AREA`, `ROOMS`, `TEAMS`, `ADDITIONAL` (default behavior may treat unspecified as `ADDITIONAL`). | | `description` | No | Max 2000 characters. | Some `category` values may be less relevant or not applied consistently for specific business categories. If unsure, list current media first and mirror categories already used by Google on that location. ### Example ```json theme={null} { "teamId": "team_123", "uploadId": "upload_abc123", "category": "EXTERIOR", "description": "Storefront at night" } ``` *** ## Related * [Google Business main guide](/api-reference/platforms/google-business) for **post** images and post limits. * [Connect social accounts](/api-reference/connect-social-accounts) if the account is not connected yet. # Google Business Reviews Source: https://info.bundle.social/api-reference/platforms/google-business-reviews Import, sync, and reply to Google Business reviews with an async job flow. Google Business reviews are handled through an async import flow. You queue an import, poll status, then work with normalized review records in our API. ## How it works This is an **asynchronous** job, same idea as Post History Import: 1. **Start:** Trigger an import ("Fetch 50 reviews for this location"). 2. **Wait:** We fetch from Google and process the batch. 3. **Poll:** Check import status. 4. **Fetch:** Read imported reviews from the reviews endpoint. 5. **Reply:** Create/update/delete owner replies. *** ## Step 1: Start the Import **Endpoint:** `POST /api/v1/misc/google-business/reviews/import` ```json theme={null} { "teamId": "team_123", "count": 50 } ``` ### Rules & Limits * **`count` range:** `1-250` per request. `count` is the number of **new** reviews to import: reviews you already have are refreshed but don't count, so re-running an import continues into older reviews until it has `count` new ones or Google has no more. * **Only new reviews use up the monthly limit.** Re-fetched reviews are free. * **One active import per social account:** if one is already running, you'll get `409`. * **Monthly limit per social account (default):** * **Free:** 5 reviews / month * **Pro:** 200 reviews / month * **Business:** 200 reviews / month > [!NOTE] > > These are defaults. Organizations can have custom review-import limits configured. You need a connected Google Business social account with a selected location. No location = no review import. *** ## Step 2: Check Import Status **Endpoints:** * `GET /api/v1/misc/google-business/reviews/import?teamId=team_123` * `GET /api/v1/misc/google-business/reviews/import/:importId` The list endpoint returns up to 20 latest imports for that team/location, newest first. ### Statuses * `PENDING`: Waiting in queue. * `FETCHING_REVIEWS`: Import is running. * `COMPLETED`: Finished. * `FAILED`: Import failed after retries. * `RATE_LIMITED`: Temporarily paused due to API/rate pressure; resumes automatically after `rateLimitResetAt`. Example import object: ```json theme={null} { "id": "imp_abc123", "teamId": "team_123", "socialAccountId": "sa_123", "requestedCount": 50, "status": "FETCHING_REVIEWS", "reviewsImported": 24, "error": null, "rateLimitResetAt": null, "startedAt": "2026-02-17T10:00:00.000Z", "completedAt": null, "createdAt": "2026-02-17T09:59:55.000Z", "updatedAt": "2026-02-17T10:00:08.000Z", "deletedAt": null } ``` *** ## Step 3: Fetch Imported Reviews **Endpoints:** * `GET /api/v1/misc/google-business/reviews?teamId=team_123&limit=50&offset=0` * `GET /api/v1/misc/google-business/reviews/:reviewId?teamId=team_123` ### Query Parameters (`GET /reviews`) | Parameter | Type | Default | Description | | :- | :- | :- | :- | | `teamId` | string | required | Team ID | | `limit` | number | `50` | Page size (`1-1000`) | | `offset` | number | `0` | Pagination offset | Example response: ```json theme={null} { "reviews": [ { "id": "rev_123", "socialAccountId": "sa_123", "teamId": "team_123", "externalReviewId": "accounts/123/locations/456/reviews/789", "reviewerDisplayName": "Jane Doe", "reviewerProfilePhotoUrl": "https://lh3.googleusercontent.com/...", "starRating": "FIVE", "comment": "Amazing service, will come back!", "reviewReplyComment": "Thanks a lot for your feedback!", "reviewReplyUpdatedAt": "2026-02-17T12:15:00.000Z", "createTime": "2026-02-16T18:22:00.000Z", "updateTime": "2026-02-17T12:15:00.000Z", "importedAt": "2026-02-17T12:15:02.000Z", "createdAt": "2026-02-17T12:15:02.000Z", "updatedAt": "2026-02-17T12:15:02.000Z", "deletedAt": null } ], "total": 1, "limit": 200, "remainingCapacity": 176 } ``` `starRating` values: `ONE`, `TWO`, `THREE`, `FOUR`, `FIVE`. `limit` in this response is your monthly import cap for that social account (not the page size). *** ## Step 4: Reply to Reviews ### Create or Update Reply **Endpoint:** `PUT /api/v1/misc/google-business/reviews/:reviewId/reply` ```json theme={null} { "teamId": "team_123", "comment": "Thank you for visiting us!" } ``` `comment` length: `1-4096` chars. ### Delete Reply **Endpoint:** `DELETE /api/v1/misc/google-business/reviews/:reviewId/reply` ```json theme={null} { "teamId": "team_123" } ``` Both endpoints return the updated review object. ### Reply Moderation State Google moderates replies, and its reply response doesn't include the result. So right after you reply, `reviewReplyState` and `reviewReplyPolicyViolation` are `null`. We then ask Google for the state of replies from the last 30 days that are still `null`, `PENDING` or `UNSPECIFIED`: on every run during the first day, about every 3 hours until day 7, then daily. `reviewReplyStateCheckedAt` is when we last asked. Replying again or deleting the reply resets it, so the new reply is checked on the next run. *** ## Quirks & Gotchas ### Incremental Sync (No Duplicate Spam) Re-running imports is safe. Reviews are upserted by external review ID, so existing reviews are updated instead of duplicated. To get a location's full history, run imports until `reviewsImported` comes back lower than `count` (Google has nothing older). Once you have every review, later imports only fetch what's new since the last one. ### Overlap Window for Edits Imports intentionally overlap recent data to catch delayed edits/reply updates from Google. So yes, some recently imported reviews may be re-processed. They're refreshed for free and don't count toward `count` or the monthly limit. ### Temporary `RATE_LIMITED` Is Normal When Google slows things down, imports switch to `RATE_LIMITED` and auto-resume. No manual retry endpoint needed for this path. ### Capacity Is Per Social Account `remainingCapacity` is calculated per connected Google Business social account, not globally across all accounts. # Google Business Service list Source: https://info.bundle.social/api-reference/platforms/google-business-service-list Read and update the structured list of services for eligible Google Business Profile locations. The **service list** is a structured set of services with optional pricing that appears on eligible profiles (Google enables this per **category** and account capabilities). If the location cannot use service lists, the API returns a clear client error instead of empty data. Not every business category supports service list editing, and allowed service object shapes can vary by location setup. **Base path:** `/api/v1/misc/google-business` *** ## Get service list **Endpoint:** `GET /api/v1/misc/google-business/location/service-list` | Query | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team with connected Google Business location. | Response follows Google's shape: typically `name` for the resource and `serviceItems` as an array of service objects (structure depends on Google's API version). *** ## Update service list **Endpoint:** `PATCH /api/v1/misc/google-business/location/service-list` | Field | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team identifier. | | `fields` | Yes | Must include `serviceItems` in the **update payload** (this is the only allowed value today). Same comma or repeated list style as elsewhere. | | `serviceItems` | Optional | Array of service objects. Use the same structure Google returns from GET, with fields you want to set or replace per Google's rules. | The location must allow edits to the service list (`canModifyServiceList` in Google's metadata). Otherwise you receive a validation error explaining that the feature is not available for that location. Best practice: read the current list first and patch from those objects instead of constructing service items from scratch. If your UI allows service editing, fetch `metadata` from `GET /location` and gate editing by `metadata.canModifyServiceList`. ### Example The exact shape of `serviceItems` depends on Google's API. The most reliable approach is to **GET** the current list, edit objects in your application, then **PATCH** the array back. ```json theme={null} { "teamId": "00000000-0000-4000-8000-000000000001", "fields": ["serviceItems"], "serviceItems": [ { "freeFormServiceItem": { "category": "categories/gcid:example_category", "label": { "displayName": "Standard consultation", "description": "Initial appointment" } } } ] } ``` > [!NOTE] > > Category and service identifiers must be valid for your business type. Prefer copying working objects from **GET** and changing only the fields you need. *** ## Related * [Food menus](/api-reference/platforms/google-business-food-menus) for restaurant menu content. # Platforms Overview Source: https://info.bundle.social/api-reference/platforms/index Everything you need to know about the platforms we support. The good, the bad, and the API limits. ## Supported Platforms We support a wide range of social platforms. Our goal is to unify them into a single API, but let's be real. Under the hood, they are all uniquely chaotic. Here is the current roster: > [card] [Instagram](/api-reference/platforms/instagram) > > Stories, Reels, and Posts. Strict aspect ratios included. > [card] [Facebook](/api-reference/platforms/facebook) > > Pages and Reels. Watch out for token expiry. > [card] [LinkedIn](/api-reference/platforms/linkedin) > > Personal Profiles vs. Company Pages. > [card] [TikTok](/api-reference/platforms/tiktok) > > Short-form video king. Copyright music is tricky. > [card] [YouTube](/api-reference/platforms/youtube) > > Long-form and Shorts. "Made for Kids" flags are mandatory. > [card] [Snapchat](/api-reference/platforms/snapchat) > > Public Stories, Spotlights, and content analytics. > [card] [Twitter/X](/api-reference/platforms/twitter) > > It's X now. Analytics are... complicated. > [card] [Threads](/api-reference/platforms/threads) > > Meta's text app. Surprisingly decent API. > [card] [Pinterest](/api-reference/platforms/pinterest) > > Pins and Boards. > [card] [Reddit](/api-reference/platforms/reddit) > > The front page of the internet. Limited analytics. > [card] [Mastodon](/api-reference/platforms/mastodon) > > Decentralized. > [card] [Bluesky](/api-reference/platforms/bluesky) > > The new challenger. > [card] [Discord](/api-reference/platforms/discord) > > Webhooks and channels. Great for community updates. > [card] [Slack](/api-reference/platforms/slack) > > Workspace messaging. Automate internal comms. > [card] [Google Business](/api-reference/platforms/google-business) > > Local SEO posts. Events, offers, and updates. ## The "Unified" API Myth We do our best to abstract away the differences, but sometimes a platform is just... special. * **Aspect Ratios:** Instagram will reject your Reel if it's not 9:16. We can't fix that for you. * **Rate Limits:** We handle queuing, but if you blast 100 posts in a second, things will slow down. * **Analytics:** Some platforms give us everything (TikTok), others give us crumbs (Reddit). We return `0` when data isn't available, rather than making numbers up. Dive into each platform's guide to see the specific quirks, gotchas, and limitations. We've documented them so you don't have to discover them at 3 AM. # Instagram Source: https://info.bundle.social/api-reference/platforms/instagram Reels, Stories, Posts, and the strict laws of aspect ratios. Feed posts must sit between 4:5 and 1.91:1 or Instagram rejects them without mercy. Instagram is visually demanding. The API reflects that. If you don't follow their rules on aspect ratios and media types, they will reject your content without mercy. ## Supported Content Types * **Posts:** Single image, single video, or carousel (mixed images + videos). 1-10 files. * **Reels:** Video only. Must be vertical. * **Stories:** Image or video. Expire after 24 hours. Gone like your motivation on Monday morning. ## Quirks & Gotchas ### Aspect Ratios are Law Instagram is very strict here. * **Stories/Reels:** Must be **9:16** (vertical). Technically the API accepts wider ratios, but they'll look terrible. * **Feed Posts:** **4:5** (vertical) or **1:1** (square) for images. Videos are more flexible. > [!WARNING] > > **Don't try to cheat.** If you upload a 16:9 (landscape) video as a Reel, it might technically "work" but it will look terrible (awkwardly cropped) or be rejected entirely. Your marketing team will not be happy. Your users' marketing teams will not be happy. Nobody will be happy. ### What if I have non-standard content? Instagram feed Posts must fall within a specific aspect ratio range (4:5 to 1.91:1). If your users upload wide landscape photos or tall portrait shots that fall outside this range, you have two automatic correction options instead of rejecting the upload outright: | Option | Field | Behavior | | :- | :- | :- | | Fit | `autoFitImage: true` | Adds padding around the image to fit the target ratio. No pixels are lost. The same way Instagram does this natively. | | Crop | `autoCropImage: true` | Center-crops the image to fit the target ratio. No padding, but edges are cut. | > [!WARNING] > > These two options are mutually exclusive. Sending both as `true` will fail validation. They only apply to `type: "POST"` and have no effect on Reels or Stories. ### Stories vs. Reels vs. Posts * **Stories** are ephemeral. They disappear after 24 hours. Great for FOMO content. * **Reels** are for growth. They're public, discoverable, and the algorithm loves them. * **Posts** are for the feed grid. The permanent collection. ### Media Limits See [Platform Limits](/api-reference/limits#instagram) for the full breakdown of file sizes, resolutions, and aspect ratios. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 2,000 characters | | `collaborators` | Max 3 usernames, each max 30 chars | | `tagged` | Max 20 users per media, username max 30 chars | | `carouselItems` | Max 10 items | | `locationId` | Max 64 characters | | `altText` | Optional. Accessibility description for **image** posts (feed, carousel images, etc.). | > [!NOTE] > > **Alt text** is supported on image posts. Use it when you need screen-reader-friendly descriptions beyond the caption in `text`. *** ## Post Options Send Instagram-specific options inside `data.INSTAGRAM`. | Field | Type | Description | | :- | :- | :- | | `type` | `enum` | `POST`, `REEL`, or `STORY`. Default: `POST`. | | `text` | `string` | Caption. Max 2,000 characters. | | `uploadIds` | `string[]` | Uploaded media IDs. Posts support 1-10 files, Reels and Stories require 1 file. | | `altText` | `string` | Accessibility text for a single image post. | | `thumbnailOffset` | `number` | Video cover frame offset in milliseconds. | | `thumbnail` | `string` | Optional thumbnail image URL uploaded through bundle.social. | | `shareToFeed` | `boolean` | Reels only. Controls whether the Reel can also appear in the feed. | | `collaborators` | `string[]` | Up to 3 usernames. Not supported for Stories. | | `autoFitImage` | `boolean` | Feed posts only. Adds padding to fit Instagram aspect ratio requirements. | | `autoCropImage` | `boolean` | Feed posts only. Crops to fit Instagram aspect ratio requirements. | | `tagged` | `array` | Person tags. Images need `x`/`y`; Reels use usernames only. | | `carouselItems` | `array` | Per-item metadata for carousel posts, including `uploadId`, `altText`, and image tags. | | `locationId` | `string` | Facebook Page/location ID to tag on posts or Reels. Not supported for Stories. | | `trialParams` | `object` | Trial Reels settings. Reels only. | | `musicSoundInfo` | `object` | Instagram audio settings for Reels. Requires Instagram connected via Facebook Login. | ```json theme={null} { "teamId": "team_123", "title": "Instagram Reel launch", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["INSTAGRAM"], "data": { "INSTAGRAM": { "type": "REEL", "text": "Launching today", "uploadIds": ["upload_video_123"], "shareToFeed": true, "thumbnailOffset": 1500, "collaborators": ["creator_one"], "locationId": "1234567890", "musicSoundInfo": { "musicSoundId": "ig_audio_123", "musicSoundVolume": 80, "videoOriginalSoundVolume": 20 } } } } ``` > [!WARNING] > > `autoFitImage` and `autoCropImage` are mutually exclusive. `musicSoundInfo` works only for `type: "REEL"` and only when the Instagram account is connected through Facebook Login. ### Instagram Misc Endpoints Instagram audio search for Reels is documented separately: [Instagram Music Library](/api-reference/platforms/instagram-music). #### `GET /misc/instagram/tags` * Purpose: business discovery by username (public profile data for discoverable business/creator accounts). * The response can include up to 12 recent public media items with media type, likes, comments, timestamp, and caption when Meta returns them. * Important: works only when the Instagram account is connected via `FACEBOOK` login flow. * If the account is connected via direct `INSTAGRAM` method, API returns explicit `400` with reconnection guidance. * Private accounts and some non-business/non-creator accounts may not be discoverable and can return `exists: false`. * In our tests, business discovery can sometimes return `false` for accounts that are still valid for publishing tags. In other words: lookup may fail, while tagging that same username in publish payload can still work. #### `GET /misc/instagram/locations` * Purpose: search Facebook Pages with physical location data and return IDs for `data.INSTAGRAM.locationId`. * Important: works only for Instagram accounts connected via `FACEBOOK` method. * Uses the account page token (`socialAccount.accessToken`). * Missing page permissions/features (for example `pages_read_engagement`) return explicit `400` with actionable message. > [!NOTE] > > Meta location search can be inconsistent. If you hit the permission/error path, there is usually nothing we can reliably fix from API side right now (this behavior is widely reported in Meta developer threads). The good news: `locationId` tagging itself still works when you already have a valid location/page ID, so known IDs found externally can still be used in publish payloads. We hope this endpoint becomes stable for all accounts over time. ### Publishing Payload & Validation Rules #### `locationId` mapping * `data.INSTAGRAM.locationId` is mapped to `location_id` in Instagram publish payload. * Supported in single image, reel/single-video flow, and carousel parent container. #### `shareToFeed` * Accepted only for reel-like payloads: * `type = REEL`, or * `type = POST` with exactly one video upload. * Rejected for image posts, carousels, and stories (`400`). #### Person tags (`tagged`) * Reel/single-video: provide usernames only (no `x`/`y` coordinates). * Single image: each tagged user must include `x` and `y` in range `0-1`. * Carousel: top-level `tagged` is rejected; use `carouselItems[].tagged` per item. * Carousel video item: person tags are not supported and are rejected. #### Carousel item binding * `carouselItems` is allowed only for real carousel posts (at least 2 uploads). * Every `carouselItems[].uploadId` must exist in provided `uploadIds`. * Use each `uploadId` only once in `carouselItems`. ```json theme={null} { "socialAccountTypes": ["INSTAGRAM"], "data": { "INSTAGRAM": { "type": "POST", "text": "Carousel with per-item tags", "uploadIds": ["upl_img_1", "upl_img_2", "upl_vid_1"], "carouselItems": [ { "uploadId": "upl_img_1", "tagged": [{ "username": "alice", "x": 0.25, "y": 0.4 }] }, { "uploadId": "upl_img_2", "tagged": [{ "username": "bob", "x": 0.6, "y": 0.35 }] }, { "uploadId": "upl_vid_1" } ] } } } ``` #### Story constraints * Stories do not support `collaborators`. * Stories do not support `locationId`. #### Collaborators behavior * Collaborators are normalized before publish (`@` stripped, trim, lowercase). * If Instagram rejects a tagged user or collaborator (private profile, invalid username, or an account that can't be tagged), we publish the post without them instead of failing it. The same goes for a `locationId` Instagram rejects (for example when the Facebook Page behind it was removed or unpublished). * The post ends as `POSTED`, the dropped parts are listed in `externalData.INSTAGRAM.skippedTags` and `externalData.INSTAGRAM.skippedLocationId`, and `errors.INSTAGRAM` carries a warning such as `Posted without the Instagram tag(s) @handle: Instagram rejected them (private profile, invalid username, or the account cannot be tagged).` or `Posted without the location (ID 123): Instagram rejected it (the Facebook Page behind it may be removed or unpublished).` * On a `POSTED` post, read `errors.INSTAGRAM` as a warning. #### Trial Reels Trial reels are shared only with non-followers first. If the content performs well, it can be graduated to a regular reel that appears to everyone. Send `data.INSTAGRAM.trialParams.graduationStrategy` in the publish payload: | Value | Behavior | | :- | :- | | `MANUAL` | The trial reel stays in trial until you manually graduate it from the native Instagram app. | | `SS_PERFORMANCE` | Instagram automatically graduates the reel if it meets a performance threshold. | Requirements and caveats: * Only valid for `type: "REEL"`. Ignored for Posts and Stories. * Requires a public professional (Creator or Business) account with at least around 1,000 followers. Instagram has not published an official threshold and some users report access starting at 200 followers. * Not all professional accounts will have access to this feature regardless of follower count. ```json theme={null} { "socialAccountTypes": ["INSTAGRAM"], "data": { "INSTAGRAM": { "type": "REEL", "text": "Testing this reel with non-followers first", "uploadIds": ["upl_vid_1"], "trialParams": { "graduationStrategy": "SS_PERFORMANCE" } } } } ``` *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). ### Refresh Rate & Limits * **Default Refresh:** Every 24 hours. * **Force Refresh:** Available (max 6 per account and 6 per post in any 24 hours). * **Data Retention:** 30 days. [Details](/api-reference/data-retention). ### Profile Analytics **Period:** Rolling window (30 days). | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total times profile content was shown | | | `impressionsUnique` | Unique accounts that saw content | Called "Reach" by Instagram | | `views` | Profile views | | | `viewsUnique` | - | Returns `0` (not provided by API) | | `likes` | Total likes | | | `comments` | Total comments | | | `postCount` | Total posts published | | | `followers` | Total followers | | | `following` | Total following | | ### Post Analytics **Period:** Lifetime (Snapshot). | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total views | Called "views" in Instagram API | | `impressionsUnique` | Unique accounts reached | Called "reach" in Instagram API | | `views` | Video plays | Videos/Reels only | | `viewsUnique` | - | Returns `0` (not provided by API) | | `likes` | Total likes | | | `comments` | Total comments | | | `shares` | Total shares | Reels only | | `saves` | Total saves | | ### Raw Analytics - Demographics & Audience Data Instagram provides detailed demographic data via raw analytics. Here's what the raw payload looks like when enabled for your organization: ```json theme={null} { "profileInfo": { /* basic account info */ }, "totals30d": [ /* 30-day daily breakdown */ ], "demographics": { "follows_and_unfollows": { "data": [{ "name": "follows_and_unfollows", "period": "day", "title": "Follows and unfollows", "total_value": { "breakdowns": [{ "dimension_keys": ["follow_type"], "results": [ { "dimension_values": ["FOLLOWER"], "value": 142 }, { "dimension_values": ["NON_FOLLOWER"], "value": 23 } ] }] } }] }, "follows_and_unfollows_by_follow_type": { "follows": 142, "unfollows": 23, "unknown": 0 }, "follower_demographics": { "country": { "data": [{ "name": "follower_demographics", "total_value": { "breakdowns": [{ "dimension_keys": ["country"], "results": [ { "dimension_values": ["US"], "value": 4521 }, { "dimension_values": ["GB"], "value": 1893 }, { "dimension_values": ["DE"], "value": 1247 } ] }] } }] }, "city": { "data": [{ "name": "follower_demographics", "total_value": { "breakdowns": [{ "dimension_keys": ["city"], "results": [ { "dimension_values": ["New York, New York"], "value": 892 }, { "dimension_values": ["London, England"], "value": 654 } ] }] } }] }, "gender": { "data": [{ "name": "follower_demographics", "total_value": { "breakdowns": [{ "dimension_keys": ["gender"], "results": [ { "dimension_values": ["M"], "value": 5234 }, { "dimension_values": ["F"], "value": 4891 }, { "dimension_values": ["U"], "value": 312 } ] }] } }] }, "age": { "data": [{ "name": "follower_demographics", "total_value": { "breakdowns": [{ "dimension_keys": ["age"], "results": [ { "dimension_values": ["18-24"], "value": 3421 }, { "dimension_values": ["25-34"], "value": 4102 }, { "dimension_values": ["35-44"], "value": 1893 }, { "dimension_values": ["45-54"], "value": 721 } ] }] } }] } }, "engaged_audience_demographics": { "country": { /* same structure as follower_demographics */ }, "city": { /* same structure */ }, "gender": { /* same structure */ }, "age": { /* same structure */ } }, "follower_demographics_age_gender": { "data": [{ "name": "follower_demographics", "total_value": { "breakdowns": [{ "dimension_keys": ["age", "gender"], "results": [ { "dimension_values": ["18-24", "F"], "value": 1820 }, { "dimension_values": ["18-24", "M"], "value": 1534 }, { "dimension_values": ["25-34", "F"], "value": 2011 } ] }] } }] } }, "onlineFollowers": { "data": [{ "name": "online_followers", "period": "lifetime", "values": [ { "value": { "0": 312, "1": 280, "...": 0, "23": 401 }, "end_time": "2026-10-07T07:00:00+0000" } ] }] } } ``` * `demographics.follows_and_unfollows` is requested with `breakdown=follow_type` over the last 30 days (Instagram returns nothing without it). `demographics.follows_and_unfollows_by_follow_type` is the same data already parsed: `follows` (`FOLLOWER`), `unfollows` (`NON_FOLLOWER`, includes accounts that left Instagram) and `unknown` (any other type). Instagram only returns it for accounts with 100+ followers, so it's `null` for smaller accounts. * `demographics.follower_demographics_age_gender` is the age × gender cross-tab of your followers (one row per age bucket + gender pair). It's `null` if Instagram didn't return it. * `onlineFollowers` shows how many followers were online in each hour (`0`-`23`) for each of the last 30 days. Handy for picking posting times. Instagram only returns it for accounts with 100+ followers, so it's `null` for smaller accounts. * `reachByFollowType` is the account's unique reach over the last 30 days (same window as `totals30d`), split into followers and non-followers. `reachTimeSeries` has reach per day for the same 30 days; summing those days counts the same person once per day they were reached, so it's higher than the 30-day total. > [!NOTE] > > Raw demographics include both **follower demographics** (lifetime, who follows you) and **engaged audience demographics** (this month, who interacts with your content). These are two different audiences and both are useful for understanding your reach. # Instagram Music Library Source: https://info.bundle.social/api-reference/platforms/instagram-music Search Instagram music and original sounds, then attach audio to Reels. Instagram lets Reels use audio assets from its audio API. In bundle.social, you search for an audio asset first, then pass its `audio_id` as `data.INSTAGRAM.musicSoundInfo.musicSoundId` when creating a Reel. > [!WARNING] > > Instagram audio search and Reel audio publishing require the Instagram account to be connected through **Facebook Login**. Direct Instagram OAuth (`instagramConnectionMethod: "INSTAGRAM"`) cannot use this feature. ## The Endpoint **`GET /api/v1/misc/instagram/audio`** Searches Instagram music or original sounds that can be attached to Reels. ### Query Parameters | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `teamId` | `string` | Yes | Team with the connected Instagram account. | | `audioType` | `enum` | Yes | `music` or `original_sound`. | | `searchQuery` | `string` | No | Optional keyword search, max 100 characters. | ```http theme={null} GET /api/v1/misc/instagram/audio?teamId=team_123&audioType=music&searchQuery=lofi ``` ## Response Shape ```json theme={null} { "audio": [ { "audio_id": "17900000000000000", "audio_type": "music", "title": "Late Night Drive", "display_artist": "Example Artist", "duration_in_ms": 30000, "cover_artwork_thumbnail_url": "https://...", "download_url": "https://..." }, { "audio_id": "17800000000000000", "audio_type": "original_sound", "title": "Original audio", "ig_username": "creator", "profile_picture_url": "https://..." } ] } ``` Important fields: | Field | Meaning | | :- | :- | | `audio_id` | The ID you pass as `musicSoundId` in the post payload. | | `audio_type` | `music` or `original_sound`. | | `title` | Track or sound title when Instagram provides it. | | `display_artist` | Artist name for music assets. | | `duration_in_ms` | Audio duration in milliseconds when available. | | `download_url` | Preview/download URL when Instagram provides it. | | `ig_username` | Creator username for original sounds when available. | ## Using Audio In Reels Use the `audio_id` from the search response as `data.INSTAGRAM.musicSoundInfo.musicSoundId`. ```json theme={null} { "teamId": "team_123", "title": "Reel with Instagram audio", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["INSTAGRAM"], "data": { "INSTAGRAM": { "type": "REEL", "text": "New Reel", "uploadIds": ["upload_video_123"], "musicSoundInfo": { "musicSoundId": "17900000000000000", "musicSoundVolume": 80, "videoOriginalSoundVolume": 20 } } } } ``` ### Audio Fields | Field | Type | Description | | :- | :- | :- | | `musicSoundId` | `string` | Required when using Instagram audio. Use `audio_id` from the search endpoint. | | `musicSoundVolume` | `number` | Optional. Audio volume from `0` to `100`. Defaults to `100`. | | `videoOriginalSoundVolume` | `number` | Optional. Original video volume from `0` to `100`. Defaults to `100`. | ## Rules * Works only for `data.INSTAGRAM.type: "REEL"`. * Does not work for feed posts, carousels, or Stories. * Requires Instagram connected via Facebook Login. * Direct Instagram OAuth returns a clear `400` error for audio search. * If you pass `musicSoundInfo` for a non-Reel post, validation fails before publishing. ## Quick Reference | Task | What to use | | :- | :- | | Search music | `GET /api/v1/misc/instagram/audio?teamId=...&audioType=music` | | Search original sounds | `GET /api/v1/misc/instagram/audio?teamId=...&audioType=original_sound` | | Search by keyword | Add `searchQuery=...` | | ID for post | `audio_id` from the search response | | Post field | `data.INSTAGRAM.musicSoundInfo.musicSoundId` | Need the full request/response schema? Check [Swagger](https://api.bundle.social/swagger). The endpoint is under misc/instagram. # LinkedIn Source: https://info.bundle.social/api-reference/platforms/linkedin The professional network. Where URNs are king and Personal profiles have limited superpowers. LinkedIn is unique because it strictly separates **Personal Profiles** (Members) from **Organization Pages** (Companies). The API treats them very differently, and this affects analytics significantly. ## Quirks & Gotchas ### Personal vs. Organization This is the biggest source of confusion. * **Personal Profile (Member):** Limited API. **Cannot import post history.** Limited analytics. No profile views data. * **Organization (Company Page):** Full API power. Richer analytics. Supports historical import. Has page view data. ### Article / Link Preview When you send a post with `data.LINKEDIN.link` and no media uploads, bundle.social fetches the URL, scrapes its Open Graph metadata, and builds a LinkedIn article content block with a title, description, and preview image automatically. * `link` is the URL to preview, max 2048 characters. > [!NOTE] > > This is the correct way to build link posts on LinkedIn. A `link` can't be combined with media uploads: such a post is rejected with `400` and `LinkedIn link preview posts cannot include media uploads.` ### Polls Send `data.LINKEDIN.poll` to publish a LinkedIn poll. The post `text` is shown above the poll. | Field | Limit | | :- | :- | | `poll.question` | Required, 1-140 characters | | `poll.options` | 2-4 options, 1-30 characters each | | `poll.duration` | `ONE_DAY`, `THREE_DAYS` (default), `SEVEN_DAYS` or `FOURTEEN_DAYS` | ```json theme={null} { "LINKEDIN": { "text": "Help us pick the next webinar topic", "poll": { "question": "What should we cover next?", "options": ["Analytics", "Automations", "Scheduling"], "duration": "SEVEN_DAYS" } } } ``` * A poll can't have media or a `link`. Such a post is rejected with `400` (`A LinkedIn poll cannot be combined with media.` / `...with a link preview.`). * Validation errors point at the exact field, for example `data.LINKEDIN.poll.options.2` with `Max 30 characters per poll option`. * LinkedIn doesn't let you edit a poll after it's published. * Poll results (votes per option) aren't available in analytics. ### The URN Nightmare LinkedIn uses "URNs" (Uniform Resource Names) to identify everything. * Organization: `urn:li:organization:12345` * Person: `urn:li:person:abcde` If you are constructing raw text mentions, you need to use this format. Our API handles basic text automatically, but if you're getting fancy, keep this in mind. ### Media Limits Video max size is **2 GB** (not 200 MB - that was an old API limitation). Documents must be PDF format, max 100 MB. **GIFs** are supported-upload animated GIFs like other image media for LinkedIn posts. See [Platform Limits](/api-reference/limits#linkedin) for the full breakdown. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 3,000 characters | | `mediaTitle` | Max 200 characters | *** ## Post Options | Field | Type | Description | | :- | :- | :- | | `text` | `string` | Post text. Max 3,000 characters. A post needs text, media, a link or a poll. | | `uploadIds` | `string[]` | Images, one video, one PDF document, or GIF media. Media types cannot be freely mixed. | | `link` | `string` | Optional URL for LinkedIn article preview posts. Can't be combined with media uploads or a poll. | | `poll` | `object` | `{ question, options, duration }`. See [Polls](#polls). Can't be combined with media or a link. | | `thumbnail` | `string` | URL to an uploaded thumbnail image. | | `mediaTitle` | `string` | Title for video or document posts. Max 200 characters. | | `privacy` | `CONNECTIONS` \| `PUBLIC` \| `LOGGED_IN` \| `CONTAINER` | Visibility setting. | | `hideFromFeed` | `boolean` | Hide from the main feed where LinkedIn supports it. | | `disableReshare` | `boolean` | Disable resharing where LinkedIn supports it. | ```json theme={null} { "teamId": "team_123", "title": "LinkedIn reporting update", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["LINKEDIN"], "data": { "LINKEDIN": { "text": "We shipped a new reporting workflow", "privacy": "PUBLIC", "link": "https://example.com/reporting" } } } ``` *** ## Mentions And Published Post Actions ### Resolve Mentionable People And Organizations **Endpoint:** `GET /api/v1/misc/linkedin/mentions/tags` Provide `teamId` and either a search query (`q`) or LinkedIn profile/company `url`. `scope` can be `people`, `organizations`, or `all`. ```http theme={null} GET /api/v1/misc/linkedin/mentions/tags?teamId=team_123&url=https://www.linkedin.com/in/jane-doe&displayName=Jane%20Doe&scope=people ``` Person mention lookup is available when the selected LinkedIn channel is an organization. URL lookup accepts `linkedin.com/in/...` for people and `linkedin.com/company/...` for organizations. `displayName` is optional and controls the text shown for a person resolved by URL. Use `POST /api/v1/misc/linkedin/mentions/builder` to combine returned URNs with text: ```json theme={null} { "text": "Thanks Jane Doe for the launch support", "tags": [ { "display": "Jane Doe", "urn": "urn:li:person:abc123" } ] } ``` ### Reshare A LinkedIn Post **Endpoint:** `POST /api/v1/misc/linkedin/post/reshare` ```json theme={null} { "teamId": "team_123", "parentPostUrn": "urn:li:share:123456789", "commentary": "Worth sharing with our network.", "visibility": "PUBLIC", "disableReshare": false } ``` `commentary` is required and limited to 3,000 characters. The response includes the new LinkedIn ID, activity URN, and permalink when LinkedIn returns them. ### Edit Or Delete Published Content | Operation | Endpoint | Main fields | | :- | :- | :- | | Edit post text | `PATCH /api/v1/misc/linkedin/post` | `teamId`, bundle.social `postId`, `description` | | Delete post | `DELETE /api/v1/misc/linkedin/post` | `teamId`, bundle.social `postId` | | Edit comment | `PATCH /api/v1/misc/linkedin/comment` | `teamId`, bundle.social `commentId`, `text` | | Delete comment | `DELETE /api/v1/misc/linkedin/comment` | `teamId`, bundle.social `commentId` | These operations act on content already published to LinkedIn. They do not change the original scheduled payload stored in bundle.social. *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). ### Profile Analytics #### Personal (Member) **Period:** Rolling window (30 days). | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total content views | | | `impressionsUnique` | Unique content views | | | `views` | - | Returns `0` (LinkedIn doesn't provide views for personal accounts) | | `viewsUnique` | - | Returns `0` | | `likes` | Total likes | | | `comments` | Total comments | | | `postCount` | - | Returns `0` (not provided by LinkedIn API) | | `followers` | Connections/Followers | | | `following` | - | Returns `0` (not provided by LinkedIn API) | #### Organization (Company) **Period:** Rolling window (30 days). | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total content views | | | `impressionsUnique` | Unique content views | | | `views` | **Page Views** | Available for Orgs only! | | `viewsUnique` | Unique page views | | | `likes` | Total likes | | | `comments` | Total comments | | | `postCount` | - | Returns `0` (not provided by LinkedIn API) | | `followers` | Followers | | | `following` | - | Returns `0` (not provided by LinkedIn API) | ### Post Analytics #### Personal Posts **Period:** Rolling window (30 days). | Metric | Description | Note | | :- | :- | :- | | `impressions` | View count | | | `impressionsUnique` | Unique view count | | | `views` | Video views | Video posts only | | `viewsUnique` | Unique video views | Video posts only | | `likes` | Reactions | | | `comments` | Comments | | | `shares` | Reposts | | | `saves` | Saves | If LinkedIn refuses it on a refresh, the last stored value is kept | #### Organization Posts **Period:** Rolling window (30 days). > [!WARNING] > > **Only recent posts.** Organization analytics only cover posts published within the last 30 days. Posts authored by members (not the organization/brand itself) are excluded from organization analytics. | Metric | Description | Note | | :- | :- | :- | | `impressions` | View count | | | `impressionsUnique` | Unique view count | | | `views` | Video views (LinkedIn counts plays of at least 3 seconds) | Video posts only, `0` for other posts | | `viewsUnique` | Unique video viewers | Video posts only, `0` for other posts | | `likes` | Reactions | | | `comments` | Comments | | | `shares` | Reposts | | | `saves` | - | Returns `0` (not provided by LinkedIn API) | ### Raw Analytics Raw analytics for LinkedIn retain **reaction** breakdowns from the platform (per reaction type) where available. Our standard post schema still exposes a single aggregated likes/reactions-style metric; use raw data when you need the full split. **Personal (member) posts** also get, in `metrics`: `clicks` (link clicks), `sends`, `followersGained` and `profileViews`. A metric LinkedIn refuses for a post is listed in `metrics.unavailableMetrics`; the others are still stored. **Account snapshots** carry `daily`, a day-by-day series for the last 364 complete UTC days, read with `GET /api/v1/analytics/social-account/raw`: * Personal profiles: `impressions`, `reactions`, `comments`, `reshares`, `saves`, `sends` and `followerGains`. * Pages: `impressions`, `uniqueImpressions`, `clicks`, `likes`, `comments`, `shares`, `organicFollowerGains` and `paidFollowerGains`. A series LinkedIn didn't answer is listed in `daily.unavailable`, and `daily` is `null` if none came back. LinkedIn keeps 12 months, so for a longer history keep older snapshots. The daily reactions, comments and reshares of a personal profile can differ from what LinkedIn shows (LinkedIn documents them as not consistent with its UI), and the newest day or two of Page follower gains read `0` because LinkedIn reports them two days late. **Organization video posts** also get: * `videoAnalytics` with LinkedIn's `VIDEO_VIEW`, `VIEWER` and `TIME_WATCHED_FOR_VIDEO_VIEWS` elements exactly as LinkedIn returns them (lifetime totals; watch time in milliseconds). A type is `null` when LinkedIn didn't answer for it. * In `metrics`: `isVideo` (on every organization post), `videoWatchTimeSeconds` and `videoAvgWatchTimeSeconds` (in seconds), and `viewsSource` / `viewsUniqueSource`, which say where the numbers came from: `videoAnalytics` (read now), `carriedForward` (LinkedIn didn't answer, the last stored value is kept), `unavailable` or `unsupportedUrn`. * Video views are read for posts with a `urn:li:ugcPost:` ID. Older video posts with a `urn:li:share:` ID get `0`. #### Post Raw Example ```json theme={null} { "shareStatistics": { "impressionCount": 23800, "uniqueImpressionsCount": 17120, "clickCount": 640, "likeCount": 312, "commentCount": 28, "shareCount": 17, "engagement": 997 }, "interactions": { "reactions": [ { "reactionType": "LIKE", "actor": "urn:li:person:abc123", "actorDisplayName": "Jane Doe" }, { "reactionType": "PRAISE", "actor": "urn:li:organization:12345", "actorDisplayName": "Example Company" } ] }, "availability": { "reactions": { "available": true } } } ``` #### Page (Organization) Raw: Follower Demographics Profile raw analytics for a LinkedIn Page include `followerStatistics`, the Page's lifetime follower breakdowns as LinkedIn returns them: ```json theme={null} { "scope": "organization", "followerStatistics": { "followerCountsByGeoCountry": [ { "geo": "urn:li:geo:103644278", "followerCounts": { "organicFollowerCount": 1840, "paidFollowerCount": 12 } } ], "followerCountsByIndustry": [ { "industry": "urn:li:industry:4", "followerCounts": { "organicFollowerCount": 920, "paidFollowerCount": 3 } } ], "followerCountsBySeniority": [ /* "seniority": "urn:li:seniority:3", ... */ ], "followerCountsByFunction": [ /* "function": "urn:li:function:8", ... */ ], "followerCountsByStaffCountRange": [ /* "staffCountRange": "SIZE_11_TO_50", ... */ ], "followerCountsByGeo": [ /* regions, same shape as by country */ ] } } ``` * Each breakdown is limited to the top 100 entries. * Values are LinkedIn URNs (geo, industry, seniority, function). Resolve them to names with LinkedIn's standardized data, or map them on your side. * LinkedIn doesn't expose follower **age or gender** to apps, so those aren't available. * Only Pages have follower demographics. Personal profiles don't, and `followerStatistics` is `null` if LinkedIn doesn't return it. ### Quirks * **Personal accounts** do NOT have views analytics for profiles - only organizations get page views. * **Organization accounts** have page views for profile analytics. For individual posts, views exist only on video posts (video views); other posts return `0`. * Post count and following count are not provided through the LinkedIn API for either account type. * A personal profile's headline is stored in the social account's `bio`, refreshed when you select the profile, refresh channels and on every daily analytics run. * Organization post analytics only include posts from the last 30 days. # Mastodon Source: https://info.bundle.social/api-reference/platforms/mastodon The decentralized social web. Basic metrics only, but at least it's open source. Mastodon is part of the Fediverse. It's decentralized, which means "analytics" is a loose concept. Each instance runs independently, and there's no central authority tracking impressions or views. ## Supported Content Types * **Toots (Posts):** Text with optional media. Up to 4 files. * Mixed images and videos allowed, but only 1 video max. ## Quirks & Gotchas ### Terminology * **Likes** = **Favourites** (British spelling, because Mastodon). * **Shares** = **Reblogs** (like retweets, but federated). * **Posts** = **Toots** (or "statuses" in the API, because naming things is hard). ### Character Limits Character limits are **instance-dependent** - most instances default to 500, but some allow more. We can't know in advance what your user's instance allows. ### Media Limits | Constraint | Value | | :- | :- | | Files | 0-4 (images and/or videos, mixed allowed) | | Max videos | 1 | | Video max size | 99 MB | | Video aspect ratio | 1:3 to 1:1 | | Max images | 4 | | Image max size | 16 MB each | See [Platform Limits](/api-reference/limits#mastodon) for more details. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 30,000 characters | | `spoiler` | Max 50 characters | *** ## Post Options Send Mastodon-specific options inside `data.MASTODON`. | Field | Type | Description | | :- | :- | :- | | `text` | `string` | Status text. Instance limits vary; bundle.social accepts up to 30,000 characters. | | `uploadIds` | `string[]` | Up to 4 uploaded media files. Only 1 video is allowed. | | `thumbnail` | `string` | Optional thumbnail image URL uploaded through bundle.social. | | `privacy` | `enum` | `PUBLIC`, `UNLISTED`, `PRIVATE`, or `DIRECT`. | | `spoiler` | `string` | Content warning text. Max 50 characters. | ```json theme={null} { "teamId": "team_123", "title": "Mastodon update", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["MASTODON"], "data": { "MASTODON": { "text": "Shipping a small but useful update today.", "privacy": "PUBLIC", "spoiler": "Product update" } } } ``` *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). Mastodon has very limited analytics capabilities. Being decentralized means there's no central tracking of impressions or views. ### Profile Analytics **Period:** Snapshot. | Metric | Description | Note | | :- | :- | :- | | `impressions` | - | Returns `0` (not available) | | `impressionsUnique` | - | Returns `0` (not available) | | `views` | - | Returns `0` (not available) | | `viewsUnique` | - | Returns `0` (not available) | | `likes` | - | Returns `0` (not available at profile level) | | `comments` | - | Returns `0` (not available at profile level) | | `postCount` | Total toots | | | `followers` | Followers | | | `following` | Following | | ### Post Analytics **Period:** Lifetime. | Metric | Description | Note | | :- | :- | :- | | `impressions` | - | Returns `0` (not available) | | `impressionsUnique` | - | Returns `0` (not available) | | `views` | - | Returns `0` (not available) | | `viewsUnique` | - | Returns `0` (not available) | | `likes` | Favourites | | | `comments` | Replies | | | `shares` | Reblogs | | | `saves` | - | Returns `0` (not available) | ### Quirks * No impression or view metrics. The Fediverse doesn't track eyeballs the way corporate social media does. * Only basic engagement metrics (favourites, replies, reblogs) are available per post. * Profile-level engagement is not aggregated by Mastodon's API. * This is by design, not a bug. Privacy-focused platform = limited tracking. ### Raw Analytics Mastodon profile raw analytics store the account payload we fetched from the instance. ```json theme={null} { "id": "10987654321", "username": "example", "acct": "example@mastodon.social", "display_name": "Example", "statuses_count": 240, "followers_count": 1800, "following_count": 220 } ``` Mastodon post raw analytics store the status payload. ```json theme={null} { "id": "1122334455", "url": "https://mastodon.social/@example/1122334455", "content": "

Shipping a small update today.

", "replies_count": 12, "reblogs_count": 34, "favourites_count": 91, "created_at": "2026-04-26T10:30:00.000Z" } ``` # Pinterest Source: https://info.bundle.social/api-reference/platforms/pinterest Pins, Boards, and a mixed bag of analytics periods. Every post needs a boardName, and saves matter more than likes on a discovery platform. Pinterest is about discovery, not just a feed. People come here to find ideas and save them for later. The API reflects this - "saves" are the key metric, not likes. ## Supported Content Types * **Pins:** 1 image or 1 video. * **Carousel Pins:** 2 to 5 images in one Pin. See [Carousel Pins](#carousel-pins). ## Quirks & Gotchas ### Board Name is Required You can't pin to thin air. Every Pinterest post needs `boardName`. Use a board from `socialAccount.channels`. ### Terminology * **Likes** are often referred to as **Saves** or **Reactions** depending on context. We normalize them in our schema. * **Video Pins:** Only video pins have true "View" counts. Static image pins just show impressions in the views field. ### Media Limits | Constraint | Value | | :- | :- | | Files | 1 image or video, or 2-5 images for a carousel (required) | | Carousel images | Same aspect ratio, no videos | | Video max size | 2 GB | | Video aspect ratio | 1:2 to 1.91:1 | | Video duration | 4s - 15 min | | Image max size | 5 MB | See [Platform Limits](/api-reference/limits#pinterest) for more details. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 100 characters | | `description` | Max 800 characters | | `link` | Max 2,048 characters | | `altText` | Max 500 characters | | `note` | Max 500 characters | | `boardName` | Required. Use a board name from `socialAccount.channels`. | *** ## Post Options | Field | Type | Description | | :- | :- | :- | | `boardName` | `string` | **Required.** Board name from `socialAccount.channels`. | | `text` | `string` | Pin title. Max 100 characters. | | `description` | `string` | Pin description. Max 800 characters. | | `uploadIds` | `string[]` | One image or video, or 2-5 images for a carousel Pin. The order is the slide order. | | `carouselItems` | `object[]` | Optional per-slide `title`, `description` and `link` for a carousel Pin. See [Carousel Pins](#carousel-pins). | | `thumbnail` | `string` | URL to an uploaded thumbnail image. | | `link` | `string` | Destination URL. Max 2,048 characters. | | `altText` | `string` | Image alt text. Max 500 characters. | | `note` | `string` | Private note. Max 500 characters. | | `dominantColor` | `string` | Hex color used while the image loads. | ```json theme={null} { "teamId": "team_123", "title": "Pinterest spring collection", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["PINTEREST"], "data": { "PINTEREST": { "boardName": "Product ideas", "text": "New spring collection", "description": "A clean, bright look for small teams", "uploadIds": ["upl_img_1"], "link": "https://example.com/spring" } } } ``` ### Carousel Pins Send 2 to 5 image uploads in `uploadIds` and they're published as one carousel Pin, in that order. * All images need the same aspect ratio (we allow 1% for rounding). Otherwise the post is rejected with `400`. * No videos in a carousel, and each upload can appear only once. * Every slide uses the Pin's `text`, `description` and `link` by default. To set them per slide, add `carouselItems`: one entry per slide you want to change, matched by `uploadId`. A missing or empty field falls back to the Pin value. | `carouselItems[]` field | Type | Description | | :- | :- | :- | | `uploadId` | `string` | **Required.** One of the `uploadIds`. | | `title` | `string` | Slide title. Max 100 characters. | | `description` | `string` | Slide description. Max 800 characters. | | `link` | `string` | Slide destination URL. Max 2,048 characters. | ```json theme={null} { "data": { "PINTEREST": { "boardName": "Product ideas", "text": "Spring collection", "description": "Five looks for small teams", "link": "https://example.com/spring", "uploadIds": ["upl_img_1", "upl_img_2", "upl_img_3"], "carouselItems": [ { "uploadId": "upl_img_2", "title": "The desk setup", "link": "https://example.com/spring/desk" } ] } } } ``` `carouselItems` needs at least 2 `uploadIds`. Pinterest downloads every slide while creating the Pin, so a carousel takes longer to publish than a single image. **Post history import:** carousel Pins are imported with the first slide as the thumbnail. With `importCarousels: true`, every slide is added to `extraData.media[]`. See [Import Posts](/api-reference/import-posts). *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). ### Profile Analytics **Period:** Rolling window (30 days). Aggregated across all pin analytics. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total impressions | | | `impressionsUnique` | - | Same as impressions (Pinterest doesn't distinguish) | | `views` | Video views | Defaults to impressions if no video pins | | `viewsUnique` | - | Same as views | | `likes` | Saves | | | `comments` | - | Returns `0` (not provided at profile level) | | `postCount` | Total pins | | | `followers` | Followers | | | `following` | Following | | ### Post Analytics **Period:** Mixed (30-day rolling window for views/impressions, Lifetime for engagement). | Metric | Description | Note | | :- | :- | :- | | `impressions` | Impressions | 30-day window | | `impressionsUnique` | - | Same as impressions | | `views` | Video views | 30-day window; defaults to impressions for static pins | | `viewsUnique` | - | Same as views | | `likes` | Total reactions | Lifetime | | `comments` | Total comments | Lifetime | | `shares` | - | Returns `0` (not tracked by Pinterest) | | `saves` | Saves | 30-day window | ### Quirks * Views are only meaningful for video pins. Static pins show impressions in the views field as a fallback. * Profile-level comments are not available through the Pinterest API. * Shares are not a concept Pinterest tracks. * Post analytics use a mixed approach: some metrics are rolling window, others are lifetime. It's confusing, but it's what Pinterest gives us. ### Raw Analytics Pinterest profile raw analytics include the user analytics payload, follower list, and following list we used to build the standard numbers. ```json theme={null} { "analytics": { "summary_metrics": { "IMPRESSION": 54000, "SAVE": 820, "VIDEO_START": 9100 } }, "followers": { "items": [{ "username": "follower_1" }] }, "following": { "items": [{ "username": "brand_1" }] } } ``` Pinterest post raw analytics store the Pin analytics response for the requested date range. ```json theme={null} { "externalId": "1234567890", "summary_metrics": { "IMPRESSION": 6400, "SAVE": 94, "PIN_CLICK": 220, "OUTBOUND_CLICK": 58, "VIDEO_START": 0 } } ``` # Reddit Source: https://info.bundle.social/api-reference/platforms/reddit The front page of the internet. Minimalist analytics, maximum subreddit rules. Reddit is a collection of communities, each with its own rules. The API is functional but stingy with data - especially analytics. ## Supported Content Types * **Text Posts:** Title + text. Title is required. * **Link Posts:** Title + URL. * **Image Posts:** 1 image, or gallery (up to 10 images if the subreddit allows). * **Video Posts:** 1 video. ## Quirks & Gotchas ### Subreddit Rules are King Each subreddit has its own rules about what's allowed: * Some subreddits don't allow media at all. * Some allow images but not galleries. * Some require flairs. * We validate against subreddit settings before posting. If it's not allowed, you get a clear error. ### Engagement Terminology * **Likes** = **Upvotes** * **Dislikes** = **Downvotes** * **Shares** = **Crossposts** Reddit does not track "Impressions" or "Reach" the way marketers want. If that's a dealbreaker, you're on the wrong platform. ### Media Limits | Constraint | Value | | :- | :- | | **Single post** | 0-1 file (image or video) | | Video max size | 1 GB | | Video aspect ratio | 9:16 to 16:9 | | Video duration | 4s - 15 min | | Image max size | 20 MB | | **Gallery** | 0-10 images (if subreddit allows) | | Gallery image max size | 20 MB each | See [Platform Limits](/api-reference/limits#reddit) for more details. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` (title) | Max 300 characters | | `description` | Max 30,000 characters | | `link` | Max 2,048 characters | *** ## Post Options Send Reddit-specific options inside `data.REDDIT`. | Field | Type | Description | | :- | :- | :- | | `sr` | `string` | Required. Subreddit name such as `r/productivity` or profile target such as `u/username`. | | `text` | `string` | Required. Reddit post title. Max 300 characters. | | `description` | `string` | Body text for text posts. Max 30,000 characters. | | `uploadIds` | `string[]` | Media attachments. One image/video for media posts, or up to 10 images for galleries if the subreddit allows it. | | `link` | `string` | URL for link posts. Max 2,048 characters. | | `nsfw` | `boolean` | Marks the post as NSFW. Default: `false`. | | `flairId` | `string` | Flair ID. Required when the subreddit requires a flair. | ```json theme={null} { "teamId": "team_123", "title": "Reddit discussion", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["REDDIT"], "data": { "REDDIT": { "sr": "r/productivity", "text": "What changed the most in your planning workflow?", "description": "We are collecting practical examples from teams.", "nsfw": false, "flairId": "flair_123" } } } ``` *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). ### Profile Analytics **Status:** Not available. Reddit does not provide profile-level analytics through their API. Everything returns `0`. All of it. Every single metric. Don't ask. ### Post Analytics **Period:** Lifetime. | Metric | Description | Note | | :- | :- | :- | | `impressions` | - | Returns `0` (not available) | | `impressionsUnique` | - | Returns `0` (not available) | | `views` | View count | May not be available for all posts | | `viewsUnique` | - | Returns `0` (not available) | | `likes` | Upvotes | | | `dislikes` | Downvotes | | | `comments` | Comments | | | `shares` | Crossposts | | | `saves` | - | Returns `0` (not available) | ### Quirks * Reddit has the most limited analytics of any major platform we support. * No profile-level analytics whatsoever. * View counts exist for some posts but are not guaranteed. * No impressions or reach metrics. Reddit's API simply doesn't provide them. * Upvotes/downvotes are the primary engagement signals. ### Raw Analytics Reddit profile raw analytics are limited to karma fields. ```json theme={null} { "total_karma": 18420, "comment_karma": 6400, "awarder_karma": 120 } ``` Reddit post raw analytics store the submission payload returned by Reddit. ```json theme={null} { "id": "abc123", "subreddit": "productivity", "title": "What changed the most in your planning workflow?", "ups": 420, "downs": 12, "num_comments": 88, "num_crossposts": 4, "view_count": 12400, "permalink": "/r/productivity/comments/abc123/example/" } ``` # Slack Source: https://info.bundle.social/api-reference/platforms/slack Workspace messaging via incoming webhooks. Needs an admin to connect, a channel selection per post, and gives you a generous 30k character limit. Like Discord, Slack uses a webhook-based approach for posting messages. ## Quirks & Gotchas ### Webhook-Based Posting Slack requires you to connect a workspace and select channels. We use incoming webhooks to post messages. * You must be a workspace admin to connect. * Posts appear as a bot message in the selected channel. ### Channel Selection Required You must specify a `channelId` in your post data. Available channels are in `socialAccount.channels`. ### Generous Character Limit Slack allows up to **30,000 characters** per message-much more than most platforms. ### Custom Bot Identity Like Discord, you can customize the bot appearance: * `username`: Up to 80 characters. * `avatarUrl`: A URL to an image for the bot's avatar. *** ## Post Options | Field | Type | Description | | :- | :- | :- | | `channelId` | `string` | **Required.** The channel to post to. Found in `socialAccount.channels`. | | `text` | `string` | Message content. Max 30,000 characters. | | `uploadIds` | `string[]` | Media attachments. | | `username` | `string` | Custom display name. Max 80 characters. | | `avatarUrl` | `string` | Custom avatar URL. Max 2048 characters. | *** ## Media Limits | Constraint | Value | | :- | :- | | Files | 0-4 (images and/or videos, mixed allowed) | | Video max size | 1 GB | | Image max size | 1 GB | | Text | Max 30,000 characters | See [Platform Limits](/api-reference/limits#slack) for more details. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 30,000 characters | | `username` | Max 80 characters | | `avatarUrl` | Max 2,048 characters | *** ## Analytics For general analytics concepts, see the [Analytics Overview](/api-reference/analytics). Slack does not provide analytics via its API. All metrics return `0`. It's a workspace tool, not a social media platform. | Metric | Note | | :- | :- | | `impressions` | Returns `0` | | `views` | Returns `0` | | `likes` | Returns `0` | | `comments` | Returns `0` | *** ## Example ```javascript theme={null} await bundle.post.create({ socialAccountTypes: ["SLACK"], data: { SLACK: { channelId: "C0123456789", text: "New product launch! Check it out.", username: "Marketing Bot" } } }); ``` # Snapchat Source: https://info.bundle.social/api-reference/platforms/snapchat Connect Snapchat Public Profiles, publish Stories and Spotlights, and retrieve profile and content analytics. > [!WARNING] > > SNAPCHAT SUPPORT USES THE **PUBLIC PROFILE API**. THE CONNECTED SNAPCHAT ACCOUNT MUST HAVE A PUBLIC PROFILE THAT THE AUTHORIZING USER CAN MANAGE. ## Supported Content Types * Public Stories with one image or MP4 video. * Saved Stories with up to 20 images or MP4 videos. * Spotlights with one MP4 video. * Profile, Story, and Spotlight analytics. ## Connection Methods Pass `snapchatConnectionMethod` to [`connect`](/api-reference/connect-social-accounts/custom-ui-flow) or to a [portal link](/api-reference/connect-social-accounts/hosted-flow): | Method | What it connects | Needs `set-channel`? | | :- | :- | :- | | `PERSONAL` (default) | The Public Profile of the Snapchat login itself. | No. The profile returned during OAuth becomes the publishing target. | | `BUSINESS` | Any Public Profile of the Snap Business organizations the login belongs to. We also request the `snapchat-marketing-api` scope. | Yes. The profiles are listed in `socialAccount.channels`; pick one with `set-channel`. `refresh-channels` reloads the list. | The login needs the **Admin or Collaborator** role on a profile for it to be listed under `BUSINESS`. If it has a role on none, the connection ends with `snapchat-no-business-profiles`. Accounts connected before `BUSINESS` existed have `snapchatConnectionMethod: null` and behave as `PERSONAL`. On a portal link without `snapchatConnectionMethod`, the user chooses the method in the portal. ## Post Options | Field | Type | Description | | :- | :- | :- | | `type` | `STORY` \| `SAVED_STORY` \| `SPOTLIGHT` | Defaults to `STORY`. | | `uploadIds` | `string[]` | Required. Exactly one uploaded media file, or 1-20 for `SAVED_STORY`. | | `storyDuration` | `ONE_DAY` \| `TWO_DAYS` \| `THREE_DAYS` \| `ONE_WEEK` | `STORY` only. How long the Story stays visible. Defaults to 24 hours. | | `title` | `string` | Required for `SAVED_STORY`, max 45 characters. Keep it to 40 or fewer: Snapchat rejects some longer titles. | | `description` | `string` | Spotlight description, max 160 characters. | | `text` | `string` | Alias for Spotlight `description`, max 160 characters. `description` takes precedence. | | `locale` | `string` | Spotlight locale in `en_US` format. Defaults to `en_US`. | | `skipSaveToProfile` | `boolean` | Spotlight only. Ask Snapchat not to save the Spotlight to the Public Profile. Defaults to `false`. | ### Story Example ```json theme={null} { "teamId": "team_123", "title": "Launch Story", "status": "SCHEDULED", "postDate": "2026-07-20T15:00:00.000Z", "socialAccountTypes": ["SNAPCHAT"], "data": { "SNAPCHAT": { "type": "STORY", "uploadIds": ["upload_image_123"] } } } ``` ### Spotlight Example ```json theme={null} { "teamId": "team_123", "title": "Launch Spotlight", "status": "SCHEDULED", "postDate": "2026-07-20T15:00:00.000Z", "socialAccountTypes": ["SNAPCHAT"], "data": { "SNAPCHAT": { "type": "SPOTLIGHT", "uploadIds": ["upload_video_123"], "description": "A quick look at what we shipped", "locale": "en_US", "skipSaveToProfile": false } } } ``` ## Media Limits ### Stories | Constraint | Value | | :- | :- | | Files | Exactly 1 image or MP4 video | | Max video file size | 400 MB | | Max image file size | 100 MB | | Video minimum resolution | 540x960 | | Video duration | 5-180 seconds | ### Saved Stories | Constraint | Value | | :- | :- | | Files | 1-20 images and/or MP4 videos | | Max file size | 400 MB per video, 100 MB per image | | Video minimum resolution | 540x960 | | Video duration | 5-180 seconds per video | | Combined length | Max 300 seconds (each image counts as 10 seconds) | | Title | Required, max 45 characters (40 or fewer recommended) | ### Spotlights | Constraint | Value | | :- | :- | | Files | Exactly 1 MP4 video | | Max file size | 400 MB | | Minimum resolution | 540x960 | | Video duration | 5-180 seconds | ## Troubleshooting | Error | What it means | Fix | | :- | :- | :- | | `snapchat-no-business-profiles` (on connect with `BUSINESS`) | The login has no role on any Public Profile of its Snap Business organizations. | Ask an organization admin to give the login the Admin or Collaborator role on a profile, then connect again. | | "This Snapchat account has no Public Profile" (on connect) | The Snapchat login has no Public Profile. Snapchat's API can only publish as a Public Profile. | Create a Public Profile in the Snapchat app, or log in with the account that owns it, then connect again. | | `SNAP:AUTHORIZATION_PERMISSION_DENIED` "Could not upload Snapchat media" | The connected Snapchat account can see the profile but is not its **Owner or Admin** (e.g. a collaborator, or access only through Ads Manager). | Give that account the Admin role on the Public Profile, or reconnect with the account that owns it. | | `SNAP:MEDIA_NOT_VALID_FOR_STORY_POSTING` | The media doesn't meet Snapchat's Story requirements. | Use an MP4 video of 5-180 seconds, at least 540x960. | | "Failed to create saved story: Title" | Snapchat rejected the Saved Story title. | Keep the title to 40 characters or fewer. | ## Publishing Behavior Snapchat processes uploaded media asynchronously. A post can remain in `PROCESSING` while Snapchat prepares the asset. bundle.social polls the media state and finalizes the Story or Spotlight when it becomes ready. The post response stores Snapchat progress in `externalData.SNAPCHAT`, including `mediaId`, content `type`, Public Profile ID, source upload ID, and one of these statuses: * `MEDIA_UPLOADED` * `MEDIA_PROCESSING` * `PUBLISHED` ## Analytics ### Profile Analytics | Metric | Snapchat source | | :- | :- | | `impressions`, `views` | Combined profile, Story, saved Story, Spotlight, and Lens views returned by Snapchat | | `impressionsUnique`, `viewsUnique` | Unique sessions/viewers where available; falls back to views | | `likes` | Favorites/likes across supported profile content | | `comments` | Replies/comments | | `postCount` | Story, saved Story, Spotlight, and Lens content counts where available | | `followers` | Subscribers/followers | | `following` | Returns `0` | ### Story And Spotlight Analytics Post analytics use Snapchat lifetime stats and map views, unique viewers, favorites, replies, shares, and screenshots into the standard post analytics fields. Raw Snapchat analytics can be enabled per organization. [Contact us](https://bundle.social/contact) if you need the original Snapchat stats payload alongside normalized metrics. With raw analytics on, profile raw data also includes `demographics`: Snapchat's lifetime profile stats broken down by **age × gender** (`AGE_GENDER`) and **country** (`COUNTRY`), exactly as Snapchat returns them (each stat has a `dimension_breakdown` such as `AGE_18_24` plus `value` and `percentage_value`). These describe your viewers, not a follower list. If Snapchat doesn't return a breakdown for a profile, `demographics` is `null`. # Threads Source: https://info.bundle.social/api-reference/platforms/threads Meta's text app. It's like Twitter, but with Meta's infrastructure and surprisingly decent API. Threads is the new kid on the block, integrated tightly with Instagram's infrastructure. The API is surprisingly decent for a platform this young. ## Supported Content Types * **Text Posts:** Text only, or text with images/videos. 0-10 files. * **Mixed Media:** Images and videos can be combined in the same post. Up to 10 items. ## Quirks & Gotchas ### Terminology * **Comments** are called **Replies** in Threads-land. * **Shares** include both **Reposts** and **Quotes**. We combine them into one number. ### Date Restrictions Threads requires posts to be after **April 2024** for analytics. Older imported posts won't have analytics data. ### Media Limits | Constraint | Value | | :- | :- | | Files | 0-10 (images and/or videos, mixed allowed) | | Video max bitrate | 100 Mbps | | Video aspect ratio | 0.01:1 to 1.91:1 | | Image max size | 8 MB | | Image width | 320-1440px | | Image aspect ratio | 0.01:1 to 1.91:1 | See [Platform Limits](/api-reference/limits#threads) for more details. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` | Max 500 characters | | `altText` | Optional. Accessibility description for **image** media in the post. | > [!NOTE] > > **Alt text** applies to image items Threads publishes through our API. Videos use platform-specific behavior; set alt text when you are posting images. *** ## Post Options Send Threads-specific options inside `data.THREADS`. | Field | Type | Description | | :- | :- | :- | | `text` | `string` | Post text. Max 500 characters. | | `uploadIds` | `string[]` | Up to 10 uploaded media files. Images and videos can be mixed. | | `mediaItems` | `array` | Optional per-media metadata. Use it to attach `altText` to image uploads. | | `topicTag` | `string` | A single topic tag shown in the post header. 1-50 characters, no periods (`.`) or ampersands (`&`). Threads allows one topic per post. | | `replyControl` | `enum` | Who can reply to the post. See [Reply Control](#reply-control). Threads defaults to `everyone`. | | `linkAttachment` | `string` | A URL attached to the post as a link preview card. **Text-only posts only.** | | `poll` | `object` | A poll attachment (2-4 options). **Text-only posts only.** See [Polls](#polls). | | `gif` | `object` | A GIF attachment. **Text-only posts only.** See [GIFs](#gifs). | | `allowlistedCountryCodes` | `string[]` | Restrict post visibility to these ISO 3166-1 alpha-2 country codes. Requires Meta account eligibility. | | `crosspostToInstagramStory` | `boolean` | Cross-share the post to the linked Instagram account as a Story. | | `crosspostToInstagramStoryDarkMode` | `boolean` | Cross-share the post to the linked Instagram account as a Story in dark mode. | | `isGhostPost` | `boolean` | Publish a ghost post that Threads archives after 24 hours. Text only. See [Ghost Posts](#ghost-posts). | ```json theme={null} { "teamId": "team_123", "title": "Threads launch post", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["THREADS"], "data": { "THREADS": { "text": "A quick launch note", "uploadIds": ["upload_image_123"], "mediaItems": [ { "uploadId": "upload_image_123", "altText": "Product screen on a phone" } ], "topicTag": "ProductLaunch", "replyControl": "followers_only" } } } ``` *** ## Reply Control Set `replyControl` in `data.THREADS` to control who can reply to the post. Threads defaults to `everyone` when omitted. | Value | Who can reply | | :- | :- | | `everyone` | Anyone (default) | | `accounts_you_follow` | Only accounts you follow | | `mentioned_only` | Only users mentioned in the post | | `parent_post_author_only` | Only the author of the parent post | | `followers_only` | Only your followers | *** ## Polls Polls attach a 2-4 option vote to a **text-only** post. Options `optionA` and `optionB` are required; `optionC` and `optionD` are optional. Each option is 1-25 characters. ```json theme={null} { "data": { "THREADS": { "text": "Which one ships first?", "poll": { "optionA": "Dark mode", "optionB": "Scheduling", "optionC": "Analytics" } } } } ``` *** ## GIFs Attach a GIF to a **text-only** post. GIPHY is currently the only supported provider. ```json theme={null} { "data": { "THREADS": { "text": "Shipping day vibes", "gif": { "gifId": "l0MYt5jPR6QX5pnqM", "provider": "GIPHY" } } } } ``` *** ## Ghost Posts Set `isGhostPost: true` to publish a text post that Threads archives automatically 24 hours after it goes live. ```json theme={null} { "data": { "THREADS": { "text": "Gone tomorrow", "isGhostPost": true } } } ``` > [!WARNING] > > Ghost posts are **plain text only**. With `isGhostPost: true`, a post that also has `uploadIds`, `poll`, `gif`, `linkAttachment`, `topicTag`, `replyControl`, `allowlistedCountryCodes`, `crosspostToInstagramStory` or `crosspostToInstagramStoryDarkMode` fails validation with `400`, with one message per field. *** ## Text-Only Attachment Rules > [!WARNING] > > `poll`, `gif`, and `linkAttachment` are only allowed on **text-only** posts. If the post also has `uploadIds`, validation fails. A post also cannot have both a `poll` and a `gif` at the same time. *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). ### Profile Analytics **Period:** Rolling window. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Content impressions | Internally contains quote count from API | | `impressionsUnique` | Unique impressions | Internally contains repost count from API | | `views` | Views | Summed over the last 2 years (never before April 13, 2024) | | `viewsUnique` | - | Same as views | | `likes` | Likes | | | `comments` | Replies | | | `postCount` | Total posts | Reposts of other people's posts don't count, and they aren't imported as your posts | | `followers` | Followers | | | `following` | - | Returns `0` (not provided by Threads API) | ### Post Analytics **Period:** Lifetime. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Views | | | `impressionsUnique` | - | Same as impressions | | `views` | Views | Same as impressions | | `viewsUnique` | - | Same as views | | `likes` | Likes | | | `comments` | Replies | | | `shares` | Reposts + Quotes | Combined into one number | ### Quirks * Views metric is used for both impressions and views (they are the same value). * Comments are called "replies" in Threads. * Shares include both reposts and quotes - we don't split them. * For profile analytics: the impressions field internally contains quote counts and impressionsUnique contains repost counts. This is how the Threads API returns data. * Following count is not available through the Threads API. * Profile `views` covers the last 2 years, and never reaches before April 13, 2024, the earliest date Threads serves insights for. Threads fails on long views series for some profiles, so we read it in 90-day slices and add them up. ### Raw Analytics Threads profile raw analytics are stored as the metrics we get back from Threads, plus a post count. ```json theme={null} { "likes": 420, "replies": 38, "views": 12400, "followers_count": 3100, "reposts": 55, "quotes": 12, "allProfilePosts": 84, "followerDemographics": { "country": { "data": [{ "name": "follower_demographics", "total_value": { "breakdowns": [{ "dimension_keys": ["country"], "results": [{ "dimension_values": ["US"], "value": 1240 }] }] } }] }, "city": { "data": [ /* same shape, dimension_keys ["city"] */ ] }, "age": { "data": [ /* same shape, dimension_keys ["age"], e.g. "25-34" */ ] }, "gender": { "data": [ /* same shape, dimension_keys ["gender"], "F" / "M" / "U" */ ] } } } ``` `followerDemographics` is the follower breakdown by country, city, age and gender, exactly as Threads returns it. It's collected when raw demographics are enabled for your organization (the same switch as Instagram demographics). Threads only returns it for profiles with at least 100 followers, so for smaller profiles (or if a breakdown fails) that breakdown is `null`. Post raw analytics store the Threads media/post payload we fetched for that item. ```json theme={null} { "id": "17890000000000000", "media_type": "IMAGE", "media_product_type": "THREADS", "permalink": "https://www.threads.net/@example/post/abc", "username": "example", "text": "A quick launch note", "timestamp": "2026-04-26T10:30:00+0000" } ``` # TikTok Source: https://info.bundle.social/api-reference/platforms/tiktok The viral machine. Watch out for music copyright, privacy settings, and image-format rules for photo mode. TikTok is the place for short-form video. The API has specific restrictions around music, privacy, and image formats that will surprise you. ## Supported Content Types * **Videos:** 1 video, up to 10 minutes. The bread and butter. * **Photo Mode (Images):** 1-35 images. **JPG, JPEG, or WebP only.** Max **20 MB per image**. PNG will be rejected. ## Quirks & Gotchas ### Privacy Levels & Permalinks If you set a video's privacy to `SELF_ONLY` (Private), the API **cannot** return a public permalink immediately. * The `permalink` field will be null or internal-only. * We can't give you a link to something that doesn't publicly exist. Physics still applies. ### Music & Copyright TikTok is extremely strict about music rights. * **Commercial Music Library (CML):** We expose TikTok's pre-cleared music via [TikTok Music](/api-reference/platforms/tiktok-music): trending tracks, genres, and `song_clip_id` for publish. No copyright roulette. * **Trending Audio:** You generally **cannot** use TikTok's in-app "trending audio" library directly via API. * **Royalty-Free:** You can use the `autoAddMusic` flag to let TikTok assign royalty-free music, but you lose control over the specific track. It's a gamble. * **Best Practice:** Use CML for controlled music, or burn your audio into the video file before uploading. ### Image Format (Photo Mode) TikTok accepts **JPG**, **JPEG**, and **WebP** files for Photo Mode posts. PNG and other formats will be rejected. Convert before uploading. Each image must be under **20 MB**. ### Image sizing (Photo Mode) For **IMAGE** posts, if photos are larger than **1920x1080** (or unusually tall/wide relative to that canvas), we may **auto-scale** them server-side so delivery matches what TikTok expects. You do not need to pre-shrink assets in every case. We handle the resizing when it helps. ### The REVIEW Status TikTok is the most common platform to put posts into a `REVIEW` status. This means TikTok wants to review the content before publishing. We periodically re-check and re-attempt publishing. Tell your users to be patient. ### Media Limits See [Platform Limits](/api-reference/limits#tiktok) for the full breakdown. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` (`VIDEO`) | Max 2,200 characters | | `text` (`IMAGE`) | Max 4,000 characters | | `title` (`IMAGE` only) | Max 90 characters | | `locationName` | Max 255 characters | *** ## Post Options | Field | Type | Description | | :- | :- | :- | | `type` | `VIDEO` \| `IMAGE` | Defaults to `VIDEO`. `IMAGE` is TikTok Photo Mode. | | `text` | `string` | Caption text. Max 2,200 characters for `VIDEO`, 4,000 for `IMAGE`. | | `title` | `string` | `IMAGE` only. Title of the photo post, max 90 characters. Rejected on `VIDEO` posts with `title is available only for IMAGE type posts.` | | `uploadIds` | `string[]` | One video, or 1-35 Photo Mode images. | | `locationId` | `string` | Location tag shown on the post, from [Location tags](#location-tags). `VIDEO` and `IMAGE`. Send together with `locationName`. | | `locationName` | `string` | Name of the location tag, as returned with `locationId`. Send together with `locationId`. | | `thumbnail` | `string` | VIDEO only. Custom cover: the `url` of an image uploaded to bundle.social (`POST /upload`). URLs hosted elsewhere are rejected with `400`, since TikTok only fetches covers from verified domains. JPG/PNG/WebP, 360x360 to 1080x1920, up to 20 MB. Overrides `thumbnailOffset`. | | `privacy` | `SELF_ONLY` \| `PUBLIC_TO_EVERYONE` \| `MUTUAL_FOLLOW_FRIENDS` \| `FOLLOWER_OF_CREATOR` | TikTok visibility setting. | | `photoCoverIndex` | `number` | Zero-based cover image index for Photo Mode. | | `isBrandContent` | `boolean` | Paid partnership promoting a third-party business. | | `isOrganicBrandContent` | `boolean` | Content promoting the creator's own business. | | `disableComments` | `boolean` | Disable comments. | | `disableDuet` | `boolean` | Disable Duets. | | `disableStitch` | `boolean` | Disable Stitches. | | `thumbnailOffset` | `number` | Video cover frame offset in milliseconds. Ignored when `thumbnail` is set. | | `isAiGenerated` | `boolean` | Mark AI-generated content. | | `autoAddMusic` | `boolean` | Let TikTok add music to Photo Mode posts. | | `autoScale` | `boolean` | For `IMAGE` posts only. Scale oversized images server-side. | | `uploadToDraft` | `boolean` | Upload as TikTok draft/inbox item. | | `musicSoundInfo` | `object` | CML music settings. See [TikTok Music](/api-reference/platforms/tiktok-music). | > [!WARNING] > > Use `uploadToDraft` only when the user really wants TikTok draft handling. Draft uploads can cause massive publish delays. The video might show up in minutes, or it might take hours. > > TikTok's answer is traffic: some days are faster, some days are worse. If your product needs predictable publishing, publish directly instead of using drafts. ```json theme={null} { "teamId": "team_123", "title": "TikTok launch video", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["TIKTOK"], "data": { "TIKTOK": { "type": "VIDEO", "text": "Launch day", "uploadIds": ["upl_vid_1"], "privacy": "PUBLIC_TO_EVERYONE", "disableComments": false, "disableDuet": false, "disableStitch": false, "isAiGenerated": false } } } ``` ### Posting Options of an Account **Endpoint:** `GET /api/v1/misc/tiktok/post-settings` Returns the privacy levels, interaction settings and maximum video duration the connected TikTok account allows, read live from TikTok. Use it to build the options of your composer (which `privacy` values to offer, whether comments, Duets and Stitches can be turned on). | Param | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team with a connected TikTok account. The team must belong to your API key's organization. | ```http theme={null} GET /api/v1/misc/tiktok/post-settings?teamId=team_123 ``` ```json theme={null} { "privacyLevelOptions": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"], "commentDisabled": false, "duetDisabled": false, "stitchDisabled": true, "maxVideoPostDurationSec": 600 } ``` | Field | Description | | :- | :- | | `privacyLevelOptions` | Values the account accepts for `privacy`. Public accounts: `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `SELF_ONLY`. Private accounts: `FOLLOWER_OF_CREATOR`, `MUTUAL_FOLLOW_FRIENDS`, `SELF_ONLY`. | | `commentDisabled` | `true` when comments can't be enabled (the creator allows comments from no one). Send `disableComments: true`. | | `duetDisabled` | `true` when Duets can't be enabled (Duets set to "Only you", or a private account). Send `disableDuet: true`. | | `stitchDisabled` | `true` when Stitches can't be enabled (Stitches set to "Only you", or a private account). Send `disableStitch: true`. | | `maxVideoPostDurationSec` | Longest video, in seconds, the account can publish. Can be `null`. Longer videos fail at publish time. | A value the account doesn't allow is not rejected when you create the post. It fails at publish time with `TT:40002`. > [!NOTE] > > Each call counts against the account's TikTok rate limit, so fetch it when building your composer, not before every publish. If TikTok returns incomplete settings, the endpoint returns `502`. ### Spark Ads Authorization Code Turn on **Ad authorization** for a public TikTok post and get its Spark Ads code. Hand the code to an advertiser, who adds it to their TikTok ad account to run the post as a Spark Ad. No extra TikTok permissions are needed. | Method | Endpoint | What it does | | :- | :- | :- | | `GET` | `/api/v1/misc/tiktok/ad-authorization` | Current code, its validity window and `status`. | | `POST` | `/api/v1/misc/tiktok/ad-authorization` | Turns on ad authorization and returns the code. Enabling it accepts TikTok's Advertising Content Terms of Service for the post. | | `POST` | `/api/v1/misc/tiktok/ad-authorization/extend` | Extends the code, or issues a new one after it was disabled. | | `DELETE` | `/api/v1/misc/tiktok/ad-authorization` | Turns ad authorization off. | Address the post with `teamId` plus **exactly one** of: | Param | Description | | :- | :- | | `postId` | A bundle.social post published to TikTok. It must have been published from the TikTok account connected to the team now. | | `platformPostId` | The TikTok post ID (`item_id`) of a public post on the team's TikTok account, for posts published outside bundle.social. | `POST` and `extend` also take `authorizationDays`: `7`, `30`, `60`, `180` or `365` (default `30`). ```json theme={null} { "teamId": "team_123", "postId": "post_abc123", "authorizationDays": 60 } ``` ```json theme={null} { "platformPostId": "7312345678901234567", "authCode": "", "startsAt": "2026-11-17T10:00:00.000Z", "expiresAt": "2027-01-16T10:00:00.000Z", "authorizationDays": 60, "status": "NOT_USED" } ``` `status` is `NOT_USED`, `IN_USE` (an advertiser runs the post as a Spark Ad) or `EXPIRED`. TikTok's own refusals come back as `400`, its rate limits as `429`, and anything else it fails on as `502`. ### Location Tags **Endpoint:** `GET /api/v1/misc/tiktok/locations` Searches TikTok's location tags for the team's TikTok account. Put the chosen tag on a post with `locationId` and `locationName`. | Param | Required | Description | | :- | :- | :- | | `teamId` | Yes | Team with a connected TikTok account. | | `q` | Yes | Search text, 1 to 100 characters. | ```http theme={null} GET /api/v1/misc/tiktok/locations?teamId=team_123&q=warsaw ``` ```json theme={null} { "items": [ { "locationId": "123456789", "name": "Warsaw", "address": "Poland" }, { "locationId": "987654321", "name": "Warsaw Old Town", "address": "Rynek Starego Miasta, Warsaw, Poland" } ] } ``` `address` can be a country, region, city or full street address, and can be `null`. Send both fields with the post; either one alone is rejected: ```json theme={null} { "TIKTOK": { "type": "VIDEO", "text": "Launch day", "uploadIds": ["upl_vid_1"], "privacy": "PUBLIC_TO_EVERYONE", "locationId": "123456789", "locationName": "Warsaw" } } ``` *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). TikTok provides detailed analytics data: demographics, audience splits, watch metrics, the works. Check the raw analytics for the detailed breakdowns. ### Profile Analytics **Period:** Rolling window (30 days). Aggregated from daily metrics. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Video views | | | `impressionsUnique` | Unique video views | | | `views` | Video views | Same as impressions for TikTok | | `viewsUnique` | Unique video views | Same as impressionsUnique | | `likes` | Total likes | Aggregated across all videos | | `comments` | Total comments | | | `postCount` | Total videos | | | `followers` | Followers | | | `following` | Following | | ### Post Analytics **Period:** Lifetime (Snapshot). | Metric | Description | Note | | :- | :- | :- | | `impressions` | Video views | | | `impressionsUnique` | Unique views | TikTok doesn't always distinguish; can equal impressions | | `views` | Video views | Same as impressions | | `viewsUnique` | Unique views | Same as impressionsUnique | | `likes` | Likes | | | `comments` | Comments | | | `shares` | Shares | | | `saves` | - | Returns `0` (not provided by TikTok API) | ### Quirks * Profile analytics aggregate daily metrics over a 30-day window. * Post analytics are lifetime values. * TikTok can take up to **48 hours** to process some detailed analytics like audience demographics. * Views and unique views are tracked separately but can sometimes be 0 if the platform decides so. ### Raw Analytics - Demographics & Audience Data TikTok provides audience and engagement data via raw analytics. Here's what the raw payload looks like when enabled for your organization: #### Account-Level Raw Data ```json theme={null} { "followers_count": 125400, "following_count": 342, "total_likes": 2891000, "videos_count": 287, "unique_video_views": 1450000, "video_views": 8920000, "comments": 45200, "audience_ages": [ { "age_range": "18-24", "percentage": 42.3 }, { "age_range": "25-34", "percentage": 31.7 }, { "age_range": "35-44", "percentage": 14.2 }, { "age_range": "45-54", "percentage": 7.1 }, { "age_range": "55+", "percentage": 4.7 } ], "audience_cities": [ { "city": "Los Angeles", "percentage": 8.2 }, { "city": "New York", "percentage": 7.1 }, { "city": "London", "percentage": 5.4 } ], "engaged_audience": [ { "metric": "likes", "value": 89200 }, { "metric": "comments", "value": 4520 }, { "metric": "shares", "value": 12300 } ], "metrics": [ { "date": "2026-01-15", "new_followers": 234, "video_views": 45600, "profile_views": 1230, "likes": 3400, "comments": 120, "shares": 890, "audience_activity": [ { "hour": "0", "count": 12 }, { "hour": "1", "count": 18 } ] } ] } ``` `audience_activity` is the hourly breakdown of when your followers are active on TikTok (UTC). Like the other `audience_*` fields, TikTok only returns it for accounts with at least 100 followers. #### Video-Level Raw Data ```json theme={null} { "item_id": "7123456789", "caption": "My viral video", "video_views": 1200000, "likes": 89000, "comments": 4500, "shares": 12000, "average_time_watched": 18.4, "full_video_watched_rate": 0.42, "total_time_watched": 22080000, "reach": 890000, "impression_sources": [ { "source": "For You", "percentage": 72.1 }, { "source": "Following", "percentage": 15.3 }, { "source": "Search", "percentage": 8.4 } ], "audience_genders": [ { "gender": "Male", "percentage": 45.2 }, { "gender": "Female", "percentage": 52.1 }, { "gender": "Other", "percentage": 2.7 } ], "audience_countries": [ { "country": "US", "percentage": 35.2 }, { "country": "GB", "percentage": 12.4 }, { "country": "BR", "percentage": 8.9 } ] } ``` > [!NOTE] > > TikTok raw data includes **impression sources** (For You, Following, Search), **watch-through rates**, **audience gender/country splits**, and daily metrics breakdowns. This is gold for content strategy - use it. # TikTok Music (CML) Source: https://info.bundle.social/api-reference/platforms/tiktok-music TikTok Commercial Music Library: pre-cleared tracks for videos and photos. Genres, date ranges, song_clip_id vs commercial_music_id, and the draft gotcha. TikTok's Commercial Music Library (CML) gives you pre-cleared tracks for organic posts and ads. No copyright roulette. Here's how it works, what the endpoint returns, and the quirks that'll bite you if you don't read this. ## The Endpoint **`GET /api/v1/misc/tiktok/cml/trending-list`** Returns up to 100 trending tracks. Filter by genre and time window. ### Query Parameters | Parameter | Type | Default | Description | | :- | :- | :- | :- | | `teamId` | string | required | Your team ID | | `genre` | string | `"POP"` | Genre filter. See [supported genres](#supported-genres) below | | `dateRange` | string | `"7DAY"` | `1DAY`, `7DAY`, or `30DAY`. How far back to rank popularity | ### Response Shape The response is a **flat array** of track objects. ```json theme={null} [ { "commercial_music_name": "Lo-Fi analog beat", "duration": 183, "thumbnail_url": "https://...", "artist": "Gloveity", "preview_url": "https://...", "genres": ["HIP_HOP/RAP", "LO-FI"], "rank_position": "1", "trending_history": [ { "date": "2026-02-15", "rank_position_daily": "1" } ], "full_duration_song_clip": { "preview_url": "https://...", "duration": 183, "song_clip_id": "6817312022837872642" }, "trending_song_clip": { "preview_url": "https://...", "duration": 183, "song_clip_id": "6817312022837872642" } } ] ``` **Use `song_clip_id`, not `commercial_music_id`.** We strip `commercial_music_id` from the response because it's not what you need for publishing. The ID you pass to the post API is `song_clip_id` from `full_duration_song_clip` or `trending_song_clip`. If you use the wrong one, TikTok will reject it. ## Supported Genres A sample of what's available: `POP`, `ROCK`, `LATIN`, `METAL`, `ELECTRONIC`, `HIP_HOP/RAP`, `ALTERNATIVE/INDIE`, `R&B/SOUL`, `COUNTRY`, `CLASSICAL`, `JAZZ`, `CHILL_BEATS`, `CHILLOUT`, `LO-FI`, `EDM`, `HOUSE`, `TECHNO`, `K-POP`, `J-POP`, `DANCE_POP`, `INDIE_POP`, and more. Check the [Swagger spec](https://api.bundle.social/swagger) for the full enum. ## Using Music in Posts When creating a post with `data.TIKTOK.musicSoundInfo`, you pass the **`song_clip_id`** as `musicSoundId`. That's it for the ID part. ### Video vs Image: Different Rules | Content Type | What you can pass | | :- | :- | | **VIDEO** | `musicSoundId` (required), `musicSoundVolume`, `musicSoundStart`, `musicSoundEnd`, `videoOriginalSoundVolume` | | **IMAGE** | **Only `musicSoundId`.** No volume, no start/end. Photos get one knob: which track. That's it. | > [!NOTE] > > For IMAGE posts, pass *only* `musicSoundId`. If you send `musicSoundVolume`, `musicSoundStart`, etc., TikTok's API will reject the request. We strip those fields server-side for IMAGE type so you don't have to remember. If you're building a form, don't show volume/trim controls for photo posts. ### Video: Volume & Trim For videos, you get real control: * **`musicSoundVolume`** (0-100): How loud the music is. * **`videoOriginalSoundVolume`** (0-100): How loud the original video audio (your voice, etc.) is. * **`musicSoundStart`** / **`musicSoundEnd`** (ms): Trim the track. Start at 100ms, end at 30000ms. If `musicSoundEnd` is 0 or less than or equal to `musicSoundStart`, we don't send it (TikTok would reject it). Omit both for the full track. So yeah, you can make the music louder than your voice, or the other way around. ## The Draft Gotcha Here's the thing: **draft uploads don't persist your music choice.** When you set `uploadToDraft: true`, TikTok uploads the post to the creator's drafts. Success. But TikTok's draft flow doesn't store which track you picked. **If music choice matters, don't use drafts.** Publish directly (or schedule) so the track is baked in. Drafts are for "save for later", not "save this exact audio mix for later." ## INBOX status (Draft Success) When you upload as draft, TikTok sometimes returns a different status instead of `PUBLISH_COMPLETE`. That means: "we put it in the creator's inbox as a draft, all good." We treat that as success when `uploadToDraft` is true. If you're not using drafts and you get this, something odd happened. Reach out. ## Quick Reference | Task | What to use | | :- | :- | | Get trending tracks | `GET /api/v1/misc/tiktok/cml/trending-list?teamId=...&genre=POP&dateRange=7DAY` | | ID for post | `song_clip_id` from `full_duration_song_clip` or `trending_song_clip` | | Video: full track | `musicSoundId` only (or omit start/end) | | Video: trim + volume | `musicSoundId`, `musicSoundVolume`, `videoOriginalSoundVolume`, `musicSoundStart`, `musicSoundEnd` | | Image: any music | `musicSoundId` only | | Drafts | Don't rely on music persisting | Need the full request/response schema? Check [Swagger](https://api.bundle.social/swagger). The CML endpoint is under misc/tiktok. # Twitter / X Source: https://info.bundle.social/api-reference/platforms/twitter It's X now. The API is... well, it exists. Analytics are available on demand, billed from X credits. The platform formerly known as Twitter. The API changes have been... eventful. Let's focus on what works. ## Billing Twitter/X is moving to a **usage-based billing model**. X charges for API access to post, and we pass that cost through to you **1:1 - at cost, with no markup**. You pay exactly what X charges us per tweet, nothing more. > [!NOTE] > > We don't add any margin on top of X's API pricing. Every tweet published through bundle.social is billed to your account at the same price X bills us. This is separate from your bundle.social plan. ## Supported Content Types * **Tweets:** Text with optional media. 0-4 files. * Images and videos can be mixed in the same tweet. ## Quirks & Gotchas ### Media Limits * Max 4 images per tweet. * Max 4 videos per tweet (though realistically, 1 is most common). * Video max size: 512 MB. ### Text & Subscription-Based Limits Twitter/X limits vary based on the account's subscription tier: | Tier | Text Limit | Video Duration | | :- | :- | :- | | Free | 280 chars | 140s (2:20) | | Basic | 280 chars | 140s (2:20) | | Premium | 25,000 chars | 600s (10 min) | | Premium+ | 25,000 chars | 600s (10 min) | See [Platform Limits](/api-reference/limits#twitter--x) for the full breakdown. *** ## Post Options Send X-specific options inside `data.TWITTER`. | Field | Type | Description | | :- | :- | :- | | `text` | `string` | Tweet text. Character limit depends on the account subscription tier. | | `uploadIds` | `string[]` | Up to 4 uploaded media files. Images and videos can be mixed. | | `replySettings` | `enum` | Controls who can reply. See the values below. | ```json theme={null} { "teamId": "team_123", "title": "X announcement", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["TWITTER"], "data": { "TWITTER": { "text": "Launching today", "uploadIds": ["upload_image_123"], "replySettings": "MENTIONED_USERS" } } } ``` *** ## Reply Settings You can control who's allowed to reply to your tweets. Set `replySettings` in the `data.TWITTER` object when creating a post. | Value | Who can reply | | :- | :- | | `EVERYONE` | Anyone (default) | | `FOLLOWING` | Only people you follow | | `MENTIONED_USERS` | Only users mentioned in the tweet | | `SUBSCRIBERS` | Subscribers only | | `VERIFIED` | Verified accounts only | If you don't set `replySettings` or set it to `EVERYONE`, we don't send the parameter to Twitter at all - which is Twitter's default behavior. ```json theme={null} { "data": { "TWITTER": { "text": "Hot take incoming", "replySettings": "MENTIONED_USERS" } } } ``` > [!NOTE] > > Reply settings depend on your Twitter/X account tier. Some options (like `SUBSCRIBERS`) only make sense if your account actually has subscribers. Twitter won't error out if you use them anyway - it just won't do much. *** ## Analytics Available **on demand only**. X charges for every API read, so we never refresh X analytics in the background. You trigger a refresh yourself, and each one is billed from your prepaid X credits, the same balance used for posting. | What | Endpoint | Fields | | :- | :- | :- | | Profile | `POST /api/v1/analytics/social-account/force` | `followers`, `following`, `postCount` (other metrics return `0`) | | Post | `POST /api/v1/analytics/post/force` | `impressions`, `likes`, `comments` (replies), `shares` (reposts + quotes), `saves` (bookmarks) | After a refresh, the data is available through the regular analytics endpoints. > [!NOTE] > > * If your credit balance is too low, the refresh fails with a clear "Not enough credits" error and nothing is charged. > * Forced refreshes have a daily limit per account and per post, like on every other platform. > * For your own posts X returns organic metrics (the richer set); if those aren't available we fall back to public metrics. # YouTube Source: https://info.bundle.social/api-reference/platforms/youtube Long-form, Shorts, and the legal requirement of Made for Kids. Videos up to 4 hours and 5 GB, Shorts auto-detected, and a title is always required. YouTube handles both traditional long-form videos and Shorts (vertical video). The API comes with legal requirements you can't ignore. ## Supported Content Types * **Videos:** Long-form content. 1 video, up to 4 hours. Max 5 GB. * **Shorts:** Vertical/square video, max 3 minutes. YouTube auto-detects based on duration and aspect ratio. ## Quirks & Gotchas ### "Made for Kids" (COPPA) This is not just a quirk, it's a **legal requirement**. * You **must** flag content as `madeForKids: true` if it targets children. * Failure to do so can result in penalties - real ones, from the FTC. * We expose this field in the `data.YOUTUBE` object. Use it. Don't skip it. Don't "figure it out later". ### Shorts Detection There is no special "upload as Short" button. YouTube decides for you based on the file: * **Duration:** Under **3 minutes** (180 seconds). * **Aspect Ratio:** Vertical (9:16) or Square (1:1). Technically 1:3 to 1:1. If your video meets these criteria, it becomes a Short. If it doesn't, it's a regular video. ### Custom Thumbnails YouTube applies a Short's custom thumbnail reliably only after the video has finished processing. So for a `SHORT`, and for a `VIDEO` that is square or vertical and up to 180 seconds long (or has no size or duration metadata), we set the thumbnail **after** processing: * The post becomes `POSTED` and `post.published` is sent right away, with `externalData.YOUTUBE.thumbnailStatus: "PENDING"`. * We check processing for up to 24 hours, then set the thumbnail. `thumbnailStatus` becomes `APPLIED`, or `FAILED` with YouTube's reason added as a warning in `errors.YOUTUBE`. The post stays `POSTED` either way. Read the result with `GET /api/v1/post/{id}`. * Setting a thumbnail manually while the video is still processing, or while we are applying the queued one, returns `400`. A manual thumbnail set after that wins over the queued one. Landscape videos get the thumbnail right after upload, as before. ### YouTube Title is Required Unlike most platforms where you just need text, YouTube treats `data.YOUTUBE.text` as the **video title**. If you leave it empty, YouTube can reject the upload. ### Media Limits See [Platform Limits](/api-reference/limits#youtube) for the full breakdown. ### Text & Field Limits | Field | Limit | | :- | :- | | `text` (video title) | Max 100 characters | | `description` | Max 5,000 characters | *** ## Post Options Send YouTube-specific options inside `data.YOUTUBE`. | Field | Type | Description | | :- | :- | :- | | `type` | `enum` | `VIDEO` or `SHORT`. Default: `SHORT`. | | `uploadIds` | `string[]` | Required. One uploaded video. | | `text` | `string` | Video title. Max 100 characters. | | `description` | `string` | Video description. Max 5,000 characters. | | `thumbnail` | `string` | Optional thumbnail image URL uploaded through bundle.social. For Shorts it is set after YouTube finishes processing the video. See [Custom Thumbnails](#custom-thumbnails). | | `privacy` | `enum` | `PRIVATE`, `PUBLIC`, or `UNLISTED`. Default sent to YouTube is public if omitted. | | `defaultLanguage` | `string` | BCP-47 language for the video's title and description, for example `en` or `pl`. Max 35 characters. | | `defaultAudioLanguage` | `string` | BCP-47 language for the video's default audio track, for example `en` or `pl`. Max 35 characters. | | `madeForKids` | `boolean` | Required by YouTube policy. Set `true` when the video is made for children. | | `containsSyntheticMedia` | `boolean` | Set `true` when the video contains AI-generated or synthetic content. | | `hasPaidProductPlacement` | `boolean` | Set `true` when the video contains paid product placement. | ```json theme={null} { "teamId": "team_123", "title": "YouTube launch video", "status": "SCHEDULED", "postDate": "2026-06-01T15:00:00.000Z", "socialAccountTypes": ["YOUTUBE"], "data": { "YOUTUBE": { "type": "VIDEO", "uploadIds": ["upload_video_123"], "text": "Product launch walkthrough", "description": "A full walkthrough of the new release.", "privacy": "PUBLIC", "defaultLanguage": "en", "defaultAudioLanguage": "en", "madeForKids": false, "containsSyntheticMedia": false, "hasPaidProductPlacement": false } } } ``` *** ## Analytics For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics). YouTube analytics are all **Lifetime** values. There is no rolling window - everything is cumulative from day one. ### Profile (Channel) Analytics **Period:** Lifetime. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Total channel views | | | `impressionsUnique` | - | Same as impressions (YouTube doesn't distinguish) | | `views` | Total channel views | Same as impressions | | `viewsUnique` | - | Same as views | | `likes` | - | Returns `0` (not available at channel level) | | `comments` | Total comments | Across all videos | | `postCount` | Total videos | | | `followers` | Subscribers | | | `following` | - | Returns `0` (not applicable to channels) | ### Post (Video) Analytics **Period:** Lifetime. | Metric | Description | Note | | :- | :- | :- | | `impressions` | Video views | | | `impressionsUnique` | - | Same as impressions (YouTube doesn't distinguish) | | `views` | Video views | Same as impressions | | `viewsUnique` | - | Same as views | | `likes` | Likes | | | `dislikes` | Dislikes | Available via API even though YouTube hides them on the UI | | `comments` | Comments | | | `shares` | Lifetime shares | From the YouTube Analytics API. Only filled when raw analytics are enabled for your org, otherwise `0` | | `saves` | - | Returns `0` (YouTube retired favorites) | ### Quirks * YouTube doesn't distinguish between impressions and unique impressions at any level. * Dislikes are available through the API (though YouTube no longer shows dislike counts publicly). Handy if you want to know the truth. * Channel-level likes are not available. Video shares need raw analytics enabled. YouTube gives us a lot, but not everything. * Imported videos are always `type: VIDEO`. Shorts are flagged in the post's `extraData` instead: `{ "contentType": "SHORTS", "isShort": true }`, and their `permalink` uses `https://www.youtube.com/shorts/`. `contentType` is YouTube's `creatorContentType` (`SHORTS`, `VIDEO_ON_DEMAND`, `LIVE_STREAM`, ...). If YouTube can't tell us (no views yet, say), `contentType` and `isShort` are left out and the link stays `/watch`. Re-running the import updates `extraData` and `permalink` on videos you already imported. * `extraData.visibility` is the video's YouTube privacy status: `PUBLIC`, `UNLISTED` or `PRIVATE` (`UNKNOWN` if YouTube doesn't say). It's set on import and updated on every analytics refresh, so a video switched to private or unlisted is reflected on the next refresh. Private and unlisted videos keep refreshing; they're not treated as deleted. ### Raw Analytics - Demographics & Audience Data YouTube raw analytics include demographics data when enabled for your organization. We query the YouTube Analytics API for each video and return age/gender breakdowns and country-level view counts. The same breakdown is also available for the whole channel in the profile raw analytics. > [!NOTE] > > Raw analytics are gated per organization (`rawYoutubeAnalyticsEnabled`). If raw analytics are disabled for your org, the extended fields below (demographics, traffic sources, monetization, etc.) are not collected - only the standard metrics remain. #### Monetization Monetization (revenue) data is included in raw analytics only when **both** conditions are met: 1. **Raw analytics are enabled** for your organization, and 2. The account connected with **business access** - the YouTube monetary analytics scope, granted via [`withBusinessScope`](/api-reference/connect-social-accounts/oauth-options#withbusinessscope) at connect time. When both hold, monetization appears at two levels: * **Channel-level** - a channel-wide revenue report for the analytics window, stored in the profile raw analytics `monetization` field. * **Video-level** - a per-video revenue report, stored in each video's `monetization` field. Both use the YouTube Analytics API metrics: `estimatedRevenue`, `estimatedAdRevenue`, `estimatedRedPartnerRevenue`, `grossRevenue`, `cpm`, `playbackBasedCpm`, `adImpressions`, and `monetizedPlaybacks`. > [!NOTE] > > A channel **without monetization** - not in the YouTube Partner Program (YPP), or the account never granted the monetary scope - returns the string `"no data available"` in the `monetization` field instead of a report. This is expected and never fails the analytics run. **Channel with monetization** - the `monetization` field holds a report with `columnHeaders` and `rows`: ```json theme={null} { "monetization": { "analyticsWindow": { "startDate": "2026-06-19", "endDate": "2026-07-19" }, "columnHeaders": [ { "name": "estimatedRevenue", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "estimatedAdRevenue", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "estimatedRedPartnerRevenue", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "grossRevenue", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "cpm", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "playbackBasedCpm", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "adImpressions", "columnType": "METRIC", "dataType": "INTEGER" }, { "name": "monetizedPlaybacks", "columnType": "METRIC", "dataType": "INTEGER" } ], "rows": [ [1234.56, 1100.20, 134.36, 1800.00, 4.52, 3.98, 265000, 98000] ] } } ``` **Channel without monetization** - no YPP data or no monetary scope granted: ```json theme={null} { "monetization": "no data available" } ``` #### Channel Demographics Profile raw analytics carry a channel-wide `demographics` field: viewer percentage by age group and gender, plus views by country (sorted by views, descending). It covers the **last 365 days**, so it's a stable audience picture rather than a noisy 30-day slice. If YouTube returns nothing (or the call fails), the field is `null` and the rest of the run carries on. ```json theme={null} { "demographics": { "analyticsWindow": { "days": 365, "startDate": "2025-10-09", "endDate": "2026-10-08" }, "ageGender": { "columnHeaders": [ { "name": "ageGroup", "columnType": "DIMENSION" }, { "name": "gender", "columnType": "DIMENSION" }, { "name": "viewerPercentage", "columnType": "METRIC" } ], "rows": [ ["age18-24", "female", 14.2], ["age25-34", "male", 31.8] ] }, "country": { "columnHeaders": [ { "name": "country", "columnType": "DIMENSION" }, { "name": "views", "columnType": "METRIC" } ], "rows": [ ["US", 812000], ["GB", 190400] ] } } } ``` #### Video-Level Raw Data ```json theme={null} { "video": { "id": "dQw4w9WgXcQ", "snippet": { "title": "My Video", "publishedAt": "2026-01-15T10:00:00Z" }, "statistics": { "viewCount": "125000", "likeCount": "8900", "commentCount": "342" } }, "monetization": { "columnHeaders": [ { "name": "estimatedRevenue", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "estimatedAdRevenue", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "estimatedRedPartnerRevenue", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "grossRevenue", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "cpm", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "playbackBasedCpm", "columnType": "METRIC", "dataType": "FLOAT" }, { "name": "adImpressions", "columnType": "METRIC", "dataType": "INTEGER" }, { "name": "monetizedPlaybacks", "columnType": "METRIC", "dataType": "INTEGER" } ], "rows": [ [312.40, 280.10, 32.30, 460.00, 3.90, 3.41, 71000, 24500] ] }, "lifetimeTotals": { "analyticsWindow": { "startDate": "2026-01-14", "endDate": "2026-10-08" }, "views": 125000, "shares": 1840, "estimatedMinutesWatched": 402300, "averageViewDuration": 193, "averageViewPercentage": 61.4 }, "contentType": "VIDEO_ON_DEMAND", "isShort": false, "demographics": { "ageGender": { "columnHeaders": [ { "name": "ageGroup", "columnType": "DIMENSION" }, { "name": "gender", "columnType": "DIMENSION" }, { "name": "viewerPercentage", "columnType": "METRIC" } ], "rows": [ ["age18-24", "female", 12.3], ["age18-24", "male", 18.7], ["age25-34", "female", 14.1], ["age25-34", "male", 22.4], ["age35-44", "female", 8.2], ["age35-44", "male", 11.5] ] }, "country": { "columnHeaders": [ { "name": "country", "columnType": "DIMENSION" }, { "name": "views", "columnType": "METRIC" } ], "rows": [ ["US", 45200], ["GB", 12800], ["DE", 8900], ["BR", 7200] ] } } } ``` > [!NOTE] > > **Empty demographics data is normal.** YouTube has undocumented thresholds for when demographics become available. Unlike Instagram (\~1,000 followers), nobody knows YouTube's minimum. If `demographics` comes back empty or null for your videos, it likely means the account or video hasn't hit the threshold yet. If you do see data, let us know your account stats - we're trying to figure out the threshold too. > [!NOTE] > > Raw YouTube data includes **viewer percentage by age group and gender** and **views by country** (sorted by view count, descending). This is useful for audience analysis and content strategy - especially if you're targeting specific demographics or regions. > [!NOTE] > > `lifetimeTotals` covers the video's whole life (the window starts on or before the day before it went live, and runs until today). `averageViewDuration` is in seconds, `averageViewPercentage` is a percentage of the video length. `contentType` / `isShort` come from YouTube's `creatorContentType`. Any of these is `null` when YouTube has no data for the video yet. The normalized `shares` metric is taken from `lifetimeTotals.shares`. > [!NOTE] > > At the video level, the `monetization` field is `null` when the account has **no business access** (monetary scope was never granted), and `"no data available"` when the account has business access but the video has no monetary data (e.g. not in YPP). A populated report only appears when business access is granted **and** the video earned revenue in the window. # Rate Limits Source: https://info.bundle.social/api-reference/rate-limits API limits, posting limits, commenting limits, and import quotas. No per-account charges: three layers of rate limiting plus daily caps per platform. ## No Account Limits bundle.social is a unified social media API built for scale. Unlike other social media management APIs, we don't charge per connected account or punish you for growing. Connect 1 account or 10,000 accounts - same flat pricing. Our API supports Instagram, TikTok, YouTube, Snapchat, Facebook, LinkedIn, Twitter/X, Pinterest, Reddit, Threads, Mastodon, Bluesky, Discord, Slack, and Google Business Profile. Perfect for SaaS platforms, agencies, and enterprise applications that need unlimited social media integrations. *** ## API Rate Limits We use a multi-layer throttling system to keep things fair and prevent bursts from taking down the ranch. Limits are tracked **per endpoint** and per tracker: **API key** (organization), **bearer token** (user), or **IP** as fallback. ### The Three Layers | Layer | Window | Max Requests | Theoretical equivalent | What it prevents | | :- | :- | :- | :- | :- | | **Burst** | 1 second | 100 | 6,000 / minute | Someone doing `Promise.all()` with 500 requests | | **Short** | 10 seconds | 500 | 3,000 / minute | Aggressive polling or runaway loops | | **Minute** | 1 minute | 2,000 | 2,000 / minute | Sustained high-volume abuse | All three layers are enforced simultaneously. For sustained traffic, the **minute** layer (2,000/min) is the effective cap. > [!NOTE] > > Because limits are per endpoint, heavy traffic on `POST /post` does not consume the same bucket as `GET /analytics` for the same tracker. > [!WARNING] > > **Easy there, cowboy.** If you hit any of these limits, you'll get a `429 Too Many Requests`. Take a breath, wait a moment, and try again. We're not going anywhere. *** ## External Platform Rate Limits These are **daily limits per connected social account**, counted per **UTC calendar day** by the post's scheduled date. The quota is keyed by the **platform account itself** (platform + account id), not by the connection or the team - so the same real account connected more than once (reconnected, or added to multiple teams) **shares a single quota**. ### Posting daily limits per platform per tier | Platform | FREE | PRO | BUSINESS | | - | - | - | - | | TWITTER | 5 | 15 | 15 | | FACEBOOK | 10 | 50 | 100 | | INSTAGRAM | 10 | 50 | 100 | | LINKEDIN | 10 | 18 | 24 | | YOUTUBE | 10 | 10 | 15 | | TIKTOK | 5 | 10 | 15 | | THREADS | 10 | 200 | 250 | | PINTEREST | 10 | 24 | 36 | | REDDIT | 10 | 24 | 36 | | DISCORD | 10 | 100 | 200 | | SLACK | 10 | 100 | 200 | | MASTODON | 10 | 50 | 100 | | BLUESKY | 10 | 50 | 100 | | GOOGLE_BUSINESS | 10 | 20 | 40 | | SNAPCHAT | 5 | 20 | 40 | > [!NOTE] > > **X limits can be set to custom values on paid plans,** because X usage is billed separately from your plan. This applies to both the posting and the commenting daily limits for Twitter/X. See [pricing](https://bundle.social/pricing). > [!NOTE] > > **YouTube also has an organization-wide daily upload cap.** On top of the per-account limits above, new YouTube uploads are capped per organization per day. This day follows YouTube's quota day and resets at **midnight Pacific Time**, not UTC. When the cap is reached, the YouTube publish fails with `YT:orgDailyUploadLimit` and isn't retried automatically, see [Errors](/api-reference/errors#youtube). Need a higher cap? [Contact us](https://bundle.social/contact). > [!NOTE] > > **Example:** On Pro, each connected TikTok account gets its own 10 posts/day. Connect 5 **different** TikTok accounts → 50/day total (10 each, independent). But connect the **same** TikTok account to 5 teams → still 10/day total, because the quota follows the real account, not the connection. ### Check Daily Usage For One Account **Endpoint:** `GET /api/v1/organization/usage/daily-limits` | Query | Required | Description | | :- | :- | :- | | `socialAccountId` | Yes | bundle.social social account ID. | | `date` | No | Any parseable date or timestamp. Defaults to today; usage is calculated for its UTC calendar day. | ```http theme={null} GET /api/v1/organization/usage/daily-limits?socialAccountId=sa_123&date=2026-07-12 ``` The response includes the UTC `date`, account ID, platform `type`, and separate `posts` and `comments` objects with `used`, `limit`, and `remaining`. ### Commenting daily limits per platform per tier Daily caps per connected account, per platform, for comments created via the API. | Platform | FREE | PRO | BUSINESS | | - | - | - | - | | TWITTER | 3 | 15 | 15 | | FACEBOOK | 3 | 50 | 100 | | INSTAGRAM | 3 | 50 | 100 | | LINKEDIN | 3 | 18 | 24 | | YOUTUBE | 3 | 10 | 15 | | TIKTOK | 3 | 10 | 15 | | THREADS | 3 | 200 | 250 | | REDDIT | 3 | 24 | 36 | | DISCORD | 3 | 100 | 200 | | SLACK | 3 | 100 | 200 | | MASTODON | 3 | 50 | 100 | | BLUESKY | 3 | 50 | 100 | > [!NOTE] > > Comment creation is currently available for Twitter/X, Facebook, Instagram, LinkedIn, YouTube, TikTok, Reddit, Threads, Mastodon, Discord, Slack, and Bluesky. Pinterest and Google Business are not supported by the Comments API. ### Monthly organization-wide limits On top of daily limits, there are monthly caps across the entire organization: | Tier | Monthly Posts | Monthly Comments | Monthly Uploads | | - | - | - | - | | FREE | 20 | 50 | 200 | | PRO | 10,000 | 5,000 | 100,000 | | BUSINESS | 100,000 | 50,000 | 1,000,000 | > [!NOTE] > > **How the monthly cap is counted:** by **creation time**, in the **UTC calendar month** - i.e. when you *schedule* an item, not when it publishes. Scheduling a post for a future month still consumes the **current** month's quota. Drafts don't count; **failed or deleted items still count** (deleting doesn't refund). The window resets on the 1st of each month (UTC). ### Monthly messages and automation runs (per account) [Direct Messages](/api-reference/direct-messages) and [Automations](/api-reference/automations) have their own monthly quotas, counted per connected Instagram, Facebook or TikTok account rather than per organization: | Tier | Outbound messages / account / month | Automation runs / account / month | | - | - | - | | FREE | 0 | 0 | | PRO | 200 | 200 | | BUSINESS | 1,000 | 1,000 | For what counts toward each quota, see [Direct Messages: Plans and limits](/api-reference/direct-messages#plans-and-limits) and [Automations: Plans and limits](/api-reference/automations#plans-and-limits). Both reset on the 1st of each month (UTC). A higher limit agreed for your organization or for a single account replaces the plan default. ### Check Monthly Message And Automation Usage **Endpoint:** `GET /api/v1/organization/usage/messages` Lists every Instagram, Facebook and TikTok account in your organization (newest first) with its usage in the current UTC month. It works even before Direct Messages or Automations are turned on for your organization, so you can read the limits up front. | Query | Required | Description | | :- | :- | :- | | `teamId` | No | Only accounts in this team. | | `socialAccountType` | No | `INSTAGRAM`, `FACEBOOK` or `TIKTOK`. | | `socialAccountId` | No | Only this account. | | `offset` | No | Default `0`. | | `limit` | No | 1 to 100, default `10`. | ```http theme={null} GET /api/v1/organization/usage/messages?socialAccountType=INSTAGRAM&limit=20 ``` ```json theme={null} { "items": [ { "id": "sa_123", "type": "INSTAGRAM", "username": "acme", "displayName": "Acme", "messagesUsed": 57, "messagesLimit": 200, "automationRunsUsed": 41, "automationRunsLimit": 200 } ], "total": 1 } ``` `messagesLimit` and `automationRunsLimit` are the limits we enforce for that account, including any override. There is no `remaining` field: subtract `*Used` from `*Limit`. Usage of an account you reconnected is summed with the account it replaced, the same way sending is counted. *** ## Import Limits Limits that apply when importing historical content from connected social accounts. ### Post history imports (monthly, per social account) Maximum posts imported from each connected social account per month. Counter resets on the 1st of each month (UTC). | Tier | Posts / account / month | | - | - | | FREE | 5 | | PRO | 100 | | BUSINESS | 500 | A single post-history import request is additionally capped at **100 posts** (hard cap, not overridable). ### Comment imports (per post) Maximum comments stored per post on each import run. Imports always run - the cap just truncates to the newest N comments before storage. No monthly window, no counter. | Tier | Comments / post / import | | - | - | | FREE | 25 | | PRO | 200 | | BUSINESS | 1,000 | ### Google review and Facebook recommendation imports (monthly, per social account) Maximum Google reviews or Facebook Page recommendations imported from each connected social account per month. Counter resets on the 1st of each month (UTC). | Tier | Reviews or recommendations / account / month | | - | - | | FREE | 5 | | PRO | 200 | | BUSINESS | 200 | A single import request is additionally capped at **250 reviews or recommendations** (hard cap, not overridable). # SDK Source: https://info.bundle.social/api-reference/sdk Don't reinvent the wheel. Our typed TypeScript SDK for Node.js handles auth headers and the boring parts, and there is a CLI and MCP server too. We have a TypeScript SDK. It's typed, it's pretty, and it handles the boring stuff like auth headers. ## Node.js SDK * **NPM:** [`bundlesocial`](https://www.npmjs.com/package/bundlesocial) * **Github:** [`bundlesocial-node`](https://github.com/bundleglobal/bundlesocial-node) ### Installation ```bash theme={null} npm install bundlesocial # or pnpm add bundlesocial ``` ### Quick Setup ```typescript theme={null} import { BundleSocial } from 'bundlesocial'; const bundle = new BundleSocial('pk_live_...'); ``` ### Common Tasks #### 1. Upload a Video ```typescript theme={null} const video = await fs.readFile('./cat_vibing.mp4'); const upload = await bundle.upload.uploadCreate({ formData: { teamId: 'team_123', file: new Blob([video], { type: 'video/mp4' }), } }); ``` #### 2. Create a Post ```typescript theme={null} await bundle.post.postCreate({ requestBody: { teamId: 'team_123', title: 'Vibing cat', status: 'SCHEDULED', postDate: '2026-12-25T10:00:00.000Z', socialAccountTypes: ['TIKTOK', 'YOUTUBE'], data: { TIKTOK: { text: "Vibing cat 🎵", uploadIds: [upload.id], privacy: 'PUBLIC_TO_EVERYONE' }, YOUTUBE: { text: "Shorts cat", type: 'SHORT', madeForKids: false, uploadIds: [upload.id] } } } }); ``` #### 3. Handle Webhooks ```typescript theme={null} // Express handler const event = bundle.webhooks.constructEvent( rawBody, signature, process.env.WEBHOOK_SECRET ); if (event.type === 'post.published') { console.log('We are live!'); } ``` > [!NOTE] > > **Need Python or Go?**\ > We generate our SDKs from OpenAPI. If you need another language, just ask (or use the OpenAPI spec directly). ## Prefer a CLI or an AI client? > [card] [CLI](/api-reference/cli) > > `bundlesocial-cli` - JSON-first command line for shells, CI, cron and shell-out agents (ships an OpenClaw skill). > [card] [MCP server](/api-reference/mcp) > > `bundlesocial-mcp` - drive bundle.social from Claude Desktop / Claude Code / Cursor and other MCP clients. The per-platform `data` fields used above are documented in [Platform parameters](/api-reference/platform-parameters). # Media Upload Source: https://info.bundle.social/api-reference/upload-content Upload images, videos, and documents with small or large upload flows. ## Overview You have three ways to upload files. | Method | Best for | Ceiling | | :- | :- | :- | | **Multipart Upload** | Big videos. Chunked, retryable per part. | Your video limit - 5 GB by default, higher on request | | **Direct Upload** | One-shot uploads of moderate files. | 5 GiB (single-request storage limit) | | **Simple Upload** | Images and small clips. | 90 MB | > [!WARNING] > > **Recommendation:** Use **Multipart Upload** for videos. It is the only method where a > network drop costs you one 64 MiB chunk instead of the whole transfer - with Direct or > Simple, a failure at 99% means starting over. *** ## Method 1: Multipart Upload (The Pro Way) The file is split into fixed **64 MiB** chunks that you PUT independently, then we assemble them. Each chunk can be retried or re-signed on its own, so a long upload survives a flaky connection. ### Step 1: Initialize **Endpoint:** `POST /api/v1/upload/multipart/init` ```json theme={null} // Request { "fileName": "viral-video.mp4", "mimeType": "video/mp4", "fileSize": 8589934592, // required - we reject oversized files here, not after the transfer "teamId": "..." } ``` **Response:** an `uploadId`, the `path`, the `partSize`, and one presigned `url` per part. ```json theme={null} { "uploadId": "2~abc123...", "path": "team-id/9f8e7d6c.mp4", "partSize": 67108864, "parts": [ { "partNumber": 1, "url": "https://..." }, { "partNumber": 2, "url": "https://..." } ] } ``` ### Step 2: PUT each part - and keep every ETag Slice the file at `partSize` boundaries and `PUT` each slice to its own URL. Every part except the last must be exactly `partSize` bytes - storage rejects the assembly at the end if they are not uniform. **Read the `ETag` response header from each PUT.** You need the full list to finish, and there is no way to recover it afterwards. ```bash theme={null} curl -X PUT "https://..." --upload-file ./chunk-001 -D - # HTTP/1.1 200 OK # ETag: "d41d8cd98f00b204e9800998ecf8427e" ``` > [!NOTE] > > Part URLs are valid for **6 hours**. If one expires mid-upload, call > `POST /api/v1/upload/multipart/sign` with `{ path, uploadId, partNumbers: [12] }` to get a > fresh URL for just those parts. Parts you already uploaded keep their ETags - do not > re-send them. ### Step 3: Complete **Endpoint:** `POST /api/v1/upload/multipart/complete` ```json theme={null} // Request { "path": "team-id/9f8e7d6c.mp4", "uploadId": "2~abc123...", "parts": [ { "partNumber": 1, "etag": "\"d41d8cd9...\"" }, { "partNumber": 2, "etag": "\"a3f5b2e1...\"" } ], "teamId": "..." } ``` **Response:** the upload object, including the `id` you pass when creating a post. ### Handling errors on complete This is worth wiring properly - it decides whether a failure costs you seconds or a full re-upload. | Response | Meaning | What to do | | :- | :- | :- | | **5xx** | Something on our side failed, not your file - either we could not assemble the parts, or we assembled them and the step after that failed. **Nothing is deleted** in either case. | Retry the same `complete` call (a few attempts with backoff). It handles both: it will assemble the parts, or - if they were already assembled - adopt the existing object. Do **not** re-upload the bytes. | | **400 about the part list** | A part number or ETag is wrong or missing. We discard the parts for you. | Fix the request and start a new upload. | | **400 about the file** | Empty, wrong type, too large, or no readable preview. The bytes have been deleted. | Fix the file and start a new upload - there is nothing left to abort. | | **403** (quota, permissions) | Rejected *before* we assemble anything, so **your parts are still open**. | Call `abort` yourself, then fix the cause. | | **Success, but you never saw it** | e.g. your request timed out after we finished. | Just call `complete` again - it returns the same upload and is not counted twice against your quota. | ### Giving up **Endpoint:** `POST /api/v1/upload/multipart/abort` with `{ path, uploadId }`. Call it whenever you abandon an upload - unfinished parts occupy storage and count against your usage. If your process dies before it can, transfers left untouched for **7 days** are aborted automatically, but that is a backstop, not your cleanup path. > [!NOTE] > > A single upload is capped at **10 000 parts**, and the file still has to fit your plan's > video limit (see [Limits](/api-reference/limits)). *** ## Method 2: Direct Upload One presigned `PUT` for the whole file. Simpler than multipart, but a failure means starting over, and the hard ceiling is **5 GiB** (a single storage request cannot carry more). Above that we reject at init and point you to multipart. ### Step 1: Initialize **Endpoint:** `POST /api/v1/upload/init` ```json theme={null} // Request { "fileName": "viral-video.mp4", "mimeType": "video/mp4", "fileSize": 1073741824, // optional, but send it - lets us reject oversized files up front "teamId": "..." } ``` **Response:** a presigned `url` and a `path`. ```json theme={null} { "url": "https://...", "path": "team-id/9f8e7d6c.mp4" } ``` > [!NOTE] > > **The pre-signed URL expires after 30 minutes.** If you don't start uploading within that window, you'll need to initialize again. ### Step 2: Push the Bytes Send the raw binary file to the `url` we gave you. Use `PUT`. > [!NOTE] > > **Important:** Do not wrap this in JSON or Multipart form. Just send the raw bytes. ```bash theme={null} curl -X PUT "https://..." \ --upload-file ./viral-video.mp4 ``` ### Step 3: Finalize Tell us you're done so we can register the file in our system. **Endpoint:** `POST /api/v1/upload/finalize` ```json theme={null} // Request { "path": "team-id/9f8e7d6c.mp4", // from Step 1 "teamId": "..." } ``` **Response:** You get an `id` (e.g., `upload_abc123`). **This is the ID you use when creating a post.** *** ## Method 3: Simple Upload (The Lazy Way) Good for images or small clips. Uses standard `multipart/form-data`. **Endpoint:** `POST /api/v1/upload` ```bash theme={null} curl -X POST "https://api.bundle.social/api/v1/upload" \ -H "x-api-key: YOUR_KEY" \ -F "file=@./meme.jpg" \ -F "teamId=YOUR_TEAM_ID" ``` **Response:** Returns the `id` immediately. *** ## Upload from a URL Register media by passing a **public HTTP(S) URL** instead of uploading the bytes yourself: `POST /api/v1/upload/from-url` (also exposed in the SDKs and the MCP server). We fetch the asset **server-side** and register it like any other upload. | Detail | Value | | :- | :- | | Max size | **1 GB** | | Download timeout | **60 seconds** | | Best for | Small / medium files (typical short-form / feed content) | | Not for | Large videos - we fetch the file server-side and cap it at **1 GB / 60 s**. For bigger files, upload the bytes yourself with [Multipart Upload](#method-1-multipart-upload-the-pro-way). | The response is the upload itself. Use `id` in `uploadIds`, and `url` wherever a field expects a hosted media URL, such as a TikTok `thumbnail`: ```json theme={null} { "id": "upl_123", "type": "image", "url": "https://private-storage.bundle.social/team_123/cover.jpg", "width": 1080, "height": 1920, "mime": "image/jpeg" } ``` > [!NOTE] > > The **1 GB / 60 s** limit applies only to URL imports, because we download the file for you. Uploads where you send the bytes stream straight to storage and allow up to your full video limit. *** ## Supported Formats & Limits | Type | Formats | Max Size | | :- | :- | :- | | **Images** | JPG, PNG, GIF | 25 MB | | **Videos** | MP4, MOV | Platform-dependent (see [Limits](/api-reference/limits)) | | **Documents** | PDF | 100 MB | > [!NOTE] > > The default video ceiling is **5 GB** per file - [talk to us](https://bundle.social/contact) if you need more, which is granted per organization and only applies to Multipart Upload. The max video size also depends on the platform you're posting to: TikTok allows up to 1 GB, YouTube up to 5 GB, while Discord caps at 10 MB. Check [Platform Limits](/api-reference/limits) for the exact numbers per platform. > [!NOTE] > > **Tip:** If you are uploading a picture of your cat (or your mom, we don't judge), Simple Upload is fine. For a 4K podcast clip, use Multipart. *** ## Video Compression You can enable automatic video compression on your organization. When enabled, we'll compress videos larger than 10 MB before they're stored and posted. ### How to enable Video compression is an organization-level setting. You can toggle it from your dashboard or contact us to enable it. Once on, it applies to all uploads across all teams in your org. ### What happens | Setting | Value | | :- | :- | | Threshold | Videos > 10 MB | | Output format | MP4 (H.264 + AAC) | | Quality | CRF 30 (good balance of quality and size) | | Preset | Medium | We're smart about it - if the compressed file ends up **larger** than the original (rare, but it happens with already-compressed videos), we keep the original and toss the compressed version. You always get the smaller file. > [!TIP] > > This is great if your users upload raw or minimally compressed videos. A 500 MB screen recording can often shrink to under 100 MB with no visible quality loss. Your storage costs will thank you - and so will the upload speeds. # Webhooks Source: https://info.bundle.social/api-reference/webhooks We call you when things happen, so you don't have to poll. Real-time post and comment events with signature verification, retries, and auto-disable. Webhooks are how you know if a post actually went live or failed permanently. Instead of polling every few seconds, give us a URL and we'll notify you. > [!NOTE] > > **Prerequisite:** You need an API Key and a URL where we can send POST requests. Webhooks are configured at the **organization** level - all teams under that org share the same webhook endpoints. ## Setup 1. Go to the [Webhooks Dashboard](https://bundle.social/dashboard/organization/webhooks). 2. Add your URL (e.g., `https://api.yourapp.com/webhooks/bundle`). Must be **HTTPS**. 3. Get your **Signing Secret**. > [!TIP] > > **Local Dev:** Use `ngrok` to test locally. `ngrok http 3000`. *** ## Events | Event | When it fires | | :- | :- | | `post.published` | Post finished processing. Check `data.status`: `POSTED` means live, `ERROR` means it failed permanently. | | `post.externally-deleted` | A post was deleted on the platform itself, detected on an analytics refresh. See [Externally Deleted Posts](#externally-deleted-posts-payload). | | `comment.published` | Comment finished processing. Check `data.status`: `POSTED` means published, `ERROR` means it failed permanently. | | `social-account.created` | User connected a new social account | | `social-account.updated` | Social account changed (channel unset, remote disconnection detected, token refresh failed) | | `social-account.deleted` | Social account was disconnected or removed | | `team.created` | A new team was created | | `team.updated` | Team details changed (name, avatar, social accounts added/removed) | | `team.deleted` | A team was deleted | > [!NOTE] > > `team.updated` also fires when a social account is added to or removed from a team - so you don't need to listen to social account events separately if you're already tracking teams. *** ## Payload Structure Every webhook delivery is an HTTP POST with this shape: ```json theme={null} { "type": "post.published", "data": { // ... event-specific payload } } ``` ### Headers We Send | Header | Value | | :- | :- | | `Content-Type` | `application/json` | | `User-Agent` | `bundlesocial` | | `x-signature` | HMAC-SHA256 signature (see [Security](#security-verify-its-us)) | ### Post Events Payload When you receive `post.published`, the `data` field contains the full post object. Use `data.status` to distinguish success from failure. ```json theme={null} { "type": "post.published", "data": { "id": "post_abc123", "title": "My awesome post", "status": "POSTED", "postDate": "2026-01-15T10:00:00.000Z", "postedDate": "2026-01-15T10:00:02.341Z", "teamId": "team_xyz", "organizationId": "org_123", "data": { "INSTAGRAM": { "type": "POST", "text": "Hello world!", "uploadIds": ["upload_456"] } }, "error": null, "errors": null, "errorsVerbose": null, "externalData": { "INSTAGRAM": { "id": "17900000000000000", "permalink": "https://www.instagram.com/p/example/" } }, "retryCount": 0, "createdAt": "2026-01-14T15:30:00.000Z", "updatedAt": "2026-01-15T10:00:02.341Z", "deletedAt": null, "uploads": [ { "upload": { "id": "upload_456", "fileName": "cover.jpg", "mimeType": "image/jpeg", "size": 245000 } } ], "socialAccounts": [ { "socialAccount": { "id": "sa_789", "type": "INSTAGRAM", "username": "mybrand", "displayName": "My Brand" } } ] } } ``` For failed posts, the event type is still `post.published`, but `data.status` is `ERROR` and `data.error`, `data.errors`, or `data.errorsVerbose` contains the failure details. A `POSTED` post can still carry a non-fatal warning in `data.errors`, for example when YouTube rejected the custom thumbnail but the video itself was published. Check `data.status`, not just whether `errors` is empty. ### Externally Deleted Posts Payload `post.externally-deleted` fires when an analytics refresh finds that a post was deleted on the platform (TikTok, YouTube, Instagram and Threads, see [Posts Deleted On The Platform](/api-reference/analytics#posts-deleted-on-the-platform)). It covers posts published through bundle.social and imported posts. `data` is the profile post, plus `teamId` and `socialAccountType`. `data.postId` is the bundle.social post it was published from, or `null` for an imported post. ```json theme={null} { "type": "post.externally-deleted", "data": { "id": "pp_123", "socialAccountId": "sa_789", "postId": "post_abc123", "externalId": "17900000000000000", "permalink": "https://www.instagram.com/p/example/", "publishedAt": "2026-01-15T10:00:02.000Z", "externallyDeletedAt": "2026-02-02T08:14:00.000Z", "teamId": "team_xyz", "socialAccountType": "INSTAGRAM" } } ``` It's sent once per post. `externallyDeletedAt` never changes after that, and the post stops getting analytics refreshes. Platform terms generally require you to delete the post and its stats on your side when you receive it. Webhooks with no event filter receive it automatically, so make sure your handler ignores event types it doesn't know. ### Comment Events Payload ```json theme={null} { "type": "comment.published", "data": { "id": "comment_abc", "status": "POSTED", "internalPostId": "post_abc123", "teamId": "team_xyz", "data": { "INSTAGRAM": { "text": "#growth #mindset" } }, "error": null, "createdAt": "2026-01-15T10:00:05.000Z", "socialAccounts": [ { "socialAccount": { "id": "sa_789", "type": "INSTAGRAM", "username": "mybrand" } } ] } } ``` For failed comments, the event type is still `comment.published`, but `data.status` is `ERROR`. ### Social Account Events Payload ```json theme={null} { "type": "social-account.created", "data": { "id": "sa_789", "type": "INSTAGRAM", "teamId": "team_xyz", "username": "mybrand", "displayName": "My Brand", "avatarUrl": "https://...", "externalId": "17841400000", "channels": [], "createdAt": "2026-01-10T12:00:00.000Z" } } ``` Sensitive fields like `accessToken`, `refreshToken`, `secret`, and `expiresAt` are **never** included in webhook payloads. We're not that reckless. ### Team Events Payload ```json theme={null} { "type": "team.created", "data": { "id": "team_xyz", "name": "Marketing Team", "avatarUrl": "https://...", "organizationId": "org_123", "createdById": "user_456", "createdAt": "2026-01-10T12:00:00.000Z", "organization": { "id": "org_123", "name": "Acme Corp" }, "createdBy": { "id": "user_456", "email": "..." }, "socialAccounts": [] } } ``` *** ## Delivery & Retries We really try to deliver your webhooks. Here's how hard we try: | Setting | Value | | :- | :- | | Timeout | 15 seconds per request | | Max attempts | 3 (initial + 2 retries) | | Backoff | Exponential, starting at 30 seconds | | Concurrency | We process up to 50 deliveries simultaneously | So if your server is down, we'll try 3 times with increasing delays. After that, the event is marked as failed and we move on. We're persistent, not obsessive. ### Auto-Disable (The Safety Net) If your webhook endpoint goes **7 days without a single successful delivery**, we automatically disable it. This protects both of us - we stop wasting resources, and you stop missing events you don't know about. When this happens: * Your webhook is marked as **disabled** and we stop sending events to that URL * We send an **email to the organization owner** and create an **in-app notification** in the dashboard, both linking to the webhooks page * You can re-enable it from the dashboard or API, which resets the 7-day window (so a single failure right after re-enabling won't immediately disable it again) * On the next successful delivery, the failure counter resets to 0 > [!WARNING] > > **Don't let your endpoint stay broken for too long.** If your server is having a bad week, re-enable manually once it's back. Events that happened while disabled are gone - we don't replay them. ### Resending Events Made a mistake in your handler? Event got lost? You can resend any webhook event from the dashboard or via the API. We'll create a fresh delivery attempt with the same payload. Events are kept for [2 days](/api-reference/data-retention#webhook-events) after delivery, so resend within that window. *** ## Remote Disconnection Detection We check every connected social account every **6 hours** to see if it's still valid. If the platform tells us "nope, this token is dead," we start the disconnection flow. ### How It Works 1. Every 6 hours, we validate each connected account against its platform. 2. If the check fails, we retry **3 times** with 10-minute backoff. 3. If all retries fail, we schedule the account for deletion and send you a `social-account.updated` webhook. 4. After the grace period, we remove the account (fires `social-account.deleted`). Automatic remote disconnection scanning currently covers Meta accounts: Facebook, Instagram, and Threads. For other platforms, use `POST /api/v1/social-account/connection-check` when your user opens account settings or before showing a reconnect warning. ### The `social-account.updated` Payload When we detect a disconnection, the webhook includes a `socialAction` object with the details: ```json theme={null} { "type": "social-account.updated", "data": { "id": "sa_789", "type": "INSTAGRAM", "teamId": "team_xyz", "username": "mybrand", "socialAction": { "type": "disconnect-check", "source": "system", "checkedAt": "2026-02-20T14:30:00.000Z", "details": { "status": "error", "code": "REMOTE_DISCONNECT_DELETION_SCHEDULED", "message": "Account failed validation after 3 attempts", "errorCategory": "UNAUTHORIZED", "providerError": { "httpStatus": 400, "code": "190", "subcode": "460", "message": "Error validating access token: The session has been invalidated because the user changed their password.", "type": "OAuthException", "fbtraceId": "AbCdEfGh123" }, "attemptNumber": 3, "attemptsTotal": 3, "scheduledForDeletion": true, "deleteAccountAfter": 6, "deleteOn": "2026-02-20T20:30:00.000Z" } } } } ``` `details.errorCategory` is `UNAUTHORIZED` (the token is no longer valid) or `TRANSIENT_OR_UNKNOWN`. `details.providerError` is what the platform answered, when we have it: `httpStatus` and `message`, plus `code`, `subcode`, `type` and `fbtraceId` when the platform provides them (Meta does; quote `fbtraceId` when you contact Meta support). Every field is optional, so check before reading. ### Token Refresh Failures We also refresh access tokens before they expire. When a refresh keeps failing, you get a `social-account.updated` with `socialAction.type: "refresh"` and the same `details` shape as above, plus `refreshBy` (when the current token expires, if the platform has a deadline). * **One webhook per failed refresh job.** The in-between retries don't send anything, so `attemptNumber` always equals `attemptsTotal`. * **After a final failure we wait 6 hours** before trying that account again. Timeouts, `429` and `502`-`504` from the platform are retried sooner. * **TikTok:** `providerError.code` is TikTok's error code and `providerError.type` is our reading of it: `DEAD_TOKEN` (the refresh token is expired or invalid, the user has to reconnect), `TRANSIENT` (rate limit or a TikTok-side error) or `UNKNOWN`. ### Status Codes | Code | Meaning | | :- | :- | | `REMOTE_DISCONNECT_DELETION_SCHEDULED` | All retries failed. Account is scheduled for deletion. | | `REMOTE_DISCONNECT_UNAUTHORIZED_WARNING` | Token refresh failed with an auth error (401, expired token, etc.). | | `REMOTE_DISCONNECT_REAUTH_REQUIRED` | Connection failed for another reason. User should reconnect. | | `REMOTE_DISCONNECT_TRANSIENT_OR_UNKNOWN` | A check failed for a reason that doesn't look like an auth error. We keep retrying. | ### The `deleteOn` Grace Period When an account is scheduled for deletion, `deleteOn` tells you exactly when it will be removed. The delay is controlled by `deleteAccountAfter` on your organization settings (0-168 hours), with a floor of **48 hours**. * **Default: 48 hours** - you have two days to notify your user before the account is gone. * **Values below 48 (including 0) still give 48 hours.** Set it higher, up to 168 hours (7 days), for a longer window. **Why does this matter?** When an account is deleted: * It's removed from all draft and scheduled posts. * Posts that only had this account become drafts. * If the user reconnects before `deleteOn`, the account stays. When `social-account.updated` arrives with a `deleteOn`, show a "hey, reconnect your Instagram" banner right away. If the user reconnects before `deleteOn`, nothing is removed. Need more than two days? Raise `deleteAccountAfter`, up to 168 hours. *** ## Best Practices 1. **Respond fast.** Return a `200` within 15 seconds. Do heavy processing asynchronously. If you take too long, we'll count it as a failure. 2. **Be idempotent.** We might deliver the same event twice in rare cases (retries, race conditions). Deduplicate with the event `type`, `data.id`, `data.status`, and relevant timestamps. 3. **Verify signatures.** Always. No exceptions. Even in development. See the [SDK](/api-reference/sdk) for built-in signature verification, or check the [Swagger](/api-reference/openapi) for the raw details. 4. **Use HTTPS.** We only send webhooks to HTTPS URLs. Sorry, `http://localhost` works via ngrok though. 5. **Monitor your failures.** If your endpoint has been failing for days with no successful deliveries, fix it before the 7-day auto-disable kicks in. You'll get an email + dashboard notification when it does, but catching it sooner is better. *** ## Using a Hosted Webhook Gateway We recommend the [Hookdeck Event Gateway](https://hookdeck.com/event-gateway) with its [bundle.social source type](https://hookdeck.com/docs/sources?type=BUNDLE_SOCIAL#source-types) to handle the best practices for you: 1. **Respond fast.** Hookdeck acknowledges every bundle.social delivery immediately and queues it for your endpoint, so slow processing doesn't count as a failed delivery. 2. **Be idempotent.** Deduplication rules drop repeated deliveries that arrive within a window of up to an hour, before they reach your endpoint. We still recommend checking for duplicates in your webhook handler as a best practice. 3. **Verify signatures.** The bundle.social source type verifies the `x-signature` header with your Signing Secret. Your handler then verifies Hookdeck's signature, the same check for every webhook source you route through Hookdeck. 4. **Use HTTPS.** You get an HTTPS URL, and the Hookdeck CLI forwards events to `localhost` during development. 5. **Monitor your failures.** With a retry rule, failed deliveries to your endpoint are retried automatically. They also raise alerts and can be retried again once you've fixed the problem, so your bundle.social webhook stays enabled. 6. **Test with sample events.** [Hookdeck Inspect's bundle.social page](https://inspect.hookdeck.com/webhooks/bundle-social) gives you a URL and sends sample bundle.social webhooks to it, so you can see each payload and build your handler before you connect a real account. The samples aren't signed, so use them to test how you handle events, not signature verification. For a full walkthrough, see Hookdeck's [guide to bundle.social webhooks](https://hookdeck.com/webhooks/platforms/guide-to-bundle-social-webhooks-features-and-best-practices). # Changelog Source: https://info.bundle.social/changelog Stay up to date with the latest changes to our app and API. New platform integrations, endpoints, analytics, and breaking changes, newest first. **2026-11-17** **Page size on list endpoints:** every list endpoint takes `limit` from 1 to 1000 and an `offset` of 0 or more, both whole numbers. `0` or an empty `limit` means the endpoint's default (10 on most lists, 20 or 50 on CSV and comment imports, reviews and recommendations). A `limit` above 1000 now returns `400` with `limit: must be at most 1000. Use offset to fetch more.`, and a negative or fractional value returns `400` too. Lists that capped `limit` at 100 or 500 (reviews, recommendations, conversations, flow executions) now go up to 1000. Validation errors on query parameters name the field that failed. **Uploads:** a connection dropped while we save a file to storage is retried on our side. If it still fails, `POST /api/v1/upload` returns `500` instead of `400`, so it no longer looks like a problem with your file. You can send it again; in rare cases the first attempt was saved too and you end up with an extra upload you can delete. **First comments:** a post's `firstComment` is now published on the platforms where the post went live, even if another platform in the same post failed. It used to stay unpublished. **Snapchat uploads:** media is sent in smaller parts with a longer timeout, and each part is retried, so large Snapchat videos fail less often on timeouts. **TikTok Spark Ads codes:** turn on ad authorization for a public TikTok post and get its Spark Ads code to hand to an advertiser, with `GET`, `POST` and `DELETE /api/v1/misc/tiktok/ad-authorization` and `POST /api/v1/misc/tiktok/ad-authorization/extend`. Address the post with `postId` or, for posts published outside bundle.social, `platformPostId`. No new TikTok permissions are needed. See [Spark Ads Authorization Code](/api-reference/platforms/tiktok#spark-ads-authorization-code). **Threads ghost posts:** `data.THREADS.isGhostPost: true` publishes a text post that Threads archives after 24 hours. Ghost posts are text only: media, polls, GIFs, link attachments, a topic tag, reply control, country restrictions and Instagram Story cross-sharing return `400`. See [Ghost Posts](/api-reference/platforms/threads#ghost-posts). **Snapchat Public Profiles of Snap Business organizations:** connect with `snapchatConnectionMethod: "BUSINESS"` to pick any Public Profile of the organizations the login belongs to with `set-channel`. `PERSONAL` stays the default. Portal links accept it too, or let the user choose when it's left out. A login with no role on any profile ends with `snapchat-no-business-profiles`. See [Connection Methods](/api-reference/platforms/snapchat#connection-methods). **Interrupted publishes have a reason:** a publish cut off on our side before the platform answered now ends with `PUBLISH:INTERRUPTED` and says whether the post may already be live, instead of an `ERROR` with no reason. See [Interrupted Publishes](/api-reference/errors#interrupted-publishes). **Clearer Meta errors:** the per-Page posting limit (`Meta:368:1390008`), blocked content (`Meta:368:1404132`) and the Facebook login checkpoint (`Meta:190:459`) get their own `userFacingMessage` in any language Meta answers in. Token errors that a reconnect can't fix no longer tell the user to reconnect. **Fewer failed video uploads:** Facebook, X and LinkedIn videos are read from storage in chunks with retries, so a connection dropped while reading the file is retried instead of failing the post with `NET:ECONNRESET`. **Link in bio:** each click is counted once. Clicks were saved several times a night before, and the extra rows have been removed. Clicks on an item that isn't in the bio return `404`. **2026-11-10** **YouTube Shorts thumbnails:** a Short's custom thumbnail is now set after YouTube finishes processing the video, the way YouTube requires. The post is `POSTED` right away with `externalData.YOUTUBE.thumbnailStatus: "PENDING"`, which becomes `APPLIED` or `FAILED` later. See [Custom Thumbnails](/api-reference/platforms/youtube#custom-thumbnails). **Webhook events are kept for 2 days** after delivery (was 7). Events still waiting for delivery are kept until they are delivered. Resend within that window. See [Data Retention](/api-reference/data-retention#webhook-events). **2026-11-08** **LinkedIn analytics:** * Personal posts report `saves`, and raw `metrics` add `clicks`, `sends`, `followersGained` and `profileViews`. * Account snapshots carry a `daily` series for the last 364 days, from `GET /api/v1/analytics/social-account/raw`. * A personal profile's headline is stored in `bio`. See [LinkedIn](/api-reference/platforms/linkedin#raw-analytics). **Google review replies show their moderation state:** after you reply, we check Google for `reviewReplyState` and `reviewReplyPolicyViolation`, and `reviewReplyStateCheckedAt` says when we last asked. See [Reply Moderation State](/api-reference/platforms/google-business-reviews#reply-moderation-state). **Daily posting limits are counted exactly** for the accounts in each request. A cached count could let a post through just over the limit before. **2026-11-06** **Norwegian:** the app and the hosted connect portal (`language: "no"`) are available in Norwegian. **2026-11-05** **YouTube uploads paused by YouTube's daily quota** resume right at YouTube's midnight Pacific reset, not up to 10 minutes later. **2026-11-04** **New webhook `post.externally-deleted`:** sent once when an analytics refresh finds a post was deleted on TikTok, YouTube, Instagram or Threads. The payload is the profile post with `externallyDeletedAt`, `teamId` and `socialAccountType`. Webhooks without an event filter get it automatically, so make sure your handler ignores types it doesn't know. See [Externally Deleted Posts](/api-reference/webhooks#externally-deleted-posts-payload). **Pinterest carousel Pins:** 2 to 5 images in `uploadIds` publish as one carousel Pin, with optional per-slide `title`, `description` and `link` in `carouselItems`. Images must share one aspect ratio. Post history import now reads carousel slides, and image Pins report impressions as `views` instead of `0`. See [Carousel Pins](/api-reference/platforms/pinterest#carousel-pins). **Why Facebook found no Page:** when a Facebook or Instagram (through Facebook) connection ends with `facebook-not-enough-pages` or `instagram-not-enough-accounts`, a new `errorReason` parameter tells you why (two-factor authentication, Page not selected, no content access and more). Pages without a Page token are no longer offered. Refreshing Facebook channels that finds no usable Page now returns `400` and keeps the stored channels. See [Error Reasons](/api-reference/connect-social-accounts/callbacks#error-reasons-facebook-and-instagram). **Instagram follow status in Direct Messages:** conversations have `platformData.participantFollowsBusiness` and `platformData.businessFollowsParticipant`. See [Conversations](/api-reference/direct-messages/conversations). **Fewer `social-account.updated` webhooks:** * A failed token refresh now sends one webhook per failed job instead of one per attempt, so `attemptNumber` always equals `attemptsTotal`. The account is tried again after 6 hours. For TikTok, `providerError` includes TikTok's `code` and a `type` (`DEAD_TOKEN`, `TRANSIENT` or `UNKNOWN`). See [Token Refresh Failures](/api-reference/webhooks#token-refresh-failures). * Avatar updates no longer fire a webhook when the image didn't change. `avatarUrl` is our stored copy of the image, unless storing it failed. **2026-11-03** **LinkedIn polls:** publish a poll with `data.LINKEDIN.poll`: a question, 2-4 options and a duration. Polls can't include media or a `link`. See [LinkedIn polls](/api-reference/platforms/linkedin#polls). **Google Business:** a location reachable through several Google accounts or groups is listed once in `channels`, and refreshing channels keeps the selected location when Google moves it. See [Google Business](/api-reference/platforms/google-business). **2026-11-02** **Comments on posts published outside bundle.social:** with Direct Messages or Automations turned on, new Instagram, Facebook and TikTok comments arrive in real time on every post, including posts published directly in the app. In `comment.received` they have `postId: null` and a `comment.importedPostId`. See [Comments](/api-reference/comments). **Comment automations on all posts:** `postId` is now optional in a `COMMENT_CREATED` trigger. Without it the flow covers every post on the account; a post's own matching flow takes priority. See [Comment Flows](/api-reference/automations/how-flows-behave#comment-flows). **Message and automation usage:** new `GET /api/v1/organization/usage/messages` shows messages and automation runs used and allowed this month, per account. See [Rate Limits](/api-reference/rate-limits#check-monthly-message-and-automation-usage). **TikTok:** * Location tags with `locationId` and `locationName`, searchable with `GET /api/v1/misc/tiktok/locations`. See [Location tags](/api-reference/platforms/tiktok#location-tags). * Photo Mode: up to 35 images (was 10), captions up to 4,000 characters and a `title` of up to 90. **LinkedIn analytics:** organization video posts now report `views` and `viewsUnique` instead of `0`, and raw data adds video watch time. See [LinkedIn](/api-reference/platforms/linkedin). **Snapchat:** videos can be up to 400 MB (was 100 MB). See [Snapchat](/api-reference/platforms/snapchat). **YouTube:** uploads are now capped per organization per day (`YT:orgDailyUploadLimit`), and when YouTube's own quota runs out they fail right away with `YT:uploadCapacityExhausted`. See [Errors](/api-reference/errors#youtube). **2026-10-29** **Threads profile views over 2 years again:** profile `views` is summed over the last 2 years (never before April 13, 2024) instead of 365 days. We now read the series in 90-day slices, because Threads kept failing on long views series for some profiles, which stopped their daily account analytics. Affected profiles resume on the next daily run. See [Threads](/api-reference/platforms/threads#profile-analytics). **An expired token no longer stops account analytics:** a failed refresh caused by an expired or revoked token is now retried on the next daily run instead of switching account analytics off. Accounts switched off this way during the token refresh problem on October 8-9 (mostly YouTube) are collecting again. See [When collection stops for an account](/api-reference/analytics#when-collection-stops-for-an-account). **Facebook Page posts accept up to 10 images**, as documented, instead of 4. See [Facebook](/api-reference/platforms/facebook). **TikTok comment import on a deleted video:** the import now ends right away with `status: "FAILED"` instead of retrying. Comments already imported are kept. **2026-10-28** **Direct Messages and Automations are out of beta.** Both are part of the paid plans and are turned on per organization on request: [contact us](https://bundle.social/contact) with your organization ID. Access is now per platform: one switch for Instagram and Facebook (DMs and automations), a separate one for TikTok automations, so a TikTok-only setup no longer needs the Meta switch and the other way around. **Status code change:** while access is not turned on, the [Direct Messages](/api-reference/direct-messages) and [Automations](/api-reference/automations) endpoints now answer `403` with a message that says how to request access, instead of `404`. A wrong ID still returns `404`. If your integration treated `404` as "not enabled", check for `403` as well. **Automations across organizations:** `POST /api/v1/automations/copy` now returns `{ items, total, skipped }` and leaves out flows whose platform isn't turned on; `GET /api/v1/automations` hides them too. See [Managing Flows](/api-reference/automations/managing-flows). **Instagram tags and location no longer fail a post:** rejected tags, collaborators or `locationId` are dropped and the post is published, with a warning in `errors.INSTAGRAM`. See [Instagram](/api-reference/platforms/instagram). **Facebook video titles:** a `mediaTitle` over 255 bytes is cut to fit instead of failing the publish. **Comment import:** an empty re-import no longer marks the post's stored comments as deleted, and TikTok errors are no longer read as zero comments. **2026-10-27** **Post history import on TikTok:** imports no longer stop after 3 pages of posts you already have. See [What `count` means](/api-reference/import-posts#what-count-means-and-onlylatest). **2026-10-25** **TikTok posting options:** new `GET /api/v1/misc/tiktok/post-settings?teamId=...` returns the privacy levels the account accepts (`privacyLevelOptions`), whether comments, Duets and Stitches can be turned on (`commentDisabled`, `duetDisabled`, `stitchDisabled`) and the longest video it can publish (`maxVideoPostDurationSec`), read live from TikTok. Use it to build your composer's options. See [TikTok](/api-reference/platforms/tiktok#posting-options-of-an-account). **Instagram story replies and mentions in Direct Messages:** a reply to the account's story carries `platformData.storyReply` (`storyId`, `url`, `linkStickerUrl`), and a story that mentions the account arrives as an attachment with `type: "STORY_MENTION"`. Story URLs expire with the story. When a message is unsent, `storyReply` is cleared along with `text` and `attachments`. See [Story replies and mentions](/api-reference/direct-messages/conversations#story-replies-and-mentions). **YouTube post visibility:** profile posts now have `extraData.visibility` (`PUBLIC`, `UNLISTED`, `PRIVATE`), set on import and updated on every analytics refresh. Private and unlisted videos keep refreshing. See [YouTube](/api-reference/platforms/youtube#quirks). **Raw analytics:** * **Instagram:** `demographics.follows_and_unfollows` is now requested by follow type, with a parsed `demographics.follows_and_unfollows_by_follow_type` (`follows`, `unfollows`, `unknown`; `null` under 100 followers). See [Instagram](/api-reference/platforms/instagram). * **Facebook Pages:** `pageInsights` adds `page_daily_follows_unique`, `page_daily_unfollows_unique`, `page_post_engagements` and `page_total_actions`. * **Facebook views breakdown:** Page and post raw analytics include `mediaViewBreakdowns`, splitting views into paid vs organic (`isFromAds`) and followers vs non-followers (`isFromFollowers`). Views only, not unique reach. See [Facebook](/api-reference/platforms/facebook#raw-analytics). **Facebook analytics:** * Reels now get reach (`impressionsUnique`), read from the reel's page post. * Story analytics (views, unique views) are read during post history import, since stories expire after 24 hours. Force refresh of story analytics is still not supported. **Post import:** Facebook imports skip unpublished video-library items (drafts, scheduled, ad-only). With imported-posts analytics enabled, imported Facebook and Instagram posts get their first analytics from the regular refresh instead of a placeholder snapshot with zero reach. See [Imported post analytics](/api-reference/import-posts#imported-post-analytics). **Webhooks:** `socialAction.details.providerError` in `social-account.updated` now includes the platform's `code`, `subcode`, `type` and `fbtraceId` when the platform provides them, next to `message` and `httpStatus`. See [Remote Disconnection Detection](/api-reference/webhooks#remote-disconnection-detection). **Threads:** the profile post count retries Threads' random errors instead of failing. **Hosted connect portal:** now loads on older iOS Safari (iOS 15). **Docs:** how to use `referenceKey` for safe post-create retries. See [Safe retries](/api-reference/examples#safe-retries-with-referencekey). **2026-10-24** **Meta reliability:** Facebook, Instagram and Threads calls hold up better under load. The connection pool is bounded, every request has an end-to-end deadline, and token checks are retried on transient Meta errors. **Threads account analytics:** `views` is now summed over the last 365 days instead of about 2 years, because Threads fails on the longer series. Account-level Threads `views` drop once as a result. Likes, replies, reposts, quotes and followers are unchanged. See [Threads](/api-reference/platforms/threads). **API errors:** endpoints can now return `503` or `504` when a platform is temporarily unavailable or timed out, instead of a generic `500`. Both are safe to retry with backoff. See [HTTP Status Codes](/api-reference/errors#http-status-codes). **Direct Messages setup:** messaging now requires the `pages_manage_metadata` permission; without it, enabling messaging returns `400` instead of `502`. Reconnect accounts connected long ago. See [Setup](/api-reference/direct-messages/setup). **2026-10-19** **CSV import:** * Imports no longer hang when a media URL stops sending data mid-download. The row fails with an error and the import continues. * A scheduled row whose `postDate` is more than 10 minutes in the past is rejected before its media is downloaded. * A retried import resumes after the rows that already have a result instead of creating them again. See [Bulk Post from CSV](/api-reference/bulk-posts-csv). **Hosted connect portal:** opening a new link in a browser that previously opened an expired link for the same team no longer shows "Link has expired". **2026-10-17** **Instagram and Threads: posts deleted on the platform:** posts you delete on Instagram or Threads now get `externallyDeletedAt` set on the next analytics refresh and stop being refreshed, like TikTok and YouTube already did. Applies to published and imported posts. Instagram and Threads return the same error for a deleted post and for one the account can't access, so a post is only marked when it's also missing from the account's own post list. Very old posts (beyond the account's latest \~500 on Instagram, \~1,000 on Threads) aren't checked. See [Analytics](/api-reference/analytics). **Threads analytics:** fixed account and post statistics failing with `Something went wrong, please try again later.` Threads' insights API currently fails at random on a share of requests; we now retry those reads automatically, so stats that were stuck fill in on the next refresh. Publishing wasn't affected. **2026-10-16** **Instagram Stories import:** Stories imported through post history now come with their numbers (views, reach, replies, shares), read from Instagram at import time. A Story that Instagram has no insights for is imported without analytics instead of with zeros. **Threads:** reposts imported before the Oct 14 fix (which never get statistics) are removed from imported posts and no longer refreshed. **2026-10-15** **Facebook and Instagram comments:** fixed comments occasionally being posted twice. When creating a comment took too long (usually while Facebook built a link preview), our request timed out, the comment still got created, and the automatic retry posted it again. Before an automatic retry we now check whether the comment already exists on the post (or under the parent comment) and, if it does, adopt it instead of posting again; if that check can't run, the retry waits rather than risk a duplicate. Comment creation also gets more time, so these retries are much rarer. **Instagram reconnect:** a reconnect (`reconnect: true`) now always asks Instagram for a fresh login, so it can't silently reuse a different account the browser is logged into. **2026-10-14** **Instagram reconnect in place:** `POST /api/v1/social-account/connect` accepts `reconnect: true` to re-authorize the Instagram account already connected to a team, instead of disconnecting it. Tokens and permissions are refreshed; the account, its draft and scheduled posts stay. In the dashboard and hosted portal, open **Disconnect** and choose **Reconnect**. Supported for Instagram connected with Instagram login (`instagramConnectionMethod: "INSTAGRAM"`); the user must log in with the same account (`instagram-reconnect-different-account` otherwise). See [OAuth Options](/api-reference/connect-social-accounts/oauth-options#reconnect). **Instagram login:** connecting now fails with `instagram-not-enough-permissions` when the publish permission isn't granted, instead of connecting an account that can't publish. **Google Business:** * An unticked "Google Business listings" permission on the consent screen now returns `google-business-not-enough-permissions` instead of the generic `google-business-callback`. See [Callback Parameters](/api-reference/connect-social-accounts/callbacks). * `userId` is always Google's own account id; a connection without one now fails instead of storing a placeholder. * `refresh-channels` clears the selected location when the login no longer has access to it, so the account asks for a new one. * Docs: `OFFER` posts need `eventStartDate` and at least one offer field, and can't have a call-to-action button. See [Google Business](/api-reference/platforms/google-business). **Threads:** reposts no longer count toward the profile's post count and aren't imported as your own posts. **Pinterest:** * Per-pin raw analytics are now stored, so the raw endpoints return pin clicks, outbound clicks, impressions and saves (from the next refresh). * Video Pins now get Pinterest's video metrics (`VIDEO_START`, `VIDEO_MRC_VIEW`, watch time), so `views` is filled for video Pins. **TikTok + other platforms:** a post no longer ends in `ERROR` when TikTok confirms publication a few seconds after our first status check, while the other platforms are still publishing. **2026-10-13** **Deprecation:** the `teams` array in `GET /api/v1/organization` is deprecated and will be **removed on November 15, 2026**. It isn't paginated and gets slow for organizations with many teams. List teams with the paginated `GET /api/v1/team` instead (`offset`, `limit`, optional `search`; returns `{ items, total }`). The rest of the organization response stays the same. See [Finding your team IDs](/api-reference/introduction#finding-your-team-ids). **Post import:** new `onlyLatest` option. With `onlyLatest: true`, an import checks only the latest `count` posts and imports the ones you don't have yet, so a daily sync with nothing new imports nothing and uses none of your limit. Without it, `count` still means "`count` posts you don't have yet", going further back if needed. See [What `count` means](/api-reference/import-posts#what-count-means-and-onlylatest). **YouTube thumbnails:** when YouTube rejects a custom thumbnail, we now retry it a few times (YouTube often refuses it while a new video is still processing). If it still fails, the post stays `POSTED` and YouTube's reason shows up in `errors.YOUTUBE`, instead of the thumbnail silently going missing. **2026-10-10** Google review imports: `count` is now the number of **new** reviews to import. Reviews you already have are refreshed but skipped, so re-running an import continues into older reviews until it has `count` new ones or Google has no more, instead of stopping after the newest page. Only new reviews use up the monthly import limit. See [Google Business Reviews](/api-reference/platforms/google-business-reviews). YouTube: Shorts are now correctly flagged (`contentType: "SHORTS"`, `isShort: true`) and get `/shorts/` links. Re-running a post history import also updates `permalink` and `extraData` on posts you already imported, so existing Shorts pick up the right link. Instagram raw analytics: `reachByFollowType` now covers the last 30 days, the same window as `totals30d`, instead of only the last 24 hours. **2026-10-09** Audience demographics in raw analytics, across more platforms: * **YouTube**: channel-level age × gender and countries (last 365 days) under `demographics`. * **Instagram**: combined follower age × gender (`follower_demographics_age_gender`) and hourly follower activity (`onlineFollowers`, accounts with 100+ followers). * **TikTok**: hourly follower activity (`audience_activity`). * **Threads**: follower country, city, age, and gender under `followerDemographics` (profiles with 100+ followers). Collected with the same switch as Instagram demographics. * **LinkedIn Pages**: lifetime follower breakdowns by country, region, industry, seniority, job function, and company size under `followerStatistics`. * **Snapchat**: viewer age × gender and countries under `demographics`. YouTube post analytics: lifetime `shares`, `estimatedMinutesWatched`, `averageViewDuration`, and `averageViewPercentage` per video under `lifetimeTotals`, and the normalized `shares` metric now uses the real number instead of 0. Shorts are flagged with `contentType` / `isShort`, and imported Shorts link to `/shorts/`. Facebook post analytics: shares also read the post insights where Meta provides them, and the higher of the two counts is used, so shares missing from the post's share count show up. Pinterest account analytics: `postCount` is the account's real total pin count, and follower/following counts are no longer capped on larger accounts. Facebook post history import no longer fails when the Page has items without an ID (for example a live Story); those items are skipped. Connected accounts now renew their access tokens more reliably, fixing a period where some YouTube, Google Business, Snapchat, and Bluesky posts failed with authentication errors. Dashboard analytics: total charts (like followers) zoom to the actual range and show the scale, so small day-to-day changes are visible. **2026-10-07** Reddit: the subreddit list now loads every subreddit the account belongs to, not just the first page. Hosted connect portal: link expiry is now decided by our API instead of the device clock, so links no longer show as expired on devices with a wrong time. **2026-10-06** Facebook Page mentions: `GET /api/v1/misc/facebook/pages` finds a Page by URL, `@handle`, ID, or name, so you can tag it in a post with `@[pageId]`. See [Page Mentions](/api-reference/platforms/facebook#page-mentions). TikTok raw analytics: follower genders and countries (`audience_genders`, `audience_countries`). Instagram (Instagram Login): fixed an "Invalid scope" error when connecting while logged out of Instagram. **2026-10-02** TikTok: a custom `thumbnail` must be an image uploaded to bundle.social. Other URLs are rejected with a `400` up front, since TikTok only accepts covers from verified domains. **2026-10-01** **Reddit and Discord:** revoked access now returns `401` and goes through the normal disconnect flow with a `deleteOn`. See [Remote Disconnection Detection](/api-reference/webhooks#remote-disconnection-detection). **LinkedIn force refresh:** LinkedIn's own `4xx` answers (for example when it has no statistics for a post) are passed through instead of a `500`. **`forceBrowserOAuth`:** now makes Instagram ask for a fresh login; in the hosted portal it applies only on iPhone and iPad. See [forceBrowserOAuth](/api-reference/connect-social-accounts/oauth-options#forcebrowseroauth). **2026-09-30** Instagram analytics: posts Instagram has no insights for (published before the account switched to professional, or too few viewers) now return no data instead of a row of zeros. Posts that can never have insights stop being refreshed, and a forced refresh returns `400` with Meta's reason. Snapchat: connecting an account without a Public Profile now fails with a clear "no Public Profile" message. Saved Stories are documented, with a Troubleshooting table for common Snapchat errors. Bluesky video: we check Bluesky's upload limits before each video upload, so refusals come back with Bluesky's reason (for example an unverified email or the daily video limit) instead of `http_401`. The daily limit is retried. Comments: `POST /comment` returns `404` for a post that doesn't exist or was deleted, and clear errors when the target post isn't published on the platform yet. X analytics are documented: available on demand through the force endpoints, billed from X credits. Upload retention is documented as it works: unused uploads are cleaned up 14 days after upload or after the last post using them finished, and deleted uploads are kept for 2 days. DMs: reactions and marking a conversation as read don't count toward the monthly message limit. `copyTeamId` was removed from `POST /team`. It never had an effect; requests that still send it keep working. **2026-09-26** Direct Messages and Automations are available through the public API: read and answer Instagram and Facebook DMs (including private replies to comments), and build comment and DM automation flows. Automations also cover TikTok comments (public reply and like). Both are enabled per organization on request. See [Direct Messages](/api-reference/direct-messages) and [Automations](/api-reference/automations). Snapchat Stories: `storyDuration` (`ONE_DAY`, `TWO_DAYS`, `THREE_DAYS`, `ONE_WEEK`) sets how long a Story stays visible. Snapchat's default applies when it's omitted, and `ONE_WEEK` requires Snapchat+. Instagram raw analytics: profile link taps broken down by contact button type (last 30 days), collected with the raw Instagram demographics switch. Bluesky: URLs in post text become clickable links, including ones written without `https://`, and work alongside hashtags. LinkedIn post history import: imported posts include their image and video media and thumbnails, and single-image and single-video posts get the right post type. **2026-09-23** **Post analytics refresh by post age:** recent posts follow your refresh interval, posts up to 30 days old refresh daily and older ones weekly. See [Default Refresh](/api-reference/analytics#default-refresh). **Publishing with rejected media:** the post now fails right away instead of after 3 attempts. **2026-09-18** X reposts: `POST /api/v1/misc/twitter/retweet` reposts any X post from a connected account and `DELETE /api/v1/misc/twitter/retweet` undoes it. Billed from X credits once per post, per account, per UTC day. X: videos longer than 140 seconds are uploaded with X's long-video category, so accounts allowed to post longer videos can publish them. Facebook post analytics: video posts and Reels are recognized as videos and read from video insights. Raw post analytics also include more video metrics and clicks broken down by type (`post_clicks_by_type`). Facebook and Instagram accounts using Page tokens that don't expire are no longer asked to reconnect. Google Business Profile: fixed deleting media. An invalid media ID now returns a clear error. **2026-09-14** TikTok video posts: a custom `thumbnail` is now sent to TikTok as the video cover, and the post composer has a cover picker for videos. `thumbnail` on `IMAGE` posts is rejected. **2026-09-11** Forced analytics refreshes: the limit is now 6 per social account and 6 per post in a rolling 24 hours, up from 5, and can be raised per organization up to 48. See [Analytics](/api-reference/analytics). TikTok comments: comment text (including `firstComment`) can be up to 1,200 characters, up from 150. New TikTok comments can also be imported automatically as they arrive; this is off by default and enabled per organization on request. Social accounts that lose access are now kept for at least 48 hours before they're removed, instead of within minutes, so there's time to reconnect. **2026-09-09** Social accounts now return `userEmail`, the email of the connected platform account when the platform shares it. Facebook video posts: fixed first comments and publishing failing while Facebook was still processing the video. Dashboard: an alert when your subscription payment is past due, unpaid, or incomplete, with a button to update your payment details. **2026-09-05** Snapchat Saved Stories: `type: "SAVED_STORY"` publishes up to 20 images and videos as one Saved Story. A `title` (max 45 characters) is required, and the snaps together can run up to 5 minutes. See [Snapchat](/api-reference/platforms/snapchat). Google Business Profile: `GET /api/v1/misc/google-business/location/search-keywords` returns the search terms customers used to find a location, for a `startMonth`-`endMonth` range (`YYYY-MM`). Low-volume keywords come back as a `threshold` instead of an exact `value`. The available-attributes endpoint now returns `lookup`, which tells you whether your `regionCode` and `languageCode` were applied. CSV bulk import: per-platform `FirstComment` columns, media and thumbnail links (including Google Drive links), and validated per-platform post types. See [Bulk Posts via CSV](/api-reference/bulk-posts-csv). Instagram analytics: single-video feed posts are recognized as Reels (which is how Instagram publishes them), so their insights load. LinkedIn analytics: per-post reaction counts come from LinkedIn's reactions list, so they match what LinkedIn shows, and account-level reactions add up to the posts below them. TikTok: posts TikTok reports as `PUBLISH_COMPLETE` are marked published even when TikTok doesn't return a public post ID. **2026-09-02** Facebook text backgrounds: `textFormatPresetId` in `data.FACEBOOK` publishes a `POST` without video on a colored, gradient, or illustrated background. `GET /api/v1/misc/facebook/text-format-presets` lists the presets, and CSV import accepts the preset ID too. Analytics are now part of paid plans. Organizations on the Free plan no longer collect analytics. Instagram raw analytics: `follower_demographics_last_14_days` is now always `null`, since Meta no longer provides it. Use the 30-day demographics instead. Dashboard translation for Arabic, with right-to-left layout. **2026-08-27** X post options in `data.TWITTER`: `poll` (2 to 4 options, 5 minutes to 7 days), `quoteTweetId`, `replyToTweetId`, `subscribersOnly`, `thread` (an explicit list of tweets), `tweetStorm` (auto-split long text, with optional `tweetStormNumbering`), and per-image alt text through `mediaItems`. A poll can't be combined with media, a quote, or a thread. X comments: publish them through `POST /comment`, delete them with `DELETE /api/v1/misc/twitter/comment`, and import X comments and post history. These actions are billed from X credits. Credits: `GET /api/v1/billing/credits/balance` returns your prepaid credit balance, and `POST /api/v1/billing/billable-usage/quote` estimates the cost of a metered X action before you run it. Reddit: fixed post permalinks for profile and subreddit posts. **2026-08-24** Dashboard analytics: redesigned per-platform metric cards. Metrics a platform doesn't report are listed in a "Not reported" card instead of charted as zero. **2026-08-20** Google Business Profile reviews: imported reviews include the owner reply's moderation state (`reviewReplyState`), any `reviewReplyPolicyViolation`, and `reviewReplyUrl`. **2026-08-17** Bluesky connect: `serverUrl` is now optional and defaults to `https://bsky.social`. For Bluesky and Mastodon, an unusable `serverUrl` returns `400` with the reason instead of a generic `500`. Forced analytics refresh: when the platform refuses, the error now carries the platform's reason (for example an expired token, a missing permission, or a rate limit) instead of a generic message. Post analytics requests for a platform that doesn't support post analytics now return a clear error. Google Business Profile account analytics include bookings, food orders, and food menu clicks for eligible locations. `postDate` must now fall between the years 2000 and 2100. Facebook: connecting an account that manages hundreds of Pages is faster and more reliable. **2026-08-11** Multipart uploads for large files: `POST /api/v1/upload/multipart/init`, `/sign`, `/complete`, and `/abort` upload a file in parts, in parallel. See [Upload Content](/api-reference/upload-content). Facebook connect now finds Pages managed through Business portfolios. Instagram captions can be up to 2,200 characters, up from 2,000. Facebook raw post analytics: more video metrics (complete views, unique viewers, average watch time, 10-second views, Reels plays, total view time) and per-bucket audience retention. Facebook comment import now works for Reels and video posts. **2026-08-06** Threads: fixed publishing carousel posts (multiple images or videos). Temporary Threads errors are retried without creating duplicate posts. **2026-07-31** LinkedIn mentions: when a person is resolved from a profile URL but LinkedIn doesn't share their name, the tag comes back with an empty `display` and `needsDisplayName: true`. Pass `displayName` to set it, since LinkedIn only renders a mention when the text matches the name exactly. Post history and comment imports no longer fail on unexpected date formats from the platform. **2026-07-30** Automatic first comment: a `firstComment` field on post create and update that publishes a comment as soon as the post itself goes live. Available for TikTok, YouTube, Instagram, Facebook, Threads, LinkedIn, Reddit, Mastodon, Discord, Slack, and Bluesky, each with its own character limit. It is echoed back on create/update and single-post responses, and the underlying comment can still be edited through the comment endpoints. AI content labels: `isAiGenerated` for X, Pinterest, and Instagram, applying each platform's native AI disclosure label. Instagram paid partnerships: `isPaidPartnership` for the native "Paid partnership" label, and `brandedContentSponsors` to tag up to 2 sponsor usernames (accounts connected through Facebook Login only). Snapchat videos now accept 5-180 seconds, up from 6-60. `DELETE /misc/instagram/comment` to permanently delete a published Instagram comment, also available from the dashboard's post comments panel. Dashboard translations for Danish, Thai, Korean, and Hebrew. **2026-07-20** Threads post options: single `topicTag`, `replyControl`, `linkAttachment`, `poll`, `gif` (GIPHY), `allowlistedCountryCodes`, and Instagram Story cross-posting. Polls, GIFs, and link attachments are text-only. YouTube monetization: revenue/monetization data in raw analytics when an account connects with `withBusinessScope` (the monetary analytics scope) and raw analytics are enabled for the organization. Channel-level and per-video revenue reports; channels not in YPP return `"no data available"`. `withBusinessScope` now applies to YouTube in both the hosted and custom connect flows. Twitter/X is moving to a usage-based billing model. X API posting costs are passed through at cost, 1:1, with no markup. **2026-07-12** Snapchat Public Profile integration: OAuth connection, scheduled Stories and Spotlights, normalized profile and content analytics, and CSV bulk-post support. Post history import improvements across Facebook, Instagram, LinkedIn, Pinterest, and Threads, including more consistent imported media metadata. Instagram business discovery can now return recent public media items. Experimental `tiktokForceLogin` option for hosted and custom OAuth flows when TikTok keeps reusing the wrong active account. **2026-06-23** Bluesky external link cards now support an uploaded `thumbnail`. LinkedIn post reshares, mention resolution from profile/company URLs, and improved mention metadata. Facebook Page posts and Reels now support videos up to 20 minutes. YouTube post and edit payloads now support `defaultLanguage` and `defaultAudioLanguage`. Video uploads increased to 5 GB through the large upload flow. Upload-from-URL handling was also made more reliable. **2026-06-11** Custom `referenceKey` values for posts, including lookup by reference key and organization-level conflict protection. Comment import and top-level comments now support historical posts through `importedPostId`. Improved monthly usage counting and per-external-account daily limits. Invoices are now available from the organization Billing view. **2026-05-29** Manual retry endpoint for failed comments. Reconnect helpers for attaching a newly connected social account to matching draft and scheduled posts. Hosted portal links now support `serverUrl` and `instagramConnectionMethod`. Automatic cleanup for uploads left unused for 90 days. **2026-05-19** Instagram Music API. Stripe customer portal link configurator for connect flows, and support for custom Stripe prices. Plan tiers moved into the shared package so SDK and dashboard stay in sync. **2026-05-17** MOV file upload support. OAuth callback redirect - return users to a custom URL after connecting a platform. Reddit post metadata improvements. Webhooks now auto-disable after repeated delivery failures. Comment import schema fixes and admin token debugger. **2026-05-11** TikTok webhook events. TikTok additional post metadata, and a `retryable` field on platform errors. Surfaced real platform errors through the API instead of generic failure messages. Facebook & Instagram OAuth flow fixes. Standardized error messages across integrations. **2026-04-27** `forceBrowserOAuth` flag for OAuth flows. Custom rate limits per organization. Google Drive and Dropbox as upload sources. Health endpoint exposes per-platform status. Downgrade at the end of the billing cycle. **2026-04-21** Facebook Reviews - fetch and reply to reviews on Facebook Pages. Google Business Profile management in the dashboard. Calendar grid timezone fix. **2026-04-13** Comments imports 7 and 14 day raw analytics data for Instagram Full Google Business API module Raw Analytics for YouTube Facebook oauth flow change **2026-04-01** Bulk posting, create many posts from a spreadsheet. Upload files via URL. Scheduled posts calendar. Facebook & Instagram connection, optional `withBusinessScope`. LinkedIn, GIF publishing supported. Raw analytics store **reaction** breakdowns. Meta image posts, optional **alt text** for accessibility. TikTok **image auto-scaling** for Photo Mode when assets exceed 1920×1080 or the inverse. **2026-03-23** Improved Linkedin analytics with additional data. Added ability to post Linkedin GIFs. Added reauthenticate option on social accounts page. Fixed an edge case where a post was retrying, even though a "Account is restricted" error was thrown. **2026-03-16** Added image auto-scaling functionality for TikTok IMAGE posts to optimize content delivery. Fixed shares tracking for all Instagram post types (previously only counted for Reels). Enhanced error handling for TikTok publishing with clearer feedback messages. Improved Instagram metrics collection with intelligent retry logic for unsupported metrics. Enhanced image validation guidance to recommend auto-fit and auto-crop options where applicable. **2026-03-10** Instagram Trial Reels with `trialParams.graduationStrategy`. Instagram `autoFitImage` and `autoCropImage` for non-standard aspect ratios. LinkedIn article preview via `link` field. `disableAutoLogin` flag for Facebook, Instagram, and TikTok OAuth flows. **2026-03-06** Instagram location search endpoint. Instagram business discovery restrictions for direct connections. Instagram payload validation updates. **2026-02-28** Improved disconnect check. TikTok Commercial Music Library. [Docs](/api-reference/platforms/tiktok-music) Google Business Reviews. Remote disconnection detection. Unset channel without re-auth. Twitter reply settings. YouTube raw analytics demographics. Import filtering by surface and media type with carousel support. Analytics for imported posts. Data retention cleanup. **2026-01-07** Post history import with analytics. **2025-12-18** Improved Linkedin analytics. Business account search for Instagram. **2025-12-09** Post updates in misc endpoints. Youtube description formatting. **2025-11-12** Verbose error messages. Custom interval for analytics. Force analytics. Tiktok analytics data fix. Automatic posting retries. Force manual posting retries. Deleting used uploads. Upload compression support (disabled by default). **2025-10-27** Bluesky integration. Google Business Profile integration. **2025-10-23** Linkedin PDFs support. Linkedin tags. Social accounts and channels avatars. **2025-09-30** Instagram direct connection. Translations for connect page. Fixes for users with a huge amount of Facebook pages connected **2025-07-26** Team list endpoint. Used/Unused uploads. **2025-06-27** Facebook post link. Tiktok thumbnails. Instagram collaborators and tagged accounts. Upload get list filters. **2025-06-02** Shared uploads and thumbnails. **2025-05-30** Handle large uploads. **2025-05-01** Exposed analytics endpoints for bundle.social API. **2025-04-30** Added the ability to create comments to posts created via bundle.social. **2025-03-07** Handling multiple images for Linkedin. **2025-02-07** Added additional fields to create portal link endpoint. Now you can specify company logo, user name and user logo. **2025-02-01** Create portal link endpoint to enable your users to easily connect their social accounts on our hosted page. **2024-11-25** Mastodon integration. **2024-11-20** Custom team plans, link in bio and threads integration. **2024-09-22** This is a release of the new version of the API. Changes include: * moved the API key from team to organization * added the ability to manage teams * added the ability to connect social accounts **2024-08-07** Basic profile and post analytics for Youtube, Tiktok, Instagram and Facebook. **2024-07-18** This is the first changelog entry. The following changes have been made: * bundle.social has been released * api.bundle.social has been released * bundlesocial node SDK has been released # bundle.social vs Ayrshare Source: https://info.bundle.social/comparison/ayrshare bundle.social vs Ayrshare: pricing, features, API access, and who each is built for. The most direct comparison, since both are API-first. ## bundle.social vs Ayrshare > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR This is the comparison that actually matters. Ayrshare is the closest competitor we have - both API-first, both built for developers. The key differences: we use flat pricing (posts as the metric), they use per-profile pricing. We include unlimited profiles, they charge per connected account. Same arena, very different pricing models. *** ## The Comparison Table | Feature | bundle.social | Ayrshare | | :- | :- | :- | | **Starting price (multi-brand)** | \$100/mo (Pro) | \$299/mo (Launch) | | **Pricing model** | Flat (by posts) | Per profile | | **Social profiles** | Unlimited | 1 (Premium), 10 (Launch), 30 (Business) | | **Extra profile cost** | \$0 | \$8.99/mo each (Business) | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | 1,000 (Business) | | **API access** | All tiers | All tiers | | **Platforms** | 15 | 13+ | | **Analytics** | Paid plans (Pro and up) | Included | | **Webhooks** | Yes | Yes (Business+) | | **SDK** | Yes (Node.js) | Yes (multiple languages) | | **Users** | Unlimited | \$6.99/mo per extra user | | **Link in bio** | Yes | No | | **RSS posting** | No | Yes | | **Facebook Ads** | No | Add-on (\$100/mo) | | **Max Pack (higher limits)** | Business tier (\$400/mo) | Add-on (\$300/mo) | *** ## Where Ayrshare Wins Credit where it's due: * **Multi-language SDKs.** They have Python, Ruby, PHP, and more. We currently have Node.js. * **RSS posting.** Auto-post from RSS feeds. We don't have this yet. * **Facebook Ads integration.** Boost posts directly via API (\$100/mo add-on). We don't offer ad management. ## Where bundle.social Wins * **Unlimited profiles. Full stop.** This is the big one. Ayrshare's Business plan includes 30 profiles for \$599/mo, with each additional profile costing \$8.99/mo. If you're building a SaaS with 100+ connected accounts, that's \$599 + \$630 = \$1,229/mo on Ayrshare vs \$400/mo on bundle.social. * **100x the posts for the same price.** Our Business tier gives you 100,000 posts/mo for \$400. Ayrshare's Business gives you 1,000 posts/mo for \$599. Read that again. * **No per-user charges.** Ayrshare charges \$6.99/mo per extra user. We include unlimited users on all tiers. * **Lower entry for multi-brand.** Our Pro tier starts at \$100/mo with unlimited profiles. Ayrshare's Launch (10 profiles) is \$299/mo. * **Webhooks on all tiers.** Ayrshare restricts webhooks to Business and up. We include them everywhere. * **More platforms.** We support Discord and Slack. Useful for community-driven products. ## The Pricing Reality This is where it gets interesting. Let's compare apples to apples: | Scenario | bundle.social | Ayrshare | | :- | :- | :- | | 1 brand, API access | \$100/mo (Pro) | \$149/mo (Premium) | | 10 profiles, API + webhooks | \$100/mo (Pro) | \$299/mo (Launch) | | 30 profiles, full features | \$400/mo (Business) | \$599/mo (Business) | | 100 profiles | \$400/mo (Business) | \$599 + \$630 = \~\$1,229/mo | | 500 profiles | \$400/mo (Business) | \$599 + \$2,543 = \~\$3,142/mo | | Posts included | 100,000 (Business) | 1,000 (Business) | The more profiles you connect, the wider the gap gets. If you're building a SaaS platform where each customer connects their own social accounts, our flat model scales dramatically better. ## The Profile Pricing Trap Here's the thing about per-profile pricing: it creates anxiety. If your SaaS lets users connect social accounts, every new customer activation costs you \$8.99/mo on Ayrshare. You start optimizing for fewer connections instead of more. You add code to disconnect idle accounts. You build billing alerts instead of features. With bundle.social, a new user connecting 5 accounts costs you \$0 extra. You focus on growth, not cost management. ## Who Should Pick What **Pick Ayrshare if:** * You need Python, Ruby, or PHP SDKs (we only have Node.js for now) * RSS auto-posting is critical for your workflow * You need Facebook Ads management via API **Pick bundle.social if:** * You're building a SaaS where users connect their own social accounts (unlimited profiles) * Volume matters - you need more than 1,000 posts/month * You want webhooks without paying for the Business tier * You want unlimited users without per-seat charges * You need Discord or Slack integration * Your connected profile count is unpredictable or growing > [!NOTE] > > Competitor pricing sourced from [ayrshare.com/pricing](https://www.ayrshare.com/pricing/) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). # bundle.social vs Buffer Source: https://info.bundle.social/comparison/buffer Comparing bundle.social with Buffer - pricing, features, API access, and who each platform is built for. Honest breakdown for developers and SaaS builders. ## bundle.social vs Buffer > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR Buffer is one of the most well-known scheduling tools out there. Clean UI, simple product. But their per-channel pricing model means costs scale fast when you connect multiple platforms. bundle.social gives you unlimited accounts on a flat fee - plus API access that Buffer doesn't offer. *** ## The Comparison Table | Feature | bundle.social | Buffer | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | Free (3 channels) / \$6/channel/mo (Essentials) | | **Pricing model** | Flat monthly | Per channel | | **Per-user pricing** | No - unlimited users | Team plan: \$12/channel/mo | | **Social accounts** | Unlimited | 3 (Free), pay-per-channel after | | **API access** | All tiers | Not available | | **Platforms** | 15 | 8 (Instagram, Facebook, Twitter/X, LinkedIn, Pinterest, TikTok, YouTube, Mastodon) | | **Analytics** | Paid plans (Pro and up) | Essentials+ | | **Webhooks** | Yes | No | | **AI assistant** | No | Yes | | **Link in bio** | Yes | Yes (Start Page) | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | 10/channel (Free), unlimited (paid) | | **SDK** | Yes (Node.js) | No | | **Bulk scheduling** | Via API | No | *** ## Where Buffer Wins * **Free tier.** 3 channels, 10 posts each. Genuinely useful for personal brands testing the waters. * **Simple, clean UI.** Buffer's interface is famously simple. If you just want to type and schedule, it's hard to beat. * **Start Page.** Their link-in-bio tool is clean and well-integrated. * **AI Assistant.** Built-in AI for repurposing content, generating ideas, and adjusting tone. Included on paid plans. * **Lower starting price.** If you only need 3-5 channels, Buffer's Essentials plan (\$18-30/mo) is cheaper than our Pro tier. ## Where bundle.social Wins * **Flat pricing.** Here's the thing about Buffer's per-channel model: connecting 10 platforms costs \$60/mo on Essentials or \$120/mo on Team. Our Pro tier is \$100/mo for unlimited accounts. The more you connect, the better our deal gets. * **API access.** Buffer has no public API for scheduling or publishing. If you're building a product, they can't help you. We're API-first. * **Unlimited users.** Buffer's Team plan charges \$12/channel/mo (vs \$6 on Essentials). That 2x jump just for adding a teammate adds up. * **More platforms.** We support 15 including Discord, Slack, Bluesky, and Google Business. Buffer covers 8. * **Developer tools.** SDK, webhooks, OpenAPI spec. Buffer is a dashboard - you can't build on top of it. * **100,000 posts.** On our Business tier. Buffer's unlimited posting is per-channel, but our volume on Business is designed for serious SaaS platforms. ## The Pricing Reality Buffer's per-channel model means your bill grows with every connected account: | Scenario | bundle.social | Buffer | | :- | :- | :- | | 3 channels, 1 user | \$100/mo (Pro) | \$18/mo (Essentials) | | 10 channels, 1 user | \$100/mo (Pro) | \$60/mo (Essentials) | | 10 channels, 3 users | \$100/mo (Pro) | \$120/mo (Team) | | 25 channels, agency | \$400/mo (Business) | \$175/mo (Essentials, tiered) | | API access | \$100/mo (Pro) | Not available | Buffer wins on low channel counts. But if you're connecting 10+ accounts across multiple platforms (which is typical for agencies and SaaS products), our flat pricing makes more sense. ## Who Should Pick What **Pick Buffer if:** * You're a solo creator or small brand with 3-5 channels * You want the simplest possible scheduling UI * You don't need API access or developer tools * Budget is under \$30/month and you don't need team features * Their AI assistant is valuable for your content workflow **Pick bundle.social if:** * You're connecting 10+ social accounts (the math tips in our favor) * You need API access for building integrations or automations * You want unlimited users without per-channel cost multipliers * You're a developer, SaaS builder, or agency * You need Discord, Slack, Bluesky, or Google Business support > [!NOTE] > > Competitor pricing sourced from [buffer.com/pricing](https://buffer.com/pricing) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). # bundle.social vs Hootsuite Source: https://info.bundle.social/comparison/hootsuite Comparing bundle.social with Hootsuite - pricing, features, API access, and who each platform is built for. Honest breakdown for developers and SaaS builders. ## bundle.social vs Hootsuite > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR Hootsuite is one of the OGs of social media management - been around since 2008. It's a full-featured dashboard for marketing teams. bundle.social is an API-first platform for developers building social features into their own products. Hootsuite is the dashboard. We're the engine behind yours. *** ## The Comparison Table | Feature | bundle.social | Hootsuite | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | \~\$99/mo (Professional) | | **Per-user pricing** | No - unlimited users | Yes - per user/month | | **Social accounts** | Unlimited | 10 (Professional), unlimited (Enterprise) | | **API access** | All tiers | Enterprise only (custom pricing) | | **Platforms** | 15 | 10+ | | **Analytics** | Paid plans (Pro and up) | Included (advanced on higher tiers) | | **Webhooks** | Yes | No | | **Social listening** | No | Add-on | | **Smart inbox** | No | Yes | | **Employee advocacy** | No | Add-on | | **AI chatbot** | No | Add-on (Enterprise) | | **Competitor benchmarking** | No | Advanced+ (up to 20 competitors) | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | Unlimited | | **Bulk scheduling** | Via API | Up to 350 posts (Advanced) | | **SDK** | Yes (Node.js) | No | *** ## Where Hootsuite Wins Hootsuite has been doing this for 18 years. They've earned some advantages: * **Mature dashboard.** Content calendar, approval workflows, team collaboration - all polished from years of iteration. * **Social inbox.** Unified messaging across platforms. Great for support teams. * **Employee advocacy.** Their Amplify tool lets you push content to employees to share. Neat for large orgs. * **Competitor benchmarking.** Compare your performance against up to 20 competitors on the Advanced plan. * **Ad management.** Boost posts and manage paid social directly from the dashboard. * **Brand recognition.** Everyone knows Hootsuite. Enterprise procurement teams love things they recognize. ## Where bundle.social Wins * **API access without selling a kidney.** Hootsuite locks API access behind their Enterprise tier (custom pricing, read: expensive). We include it on every tier. * **No per-seat costs.** Hootsuite charges per user. We don't. Whether you have 1 user or 100, same price. * **Built for developers.** SDK, webhooks, OpenAPI spec, per-platform documentation. Hootsuite is built for marketing managers clicking buttons. We're built for engineers writing code. * **15 platforms.** Including Discord, Slack, Mastodon, and Bluesky. Hootsuite covers the major ones. * **Unlimited social accounts.** No caps on any tier. * **Simpler pricing.** Two tiers. Flat monthly. No add-on upsells for listening, advocacy, or AI chatbots. ## The Pricing Reality Hootsuite's exact pricing is harder to pin down (they love the "contact us" game on higher tiers), but here's what we know: | Scenario | bundle.social | Hootsuite | | :- | :- | :- | | Solo user, 10 accounts | \$100/mo (Pro) | \~\$99/mo (Professional) | | 3 users, full features | \$100/mo (Pro) | \~\$249+/mo (Team) | | 10 users, with API | \$400/mo (Business) | Custom Enterprise pricing | | Add-ons needed | None | Listening, advocacy, AI chatbot = extra | With Hootsuite, the sticker price is just the beginning. Add-ons add up fast. ## Who Should Pick What **Pick Hootsuite if:** * You're a marketing team that lives in a dashboard (not code) * You need employee advocacy, ad management, or social listening * You want competitor benchmarking with pretty reports for stakeholders * Your company's procurement process requires "established vendors" * You don't need API access **Pick bundle.social if:** * You're building a product that needs social media publishing baked in * You need API and SDK access without enterprise pricing * You want unlimited users and accounts on a flat monthly fee * You're a startup, agency, or SaaS company that moves fast * You care about developer experience more than dashboard bells and whistles > [!NOTE] > > Competitor pricing sourced from [hootsuite.com/plans](https://www.hootsuite.com/plans) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). Hootsuite's Team and Enterprise pricing may vary. # Comparison Source: https://info.bundle.social/comparison/index See how bundle.social compares to other social media management tools. Honest breakdowns with real pricing data for developers, SaaS builders, and agencies. ## How We Compare We built bundle.social for a specific audience: **developers, SaaS companies, and agencies** who need social media publishing and analytics as an API, not just a dashboard. Most tools in this space are built for marketing managers. We're built for engineers. That said, every tool has its strengths. Here's how we stack up - honestly. ### API-First Competitors The closest comparison. Also built for developers. > [card] [bundle.social vs Ayrshare](/comparison/ayrshare) > > The most direct competitor. Both API-first, both built for SaaS. Key difference: flat pricing vs per-profile pricing. ### Enterprise Solutions Large platforms with advanced features, enterprise pricing, and sales teams. > [card] [bundle.social vs Sprout Social](/comparison/sproutsocial) > > Enterprise-grade with social listening, CRM integrations, and \$199+/seat pricing. Great if you have the budget. > [card] [bundle.social vs Hootsuite](/comparison/hootsuite) > > The OG of social media management. Mature dashboard, employee advocacy, but API locked behind Enterprise pricing. > [card] [bundle.social vs Zoho Social](/comparison/zohosocial) > > Great if you're in the Zoho ecosystem. CRM integration is seamless. No API for social media operations. ### Mid-Market Tools Popular scheduling tools with solid features at moderate pricing. > [card] [bundle.social vs Buffer](/comparison/buffer) > > Clean, simple, per-channel pricing. Great for solo creators. Costs add up fast with 10+ channels. > [card] [bundle.social vs Later](/comparison/later) > > Instagram-first with visual planning and AI credits. Scales with users and social sets. > [card] [bundle.social vs Publer](/comparison/publer) > > Affordable starting at \$12/mo. RSS posting and content recycling. No API. ### SMB & Creator Tools Focused on small businesses, agencies, and individual creators. > [card] [bundle.social vs SocialPilot](/comparison/socialpilot) > > Agency-focused with white-label reports and client approvals. No API. Per-user pricing. > [card] [bundle.social vs SocialBee](/comparison/socialbee) > > Content categories and recycling are their superpower. Canva integration. No API. > [card] [bundle.social vs Planoly](/comparison/planoly) > > Instagram visual planner for creators. Beautiful UX. 6 platforms, no API. *** ### Quick Decision Guide | If you need... | Best pick | | :- | :- | | API access for building a SaaS product | **bundle.social** or Ayrshare | | Enterprise social listening + CRM | Sprout Social or Hootsuite | | Cheapest possible scheduling for 1 brand | Buffer (Free) or Planoly (\$7/mo) | | Visual Instagram grid planning | Planoly or Later | | Agency white-label reports | SocialPilot | | Content recycling and categories | SocialBee | | Zoho CRM integration | Zoho Social | | Unlimited accounts + API on flat pricing | **bundle.social** | > [!NOTE] > > All competitor pricing sourced from public pricing pages as of February 2026. Prices may change. # bundle.social vs Later Source: https://info.bundle.social/comparison/later Comparing bundle.social with Later - pricing, features, API access, and who each platform is built for. Honest breakdown for developers and SaaS builders. ## bundle.social vs Later > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR Later started as an Instagram-first scheduling tool and grew from there. They have a strong visual planner, AI credits, and a clean UI. But their pricing scales with users, social sets, and post limits - and they don't offer an API. If you're building something programmatic, we're the better fit. *** ## The Comparison Table | Feature | bundle.social | Later | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | \$25/mo (Starter) | | **Per-user pricing** | No - unlimited users | Yes - extra users \$5/mo each | | **Social accounts** | Unlimited | 1 social set (Starter), up to 6 (Scale) | | **API access** | All tiers | Not available | | **Platforms** | 15 | 8 (Instagram, Facebook, TikTok, LinkedIn, Pinterest, YouTube, Threads, Snapchat) | | **Analytics** | Paid plans (Pro and up) | Starter+ (basic), Scale for custom | | **Webhooks** | Yes | No | | **AI credits** | No | 5-100 depending on plan | | **Visual content planner** | No | Yes (their signature feature) | | **Social inbox** | No | Growth+ | | **Post limits** | 10,000/mo (Pro) | 30/profile/mo (Starter), unlimited (Scale) | | **SDK** | Yes (Node.js) | No | | **Extra social sets** | N/A (unlimited) | \$11.25-15/mo each | *** ## Where Later Wins * **Visual planner.** Later's drag-and-drop visual calendar is genuinely great, especially for Instagram-heavy brands that care about grid aesthetics. * **Lower starting price.** \$25/month for their Starter plan is accessible for small creators. Though you get 1 social set and 30 posts/profile/month. * **AI credits.** Built-in AI for caption writing and content ideas. 5-100 credits depending on tier. * **Linkin.bio.** Their link-in-bio tool is well-polished and Instagram-native. * **Instagram-first DNA.** If Instagram is your primary platform, Later's tooling around visual planning, grid preview, and optimal timing is mature. ## Where bundle.social Wins * **API access.** Later has no API. If you're building a SaaS product, internal tool, or any automation - they're a dead end. * **Unlimited accounts and users.** Later caps social sets (1-6 depending on plan) and charges extra for additional sets (\$11.25-15/mo each) and users (\$5/mo each). We include unlimited everything. * **More platforms.** We support 15 including Snapchat, Discord, Slack, Mastodon, Bluesky, and Google Business. Later covers 8. * **High post limits on Pro.** Later's Starter caps at 30 posts per profile per month. Our Pro gives you 10,000 across the organization. * **Developer tools.** SDK, webhooks, OpenAPI spec. Later is a pure dashboard product. * **Flat pricing.** No surprises when you add users, sets, or channels. ## The Pricing Reality Later's pricing adds up as you scale: | Scenario | bundle.social | Later | | :- | :- | :- | | 1 user, 1 brand, basic | \$100/mo (Pro) | \$25/mo (Starter) | | 3 users, 2 brands | \$100/mo (Pro) | \$50/mo (Growth) + extras | | 4 users, 6 brands | \$400/mo (Business) | \$110/mo (Scale) + extra sets | | API access | \$100/mo (Pro) | Not available | Later wins for solo creators and small teams with 1-2 brands. But the moment you scale beyond that - more brands, more users, or especially API access - bundle.social is the better deal. ## Who Should Pick What **Pick Later if:** * You're an Instagram-first creator who loves visual grid planning * You have 1-2 brands and 1-3 team members * You want built-in AI caption tools * Budget is under \$50/month and you don't need API access **Pick bundle.social if:** * You need API access for building integrations or automations * You manage many brands and need unlimited social accounts * You want unlimited users without extra per-user fees * You're a developer, SaaS builder, or agency * You need Discord, Slack, Bluesky, Mastodon, or Google Business > [!NOTE] > > Competitor pricing sourced from [later.com/pricing](https://later.com/pricing/) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). # bundle.social vs Planoly Source: https://info.bundle.social/comparison/planoly Comparing bundle.social with Planoly - pricing, features, API access, and who each platform is built for. Honest breakdown for developers and SaaS builders. ## bundle.social vs Planoly > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR Planoly is an Instagram-first visual planner with a clean aesthetic and a loyal following among creators. It's affordable, simple, and designed for visual content. But it supports fewer platforms, limits uploads and users, and has no API. Different audiences entirely. *** ## The Comparison Table | Feature | bundle.social | Planoly | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | Free (2 profiles, 30 uploads/mo) | | **Per-user pricing** | No - unlimited users | Yes - limited by plan (1-3 users) | | **Social accounts** | Unlimited | 1-2 social sets depending on plan | | **API access** | All tiers | Not available | | **Platforms** | 15 | 6 (Instagram, Facebook, TikTok, Pinterest, YouTube, Twitter/X) | | **Analytics** | Paid plans (Pro and up) | Paid plans | | **Webhooks** | Yes | No | | **Visual grid planner** | No | Yes (their signature feature) | | **Instagram DM inbox** | No | Yes | | **Upload limits** | No limits | 30-unlimited depending on plan | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | Based on uploads | | **SDK** | Yes (Node.js) | No | *** ## Where Planoly Wins * **Visual grid planner.** Planoly's Instagram grid preview is their killer feature. Drag, drop, and see how your feed will look before posting. If Instagram aesthetics matter to you, this is best-in-class. * **Cheapest entry point.** Free plan with 2 profiles and 30 uploads. Paid plans start at \$7-11/month. Hard to beat for personal brands. * **Instagram DM management.** Manage DMs directly from the platform. Useful for creators handling customer inquiries. * **Creator-friendly design.** The entire UX is designed for visual creators, not developers. Clean, intuitive, pretty. * **Storefront features.** Sellit and link-in-bio commerce tools for selling products through social. ## Where bundle.social Wins * **API access.** Planoly has no API. If you need programmatic access, it's a non-starter. * **15 platforms vs 6.** We support Discord, Slack, Mastodon, Bluesky, Google Business, LinkedIn, Reddit, and Threads. Planoly focuses on Instagram, Facebook, TikTok, Pinterest, YouTube, and Twitter/X. * **Unlimited everything.** Accounts, users, uploads. Planoly caps social sets (1-2), users (1-3), and uploads (30-unlimited) depending on plan. * **Volume.** Our Business tier supports 100,000 posts/month. Planoly is designed for individual creators posting a few times a day. * **Developer tools.** SDK, webhooks, OpenAPI spec. * **Multi-brand at scale.** Managing 10+ brands on Planoly means paying for extra social sets. We include unlimited teams. ## The Pricing Reality | Scenario | bundle.social | Planoly | | :- | :- | :- | | 1 user, 1 brand, light use | \$100/mo (Pro) | \$11.25/mo (Starter) | | 3 users, 1 brand | \$100/mo (Pro) | \$20/mo (Growth) | | 3 users, 2 brands | \$100/mo (Pro) | \$36.50/mo (Professional) | | Unlimited brands, agency | \$400/mo (Business) | Not designed for this | | API access | \$100/mo (Pro) | Not available | This is less of a "vs" and more of a "different tools for different people." Planoly is for Instagram creators. bundle.social is for developers and SaaS companies. ## Who Should Pick What **Pick Planoly if:** * You're an Instagram-first creator who cares about grid aesthetics * You want the cheapest possible entry point (\$7-11/month) * Instagram DM management is part of your workflow * You sell products and want integrated commerce tools * You don't need API access, developer tools, or 15 platforms **Pick bundle.social if:** * You need API access for building products or integrations * You need more than 6 platforms (especially LinkedIn, Reddit, Discord, Slack, Mastodon, Bluesky) * You're managing multiple brands at scale * You want unlimited users and accounts * You're a developer, SaaS builder, or agency, not an Instagram creator > [!NOTE] > > Competitor pricing sourced from [planoly.com/pricing](https://www.planoly.com/pricing) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). Planoly pricing may vary by region. # bundle.social vs Publer Source: https://info.bundle.social/comparison/publer Comparing bundle.social with Publer - pricing, features, API access, and who each platform is built for. Honest breakdown for developers and SaaS builders. ## bundle.social vs Publer > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR Publer is a solid mid-range scheduling tool with a generous feature set for the price. Their base plans start at \$12/month with 3 accounts. But they scale per-account, have no API, and charge extra for Twitter/X. If you need developer tools or unlimited accounts, we've got you. *** ## The Comparison Table | Feature | bundle.social | Publer | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | Free (3 accounts) / \$12/mo (Professional) | | **Per-user/account pricing** | No - unlimited | Yes - extra accounts cost more | | **Social accounts** | Unlimited | 3 (base), additional for extra cost | | **API access** | All tiers | Not available | | **Platforms** | 15 | 10+ (Instagram, Facebook, Twitter/X, LinkedIn, Pinterest, TikTok, YouTube, Google Business, Mastodon, Threads) | | **Analytics** | Paid plans (Pro and up) | Business+ (\$21/mo) | | **Webhooks** | Yes | No | | **Twitter/X** | Included | Paid plans only | | **RSS auto-posting** | No | Professional+ | | **AI Assist** | No | Business+ (unlimited prompts) | | **Post recycling** | No | Business+ | | **Bulk scheduling** | Via API | Professional+ | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | Unlimited (paid plans) | | **SDK** | Yes (Node.js) | No | *** ## Where Publer Wins * **Low entry price.** \$12/month for 3 accounts with unlimited scheduling is genuinely affordable. Hard to argue with that for solo users. * **RSS auto-posting.** Automatically publish from RSS feeds. Nice for content curation workflows. * **AI Assist.** Unlimited AI prompts on Business plan (\$21/mo). Helpful for generating captions and ideas. * **Post recycling.** Automatically re-share evergreen content on a schedule. We don't have this. * **Browser extension.** Quick-share from anywhere while browsing. Handy. * **Free plan.** 3 accounts (no Twitter/X), 10 scheduled posts per account. Good for testing. ## Where bundle.social Wins * **API access.** Publer has no API. If you're building a SaaS product or integration, they can't help you. * **Unlimited accounts.** Publer charges for additional accounts beyond the base 3. With 7 accounts, you're paying \$28-37/mo. With 15 accounts, it climbs fast. We include unlimited on all tiers. * **Unlimited users.** Publer charges extra for team members beyond the base plan. We don't. * **Developer tools.** SDK, webhooks, OpenAPI spec. Publer is dashboard-only. * **More platforms.** We support 15 including Discord, Slack, and Bluesky. * **Twitter/X included.** Publer restricts Twitter/X to paid plans because of API costs. We include it on all tiers. * **No content limits.** Publer's free plan caps at 10 scheduled posts per account with 25 saved drafts. ## The Pricing Reality | Scenario | bundle.social | Publer | | :- | :- | :- | | 3 accounts, 1 user | \$100/mo (Pro) | \$12/mo (Professional) | | 7 accounts, 1 user | \$100/mo (Pro) | \$28/mo (Professional) | | 15 accounts, 3 users | \$100/mo (Pro) | \~\$60-70/mo (Business + extras) | | 30 accounts, agency | \$400/mo (Business) | Custom/Enterprise | | API access | \$100/mo (Pro) | Not available | Publer is cheaper for small setups (under 10 accounts). Once you're managing many accounts or need programmatic access, we're the better value. ## Who Should Pick What **Pick Publer if:** * You're a solo creator or small team with under 10 social accounts * You want RSS auto-posting or content recycling features * Budget is under \$30/month * You don't need API access or developer tools * AI caption generation is important to your workflow **Pick bundle.social if:** * You need API access for building products or integrations * You're managing 10+ social accounts and want flat pricing * You want unlimited users without per-seat fees * You're a developer, SaaS builder, or agency * You need Discord, Slack, or Bluesky support > [!NOTE] > > Competitor pricing sourced from [publer.io/plans](https://publer.io/plans) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). # bundle.social vs SocialBee Source: https://info.bundle.social/comparison/socialbee Comparing bundle.social with SocialBee - pricing, features, API access, and who each platform is built for. Honest breakdown for developers and SaaS builders. ## bundle.social vs SocialBee > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR SocialBee is a content-focused scheduling tool with strong category-based posting, Canva integration, and content recycling. Solid product for marketers. But they charge per profile, per user, cap workspaces, and have no API. If you're building something or need unlimited scaling, we're the move. *** ## The Comparison Table | Feature | bundle.social | SocialBee | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | \$29/mo (Bootstrap) | | **Per-user pricing** | No - unlimited users | Yes - \$10/mo per extra user | | **Social accounts** | Unlimited | 5-25 depending on plan | | **API access** | All tiers | Not available | | **Platforms** | 15 | 9 (Instagram, Facebook, Twitter/X, LinkedIn, Pinterest, TikTok, YouTube, Google Business, Threads) | | **Analytics** | Paid plans (Pro and up) | All plans | | **Webhooks** | Yes | No | | **Content categories** | No | Yes (their signature feature) | | **Canva integration** | No | Yes | | **Content recycling** | No | Yes | | **AI tools** | No | Yes (Copilot, AI Post Generator) | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | Unlimited | | **SDK** | Yes (Node.js) | No | *** ## Where SocialBee Wins * **Content categories.** Organize posts into categories (promotions, tips, quotes) and set a schedule per category. Smart approach for content variety. * **Content recycling.** Automatically re-share evergreen content. Great for solopreneurs who want to maximize a content library. * **Canva integration.** Design directly within SocialBee. Genuinely convenient. * **AI Copilot.** Generate content ideas, captions, and hashtags. More sophisticated than simple AI credits. * **Lower entry price.** \$29/month for 5 profiles is accessible for solo marketers. * **Workspaces.** Up to 5 workspaces on the Pro plan (\$99/mo) for separating clients or projects. ## Where bundle.social Wins * **API access.** SocialBee has no API. Can't build on top of it. Can't automate. Can't integrate into your SaaS. * **Unlimited profiles.** SocialBee caps at 5-25 profiles (standard plans). Want 50? That's \$179/mo (Pro50 agency plan). Want 100? \$329/mo. We include unlimited on all tiers. * **Unlimited users.** SocialBee charges \$10/mo per extra user. Even their Pro plan (3 users) at \$99/mo is comparable to our Pro (\$100/mo) but with user and profile caps. * **More platforms.** We support 15 including Discord, Slack, Mastodon, and Bluesky. SocialBee covers 9. * **Developer tools.** SDK, webhooks, OpenAPI spec. * **No workspace limits.** SocialBee caps workspaces (1-5 on standard plans, more on agency). Our teams are unlimited. ## The Pricing Reality | Scenario | bundle.social | SocialBee | | :- | :- | :- | | 1 user, 5 profiles | \$100/mo (Pro) | \$29/mo (Bootstrap) | | 1 user, 10 profiles | \$100/mo (Pro) | \$49/mo (Accelerate) | | 3 users, 25 profiles | \$100/mo (Pro) | \$99/mo (Pro) | | 5 users, 50 profiles | \$400/mo (Business) | \$179/mo (Pro50) + \$20 extra users | | 5 users, 100 profiles | \$400/mo (Business) | \$329/mo (Pro100) + \$20 extra users | | API access | \$100/mo (Pro) | Not available | SocialBee is cheaper for small setups with fewer profiles. At 25+ profiles with 3+ users, the pricing converges. At 50+ profiles, we're comparable. The API is the dealbreaker. ## Who Should Pick What **Pick SocialBee if:** * You're a solo marketer who loves content categories and recycling * Canva integration is part of your daily workflow * You have under 25 social profiles * You don't need API access or developer tools * AI-generated content is important to your strategy * Budget is under \$50/month **Pick bundle.social if:** * You need API access for building products or integrations * You're managing 25+ profiles and want predictable pricing * You want unlimited users without per-seat charges * You're a developer, SaaS builder, or agency building their own tools * You need Discord, Slack, Mastodon, or Bluesky support > [!NOTE] > > Competitor pricing sourced from [socialbee.com/pricing](https://socialbee.com/pricing/) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). # bundle.social vs SocialPilot Source: https://info.bundle.social/comparison/socialpilot Comparing bundle.social with SocialPilot - pricing, features, API access, and who each platform is built for. Honest breakdown for developers and SaaS builders. ## bundle.social vs SocialPilot > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR SocialPilot is a popular agency-focused scheduling tool with solid features at mid-range pricing. They offer white-label reports, client workflows, and up to 50 accounts. But they have no API, charge per user, and cap accounts per plan. If you need developer tools or unlimited accounts, that's our turf. *** ## The Comparison Table | Feature | bundle.social | SocialPilot | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | \$30/mo (Essentials) | | **Per-user pricing** | No - unlimited users | Yes - \$5/mo per extra user | | **Social accounts** | Unlimited | 7-50 depending on plan | | **API access** | All tiers | Not available | | **Platforms** | 15 | 9 (Instagram, Facebook, Twitter/X, LinkedIn, Pinterest, TikTok, YouTube, Google Business, Threads) | | **Analytics** | Paid plans (Pro and up) | Standard+ (\$50/mo) | | **Webhooks** | Yes | No | | **White-label reports** | No | Premium+ (\$100/mo) | | **Client approval** | No | Premium+ | | **Social inbox** | No | Standard+ | | **AI credits** | No | 500-unlimited depending on plan | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | Unlimited | | **SDK** | Yes (Node.js) | No | *** ## Where SocialPilot Wins * **Lower entry price.** \$30/month for 7 accounts and basic scheduling. Good value for solo managers. * **White-label reports.** On Premium (\$100/mo) - great for agencies that send branded reports to clients. * **Client approval workflows.** Let clients review and approve posts before publishing. Nice for agency-client relationships. * **Social inbox.** Unified messaging starting at Standard (\$50/mo). * **AI credits.** 500-unlimited depending on plan. Built-in content generation. * **Dedicated account manager.** On the Ultimate plan (\$200/mo). Actual human support at scale. ## Where bundle.social Wins * **API access.** SocialPilot has no API. If you're building a product, internal tool, or any automation, they can't help you. * **Unlimited accounts.** SocialPilot caps at 7-50 accounts depending on plan. Extra profiles cost \$4/mo each. We include unlimited. * **Unlimited users.** SocialPilot charges \$5/mo per extra user. Our Pro at \$100/mo includes unlimited users - same as their Premium price but without user caps. * **More platforms.** We support 15 including Discord, Slack, Mastodon, and Bluesky. SocialPilot covers 9. * **Developer tools.** SDK, webhooks, OpenAPI spec. SocialPilot is dashboard-only. * **Support response time.** We respond same-day. Not behind a premium tier wall. ## The Pricing Reality | Scenario | bundle.social | SocialPilot | | :- | :- | :- | | 1 user, 7 accounts | \$100/mo (Pro) | \$30/mo (Essentials) | | 3 users, 15 accounts | \$100/mo (Pro) | \$50/mo (Standard) | | 6 users, 25 accounts | \$100/mo (Pro) | \$100/mo (Premium) | | 10+ users, 50 accounts | \$400/mo (Business) | \$200/mo (Ultimate) | | API access | \$100/mo (Pro) | Not available | SocialPilot is cheaper across the board for pure dashboard scheduling. The question is: do you need an API? If yes, the comparison ends here. If no, SocialPilot offers solid value for agencies. ## Who Should Pick What **Pick SocialPilot if:** * You're an agency that needs white-label reports and client approvals * You don't need API access or developer tools * You want a dedicated account manager (Ultimate plan) * Social inbox and client workflows are part of your daily work * Budget is a priority and you have a fixed, smaller set of accounts **Pick bundle.social if:** * You need API access for building products or integrations * You want unlimited accounts and users on a flat fee * You're a developer, SaaS builder, or tech-forward agency * You need Discord, Slack, Mastodon, or Bluesky support * You'd rather build your own dashboard on top of our API > [!NOTE] > > Competitor pricing sourced from [socialpilot.co/plans](https://www.socialpilot.co/plans) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). # bundle.social vs Sprout Social Source: https://info.bundle.social/comparison/sproutsocial bundle.social vs Sprout Social: pricing, features, API access, and who each is built for. An honest breakdown for developers and SaaS builders. ## bundle.social vs Sprout Social > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR Sprout Social is an enterprise social media management suite with advanced listening, CRM, and team workflows. bundle.social is an API-first platform built for developers and SaaS companies who need to integrate social media into their own products. Different tools for different jobs. *** ## The Comparison Table | Feature | bundle.social | Sprout Social | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | \$199/seat/mo (Standard) | | **Per-user pricing** | No - unlimited users | Yes - every seat costs \$199-399/mo | | **Social accounts** | Unlimited | 5 (Standard), unlimited (Professional+) | | **API access** | All tiers | Advanced tier only (\$399/seat/mo) | | **Platforms** | 15 | 10+ | | **Analytics** | Paid plans (Pro and up) | Included (more advanced on higher tiers) | | **Webhooks** | Yes | No (use their API) | | **Social listening** | No | Yes (add-on) | | **CRM integration** | No | Yes (Salesforce, HubSpot, etc.) | | **Smart inbox** | No | Yes | | **Sentiment analysis** | No | Yes (Advanced+) | | **Team approval workflows** | No | Yes | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | Unlimited | | **Billing model** | Flat monthly | Per seat, annual commitment | | **SDK** | Yes (Node.js) | No | *** ## Where Sprout Social Wins Let's be real. Sprout Social is a beast of a platform: * **Social listening and monitoring.** They can track brand mentions, keywords, and sentiment across the internet. We don't do this. * **Smart inbox.** Unified inbox for DMs, comments, and mentions across platforms. Great for customer support teams. * **Enterprise reporting.** Custom dashboards, competitor benchmarking, paid social tracking. Their reporting is seriously powerful. * **CRM integrations.** Native Salesforce, HubSpot, and Zendesk connections. If your workflow lives in a CRM, this matters. * **Team workflows.** Approval chains, task assignments, team productivity reports. Built for 20+ person social teams. If you're a large brand with a dedicated social media team that needs listening, CRM, and enterprise reporting - Sprout is built for you. ## Where bundle.social Wins * **Price.** A 3-person team on Sprout Professional costs \$897/month. Our Business tier with unlimited users is \$400/month. That's not a typo. * **API-first.** Our entire platform is built around the API. If you're a SaaS company building social media features into your product, we're purpose-built for this. Sprout's API is an afterthought locked behind the \$399/seat tier. * **No per-seat pricing.** Add 5 users or 50 users - same price. Sprout charges \$199-399 per additional seat. * **Unlimited social accounts.** On all tiers. Sprout's Standard plan caps at 5 profiles. * **Developer experience.** SDK, webhooks, OpenAPI spec, detailed platform-specific docs. We're built for developers, not marketing managers. * **15 platforms.** Including Discord, Slack, Mastodon, and Bluesky. Sprout focuses on the major platforms. ## The Pricing Reality Let's do the math for a typical SaaS company with 3 team members: | Scenario | bundle.social | Sprout Social | | :- | :- | :- | | 3 users, basic | \$100/mo (Pro) | \$597/mo (Standard) | | 3 users, with API | \$100/mo (Pro) | \$1,197/mo (Advanced) | | 10 users, full features | \$400/mo (Business) | \$2,990/mo (Professional) | Annual commitment required for Sprout. We do monthly. ## Who Should Pick What **Pick Sprout Social if:** * You're a large brand with a dedicated social team (10+ people) * You need social listening, sentiment analysis, and CRM integration * Your budget is \$1,000+/month and you need enterprise reporting * You don't need API access for building integrations **Pick bundle.social if:** * You're building a SaaS product that needs social media features * You need API access and developer tools (SDK, webhooks) * You want unlimited users and accounts without per-seat pricing * You're a startup or agency that needs 80% of the features at 10% of the cost * Your use case is publishing and analytics, not social listening > [!NOTE] > > Competitor pricing sourced from [sproutsocial.com/pricing](https://sproutsocial.com/pricing/) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). # bundle.social vs Zoho Social Source: https://info.bundle.social/comparison/zohosocial Comparing bundle.social with Zoho Social - pricing, features, API access, and who each platform is built for. Honest breakdown for developers and SaaS builders. ## bundle.social vs Zoho Social > [!NOTE] > > This comparison is on our website, so take it with a grain of salt. We'll stick to facts and publicly available pricing. If something's wrong, [tell us](https://bundle.social/contact). ### TL;DR Zoho Social is part of the massive Zoho ecosystem. If you're already neck-deep in Zoho CRM, Zoho Desk, and Zoho Everything-Else, their social tool plugs in neatly. If you're not in the Zoho world and you need an API - that's where we come in. *** ## The Comparison Table | Feature | bundle.social | Zoho Social | | :- | :- | :- | | **Starting price** | \$100/mo (Pro) | \$15/mo (Standard) | | **Per-user pricing** | No - unlimited users | Yes - extra members \$10-13/mo each | | **Social accounts** | Unlimited | 6 channels (Free), up to 10 (Standard) | | **API access** | All tiers | Not available | | **Platforms** | 15 | 9 (Instagram, Facebook, Twitter/X, LinkedIn, Pinterest, TikTok, YouTube, Threads, Mastodon) | | **Analytics** | Paid plans (Pro and up) | Professional+ (\$40/mo) | | **Webhooks** | Yes | No | | **CRM integration** | No | Yes (Zoho CRM, native) | | **Social inbox** | No | Professional+ | | **Bulk scheduling** | Via API | Professional+ | | **Multi-brand** | Yes (teams) | Agency plans only (\$320/mo for 10 brands) | | **SDK** | Yes (Node.js) | No | | **Monthly posts** | 10,000 (Pro) / 100,000 (Business) | Unlimited (Standard+) | *** ## Where Zoho Social Wins * **Zoho ecosystem integration.** If you use Zoho CRM, the native integration is genuinely useful. Lead generation from social, contact enrichment - it's seamless within their world. * **Lower entry price.** \$15/month for Standard is hard to beat for a solo social media manager who just needs a publishing calendar. * **Social inbox.** Unified messaging starting at the Professional tier (\$40/mo). * **Publishing calendar.** Clean, visual, drag-and-drop. Great for non-technical users. * **SmartQ.** Their AI suggests optimal posting times. Nice touch. ## Where bundle.social Wins * **API access.** Zoho Social has no public API for social media operations. If you're building a SaaS product, an internal tool, or any kind of integration - they can't help you. * **Unlimited users.** Zoho charges \$10-13/month per additional team member. Their Premium plan includes only 3 members. Adding 10 users gets expensive. * **Unlimited accounts.** Our Pro tier gives you unlimited social accounts. Zoho Standard caps at 10 channels. * **More platforms.** We support 15 including Discord, Slack, Bluesky, and Google Business. Zoho covers 9. * **Multi-brand without agency pricing.** You need teams for multiple brands? We include that in our standard tiers. Zoho's agency plans start at \$320/month for 10 brands with only 5 team members. * **Developer tools.** SDK, webhooks, OpenAPI spec. Zoho Social is a dashboard - there's nothing to integrate with programmatically. ## The Pricing Reality Zoho looks cheap until you need features and users: | Scenario | bundle.social | Zoho Social | | :- | :- | :- | | 1 user, basic scheduling | \$100/mo (Pro) | \$15/mo (Standard) | | 1 user, with analytics | \$100/mo (Pro) | \$40/mo (Professional) | | 5 users, analytics | \$100/mo (Pro) | \$40 + \$40 extra members = \~\$80/mo | | 10 brands, 5 users | \$400/mo (Business) | \$320/mo (Agency) | | API access | \$100/mo (Pro) | Not available at any price | For a single user doing basic scheduling, Zoho is genuinely cheaper. But the moment you add users, brands, or need an API - the math shifts. ## Who Should Pick What **Pick Zoho Social if:** * You're already in the Zoho ecosystem (CRM, Desk, etc.) * You're a solo marketer or small team (1-3 people) managing 1 brand * You don't need API access or developer tools * Budget is tight and you just need a publishing calendar with analytics * The Zoho CRM integration is a must-have for your workflow **Pick bundle.social if:** * You need API access for building integrations or automations * You're managing multiple brands and don't want to pay agency pricing * You need unlimited users without per-seat costs * You're a developer, SaaS builder, or agency that needs programmatic access * You need Discord, Slack, Bluesky, or Google Business support > [!NOTE] > > Competitor pricing sourced from [zoho.com/social/pricing.html](https://www.zoho.com/social/pricing.html) as of February 2026. bundle.social pricing from [bundle.social](https://bundle.social). # Demo Source: https://info.bundle.social/demo Watch bundle.social in action. Demo videos of the web app and API covering scheduling, multi-platform publishing, and analytics with real examples. ## Web App Demo [YouTube video player](https://www.youtube.com/embed/m9s7uG-S2vU?si=JFVmydc52U4jkDHE) ## API Demo [YouTube video player](https://www.youtube.com/embed/TIA_KzL6PeY?si=NLQKzy-SNIFmtXMn) # FAQ Source: https://info.bundle.social/faq Frequently asked questions about bundle.social. How to get started, connect accounts, schedule posts, what counts toward limits, and how billing works. > [accordion] What is the purpose of bundle.social? > > bundle.social is a platform and API that allows you to manage yours and your clients' social media accounts in one place. > You can schedule posts, view analytics, and more. > [accordion] How do I get started with bundle.social? > > To get started with bundle.social, you need to create an account. > Once you have an account, create a team and then connect your social media accounts and start using the platform. > [accordion] How do I connect my social media accounts to bundle.social? > > ### Platform > > To connect your social media accounts to bundle.social, go to the "Social Accounts" page and click on the "Connect" button. > You will be prompted to log in to your social media account and authorize bundle.social to access your account with the required permissions. > Get more info here: [Connect Social Accounts](/knowledge/social-accounts/index) > > ### API > > Get more info here: [Connect Social Accounts via API](/api-reference/connect-social-accounts) > [accordion] How do I schedule a post on bundle.social? > > ### Platform > > To schedule a post on bundle.social, go to the "Posts" page and click on the "+" button. > You can then select the social media accounts you want to post to, enter the content of the post, and set the date and time you want the post to be published. > > Get more info here: [Create a post](/knowledge/posts/create-first-post) > > ### API > > Get more info here: [Create a post via API/SDK](/api-reference/sdk#create-a-post) > [accordion] Is bundle.social free? > > Yes, bundle.social has a free, but limited plan. If you need more features, you can upgrade to a paid plan. > [accordion] How do I upgrade to a paid plan on bundle.social? > > To upgrade to a paid plan on bundle.social, go to the "Billing" page and click on the "Upgrade" button. > You will be prompted first to setup your billing information and then to select the plan you want to upgrade to. > [accordion] How do I cancel my subscription on bundle.social? > > To cancel your subscription on bundle.social, go to the "Billing" page and click on "X" button. > [accordion] How do I contact support on bundle.social? > > Go to [Help page](https://bundle.social/) and click on the blue circle button in the bottom right corner. # Glossary Source: https://info.bundle.social/glossary Glossary of terms used widely in social media marketing and APIs, from engagement rate and reach to webhooks, OAuth scopes, and rate limiting. ## Analytics The process of collecting and analyzing data to gain insights into user behavior, engagement, and performance of social media posts. ## API (Application Programming Interface) A set of tools and protocols that allow different software applications to communicate with each other, enabling integration with various social media platforms. ## A/B Testing A method of comparing two versions of a webpage or app against each other to determine which one performs better. ## Audience Insights Data and analysis about the demographics, interests, and behaviors of your social media audience. ## Backlink A link from one website to another, important for SEO and driving traffic. ## Benchmarking Comparing your social media performance metrics to industry standards or competitors to gauge success. ## Bounce Rate The percentage of visitors who navigate away from a site after viewing only one page, used as a metric to gauge the effectiveness of content. ## Brand Monitoring The practice of tracking mentions of a brand, product, or service across social media and other online platforms to manage reputation and engagement. ## Call to Action (CTA) A prompt that encourages users to take a specific action, such as "Click Here" or "Learn More". ## Campaign A coordinated series of social media posts, ads, or content designed to achieve a specific goal. ## Click-Through Rate (CTR) The ratio of users who click on a link to the number of total users who view an ad or a post, used to measure the effectiveness of online campaigns. ## Content Calendar A scheduling tool that outlines the dates and times for publishing specific content on social media platforms. ## Conversion Rate The percentage of users who take a desired action, such as making a purchase or signing up for a newsletter, out of the total number of visitors. ## Customer Relationship Management (CRM) A system for managing a company’s interactions with current and potential customers, often integrated with social media tools. ## Dashboard A user interface that provides an overview of key metrics and performance indicators related to social media activity and campaigns. ## Demographics Statistical data relating to the population and particular groups within it, used to understand the audience and tailor content accordingly. ## Engagement The level of interaction between users and social media content, including likes, comments, shares, and clicks. ## Engagement Rate A metric that measures the amount of interaction (likes, shares, comments) a post receives relative to the number of followers or views. ## Follower Growth The increase in the number of followers on a social media account over a specified period. ## Frequency The number of times an ad or post is shown to the same user within a specific time period. ## Geotagging Adding geographical identification metadata to posts, photos, and videos to specify location. ## Hashtag A keyword or phrase preceded by the pound sign (#) used to categorize and discover content on social media platforms. ## Impressions The number of times a post or ad is displayed to users, regardless of whether it is clicked or not. ## Influencer An individual with a significant following on social media who can impact their audience's opinions and behaviors. ## Key Performance Indicator (KPI) A measurable value that indicates how effectively a company is achieving key business objectives, such as engagement rates or follower growth. ## Lead Generation The process of attracting and converting strangers and prospects into someone who has indicated interest in your company's product or service. ## Mentions Instances where a brand, user, or hashtag is referenced on social media platforms, used to gauge brand visibility and engagement. ## Metrics Quantitative measures used to track and assess the status of specific business processes, such as likes, shares, and comments. ## Native Advertising Paid ads that match the look, feel, and function of the media format in which they appear, making them less intrusive and more engaging. ## Organic Reach The number of people who see your content without paid promotion, reflecting the natural visibility and engagement of posts. ## Post Scheduling The process of planning and arranging content to be published on social media platforms at predetermined times. ## Pay-Per-Click (PPC) An online advertising model where advertisers pay a fee each time one of their ads is clicked, commonly used in social media marketing. ## Reach The total number of unique users who see a post or ad on social media, indicating the extent of content distribution. ## Return on Investment (ROI) A performance measure used to evaluate the efficiency of an investment, calculated by dividing the net profit by the cost of the investment. ## Segmentation The process of dividing a target audience into smaller, more defined categories based on various criteria, such as demographics or behavior. ## Sentiment Analysis The use of natural language processing and other data analysis techniques to determine the emotional tone behind social media mentions and comments. ## Social Media Marketing (SMM) The use of social media platforms to promote products or services, engage with the audience, and drive traffic to a website. ## Target Audience A specific group of people identified as the intended recipient of an advertisement or message, based on demographic, psychographic, and behavioral characteristics. ## Traffic The number of visitors to a website or social media page, often analyzed to understand user behavior and content effectiveness. ## User-Generated Content (UGC) Content created by users rather than brands, often used in marketing to increase engagement and authenticity. ## URL Shortener A tool that condenses long URLs into shorter, more manageable links, often used to track clicks and engagement on social media. ## Viral Content Content that rapidly spreads across the internet, often through social media shares and engagement, due to its highly engaging or shareable nature. ## Webinar An online seminar or presentation conducted over the internet, often used for marketing, education, or training purposes. ## Workflow Automation The use of technology to automate repetitive tasks and processes, improving efficiency and consistency in social media management. # Building a Scheduler Source: https://info.bundle.social/guides/building-scheduler A practical guide to building a social media scheduling tool. The real one, not the 5-step tutorial. So you want to build a scheduler? You want to be the next Buffer or Hootsuite? Cool. Here is how you actually do it with bundle.social. Not the "hello world" version - the real thing, with error handling, retries, drafts, and all the edge cases that will bite you at 2 AM. *** ## The Architecture The high-level flow is simple. The devil is in the details (which we cover below). 1. **User connects account** (via [Connect Flow](/api-reference/connect-social-accounts)). 2. **User uploads content** (via [Media Upload](/api-reference/upload-content)). 3. **User picks a date** (your UI). 4. **You send it to us** (API call). 5. **We publish it** (our infrastructure). 6. **We tell you what happened** ([Webhooks](/api-reference/webhooks)). Simple? In theory. Let's go deeper. *** ## Post Status Lifecycle This is the most important thing to understand. A post is not just "scheduled" or "published". It goes through a state machine. ```mermaid theme={null} stateDiagram-v2 [*] --> DRAFT [*] --> SCHEDULED DRAFT --> SCHEDULED : User schedules SCHEDULED --> PROCESSING : Scanner picks it up PROCESSING --> POSTED : Success PROCESSING --> RETRYING : Temporary failure PROCESSING --> ERROR : Permanent failure PROCESSING --> REVIEW : Needs platform review RETRYING --> PROCESSING : Retry attempt ERROR --> PROCESSING : Manual retry REVIEW --> PROCESSING : Review scanner picks it up ``` ### Status Breakdown | Status | What It Means | What You Should Show | | :- | :- | :- | | `DRAFT` | Saved but not scheduled. No `postDate` set (or set in the past). | "Draft" - editable, not going anywhere yet. | | `SCHEDULED` | Has a future `postDate`. Waiting in line. | "Scheduled for Dec 25 at 10:00 AM" | | `PROCESSING` | We picked it up and are actively publishing it. | "Publishing..." - spinner time. | | `POSTED` | Successfully published to the platform. | "Published" - show the permalink. | | `RETRYING` | Failed, but we're going to try again. | "Retrying..." - don't panic yet. | | `ERROR` | Failed after all retries. Dead. | "Failed" - show the error, offer manual retry. | | `REVIEW` | Platform needs to review it (mostly TikTok). | "Under Review" - patience. | ### Retry Logic When a post fails to publish, we don't give up immediately: * **Max retries:** 3 attempts * **Backoff:** Exponential, starting at 3 minutes * **Between retries:** Status is set to `RETRYING` * **After all retries exhausted:** Status becomes `ERROR` If the error is a "review" error (common with TikTok), the post goes to `REVIEW` instead. We periodically re-check and re-attempt publishing. > [!NOTE] > > **Manual retry:** Users can retry `ERROR` posts via the API. This resets the retry counter and re-queues the post. Max 3 manual retries total - we don't want infinite loops (we've seen things). *** ## Step 1: Connect Accounts Before you can schedule anything, the user needs to connect their social accounts. See the [Connect Flow](/api-reference/connect-social-accounts) guide for the full walkthrough. Quick version: you redirect the user to our OAuth flow, they authorize, we give you a `socialAccountId`. Done. *** ## Step 2: Import History (Optional but Recommended) Don't show an empty calendar. Nobody likes staring at a blank grid wondering if the app is broken. Use the [Post History Import](/api-reference/import-posts) to fetch their recent posts and populate the calendar. ```typescript theme={null} await bundlesocial.postHistoryImport.create({ teamId: 'team_abc', socialAccountType: 'INSTAGRAM', count: 50, withAnalytics: true, }); ``` > [!WARNING] > > **Imported posts are deleted after 30 days.** They're meant to populate your UI, not serve as a permanent archive. If you need them long-term, save them and don't let them go. See [Data Retention](/api-reference/data-retention). *** ## Step 3: Upload Media **Crucial:** Upload media *before* the user hits "Schedule". You need the `uploadId` to create the post. * **Simple Upload** - for images and small files. One request, done. * **Multipart Upload** - for videos. The file goes up in 64 MiB chunks (init, PUT each part, complete), so a dropped connection costs one chunk instead of the whole transfer. See [Media Upload](/api-reference/upload-content) for the full guide. ```typescript theme={null} // Simple upload example const upload = await bundlesocial.upload.create({ teamId: 'team_abc', file: myImageFile, }); const uploadId = upload.id; // e.g. "upload_123" ``` > [!NOTE] > > **Pro tip:** Always use Multipart Upload for videos. If a 500MB upload fails with Simple Upload, your user has to start over - with Multipart they lose one 64 MiB chunk and retry just that. One more thing worth wiring: if `complete` returns a 5xx, the parts are still stored, so retry `complete` rather than re-uploading. Your users will thank you. Your support inbox will thank you. *** ## Step 4: Create the Post Here's where it gets interesting. You can create a post as a **draft** or **schedule it immediately**. ### Schedule for the Future ```typescript theme={null} const post = await bundlesocial.post.create({ teamId: 'team_abc', title: "Launching something big", status: "SCHEDULED", socialAccountTypes: ['INSTAGRAM', 'TIKTOK'], // UTC ISO string postDate: "2026-12-25T10:00:00.000Z", // UTC ISO string // Platform-specific options data: { INSTAGRAM: { type: "REEL", text: "Launching something big tomorrow. Stay tuned.", uploadIds: ['upload_789'] }, TIKTOK: { type: "VIDEO", text: "Launching something big tomorrow. Stay tuned.", uploadIds: ['upload_789'], privacy: "PUBLIC_TO_EVERYONE", disableComments: false, disableDuet: false, disableStitch: false, } } }); ``` > [!WARNING] > > **Timezones matter.** Always send `postDate` in **UTC**. If your user is in Tokyo and picks "10:00 AM", convert that to UTC before sending it to us. If you don't, they'll be posting at 3 AM Tokyo time and blaming you. And then they'll blame us. And then we'll blame you again. ### Save as Draft Set `status: "DRAFT"` and pass an empty `postDate`: ```typescript theme={null} const draft = await bundlesocial.post.create({ teamId: 'team_abc', title: "Draft idea", status: "DRAFT", postDate: "", socialAccountTypes: ['INSTAGRAM'], data: { INSTAGRAM: { type: "POST", text: "Work in progress...", uploadIds: ['upload_789'] } } }); ``` The user can come back later, edit it, and schedule it when ready. ### Platform-Specific Data Options Each platform has its own special fields in the `data` object. Here are the highlights: | Platform | Key Options | | :- | :- | | **Instagram** | `type` (`REEL`, `STORY`, `POST`), `thumbnail`, `thumbnailOffset`, `locationId` | | **TikTok** | `privacy`, `disableComments`, `disableDuet`, `disableStitch`, `autoAddMusic`, `uploadToDraft` | | **YouTube** | `text` (required title), `privacy`, `madeForKids`, `containsSyntheticMedia`, `hasPaidProductPlacement` | | **Facebook** | `type` (`REEL`, `STORY`, `POST`) | | **LinkedIn** | `privacy`, `hideFromFeed`, `disableReshare`, `link` | | **Pinterest** | `boardName` (required - use the board name from `socialAccount.channels`), `text`, `link` | | **Reddit** | `sr` (required, e.g. `r/example`), `text` (title), `flairId` | | **Discord** | `channelId` (required), `username`, `avatarUrl` | | **Slack** | `channelId` (required), `username`, `avatarUrl` | | **Google Business** | `topicType`, `callToActionType`, `callToActionUrl`, event/offer fields | | **Snapchat** | `type` (`STORY` or `SPOTLIGHT`), `description`, `locale`, `skipSaveToProfile` | Check each [platform's page](/api-reference/platforms/index) for the full list of options and their constraints. *** ## Step 5: Edit or Cancel ### Update a Scheduled Post Only `DRAFT` and `SCHEDULED` posts can be updated. Once a post is `PROCESSING` or beyond, it's too late. ```typescript theme={null} await bundlesocial.post.update({ postId: 'post_abc', text: "Updated copy. Much better.", postDate: "2026-12-26T10:00:00.000Z", // Reschedule }); ``` ### Delete a Scheduled Post Soft-deletes the post. Sets status to `DELETED`. ```typescript theme={null} await bundlesocial.post.delete({ postId: 'post_abc', }); ``` If the post was already `POSTED`, this only deletes it from our system - it does NOT remove it from the social platform. We can't un-ring that bell. *** ## Step 6: Handle the Results Scheduling is **asynchronous**. You send us the post, we queue it, and you find out later what happened. There are two ways to know: ### Option A: Webhooks (Recommended) Set up a [webhook endpoint](/api-reference/webhooks) and listen for: | Event | Meaning | What To Do | | :- | :- | :- | | `post.published` | Post finished processing. `data.status` tells you whether it is `POSTED` or `ERROR`. | Update UI from `data.status`; show permalink or error. | | `comment.published` | First comment finished processing. `data.status` tells you whether it is `POSTED` or `ERROR`. | Update UI if you show comment status. | ```typescript theme={null} // Your webhook handler app.post('/webhooks/bundle', (req, res) => { const event = req.body; switch (event.type) { case 'post.published': if (event.data.status === 'POSTED') { await updatePostStatus(event.data.id, 'published'); } else if (event.data.status === 'ERROR') { await updatePostStatus(event.data.id, 'failed'); await notifyUser(event.data.id, event.data.error); } break; } res.status(200).send('OK'); }); ``` > [!NOTE] > > **Verify webhook signatures.** Don't trust random POST requests. We sign every webhook with HMAC SHA256. See [Webhooks](/api-reference/webhooks) for the verification code. ### Option B: Polling If you can't use webhooks, you can poll the post status: ```typescript theme={null} const post = await bundlesocial.post.get({ postId: 'post_abc' }); if (post.status === 'POSTED') { // Show success } else if (post.status === 'ERROR') { // Show error details in post.error } else if (post.status === 'REVIEW') { // Tell user: "Platform is reviewing your post" } ``` Don't poll every 100ms. Once every 30-60 seconds is fine. You won't miss anything by being patient. ### Error Notifications If your organization has `sendEmailOnError` enabled, we'll email the user when their post fails. One less thing for you to build. *** ## Bulk Scheduling Want to schedule 50 posts at once? Go for it. But be smart about it. ### Rate Limits * **API rate limits:** Multi-layer limits per endpoint and tracker (API key / bearer token / IP fallback): burst `100/1s`, short `500/10s`, minute `2000/60s`. See [Rate Limits](/api-reference/rate-limits). * **Platform limits:** Each platform has its own daily posting limits per team. Check our [Platform Limits](/api-reference/rate-limits#posting-daily-limits-per-platform-per-tier) for the exact numbers per tier. If you blast 50 TikToks in an hour, TikTok might have opinions. ### Best Approach ```typescript theme={null} // Space them out. Don't schedule everything for the same second. const posts = contentCalendar.map((item, index) => ({ teamId: 'team_abc', title: item.title, status: 'SCHEDULED', socialAccountTypes: item.platforms, postDate: addMinutes(item.date, index * 5), // 5-minute gaps data: item.data, })); for (const post of posts) { await bundlesocial.post.create(post); } ``` *** ## Best Practices ### 1. Validate Before Scheduling Don't let a user schedule a 10-minute video for an Instagram Story. It will fail. At 3 AM. On Christmas. And they will email you. Check our [Platform Limits](/api-reference/limits) and validate in your UI before sending anything to us. We validate too, but catching errors early is better for everyone. ### 2. Timezones. Seriously. We accept `postDate` in **UTC only**. Convert on your end. Every timezone bug in social media scheduling comes from someone who thought "eh, it's probably fine" and didn't convert. ### 3. First Comment Strategy Use the Comment API to put hashtags in the first comment instead of the caption. It keeps the post clean and looks more professional. ```typescript theme={null} await bundlesocial.comment.create({ teamId: 'team_abc', internalPostId: post.id, title: "First comment", status: "SCHEDULED", postDate: post.postDate, socialAccountTypes: ['INSTAGRAM'], data: { INSTAGRAM: { text: "#growth #mindset #grind #blessed" } } }); ``` Create first comments through the [Comments API](/api-reference/comments), not inside the post payload. Schedule the post first, keep the returned `post.id`, then create the comment with `internalPostId`. ### 4. Remember Data Retention * **Imported posts:** Deleted after 30 days. Store them if you need them. * **Analytics:** Deleted after 30 days. Fetch daily if you're building reports. * **Webhook events:** Deleted 2 days after delivery. Log them on your end. See [Data Retention](/api-reference/data-retention) for the full breakdown. ### 5. Handle the REVIEW Status TikTok (and occasionally other platforms) may put posts into a review state instead of publishing immediately. This is normal. Don't show it as an error - show it as "Under Review" and let us handle it. We periodically re-check and re-attempt publishing. ### 6. Don't Forget `madeForKids` on YouTube This is a **legal requirement** (COPPA). If the content targets children, you must set `madeForKids: true`. If you don't, YouTube will eventually notice, and penalties apply. We expose this field - use it. # Knowledge Base Source: https://info.bundle.social/knowledge/index This is a knowledge base for bundle.social. You can find all the information you need here. ## Categories > [card] [Connect your social accounts](/knowledge/social-accounts/index) > > Series of tutorials on how to connect all of your social accounts to > bundle.social. > [card] [What is an organization](/knowledge/organization/what-is-an-organization) > > manage API keys, webhooks, billing, and settings. > [card] [What are teams in bundle.social](/knowledge/teams/what-are-teams) > > and how do you create one? > [card] [Create first post](/knowledge/posts/create-first-post) > > Use bundle.social to post on multiple platforms. > [card] [Learn about media library](/knowledge/posts/media-library) > > we are providing storage for those on the go. > [card] [Discord and Slack bots](/knowledge/posts/dc-slack-bots) > > it's not a magic, just an annoyance. # Get to know organizations in bundle.social Source: https://info.bundle.social/knowledge/organization/what-is-an-organization Learn how organizations work in bundle.social - manage billing, API keys, and webhooks at the organization level across all of your teams. In this tutorial you will learn how organizations work in bundle.social and what you manage at the organization level. ## What is an organization? An organization is the top-level account in bundle.social. Each organization can contain many teams, and a few things are shared across all of them: **API keys**, **webhooks**, and **billing** are managed at the organization level rather than per team. You'll find all of these in the **Organization** section of the sidebar. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/menu.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=d37f259aff369700496216666130309b) ## Create an API key If you want to automate your bundle.social workflow, you can use our API or SDK - [learn more here](/api-reference/introduction). In the sidebar, click **API Keys**. This is where you create and manage API access. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/api-keys.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=124c22e6375cd7428a8f638352264932) Click **+**, enter a name for the key, and click **Create**. > [!WARNING] > > You can only see an API key once, so copy it and store it somewhere safe. > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/create-api-key-modal.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=68909868ebfd6f0c8084577ff247f316) > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/copy-api-key.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=28795d839301ec507317078c296bc659) ## Add a webhook In the sidebar, click **Webhooks**. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/webhooks.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=ad3a57c337c74fe4905cb52130ff6608) Click the **+** icon. In the popup, enter the URL you want to receive webhook events on. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/add-webhook.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=ba5949b89c35975cc2dd5ba0810dbf21) ## Manage billing To change your plan, click **Billing**. Plans can be billed monthly or yearly using the picker at the top. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/billing.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=18c8bc765baa34b850ae754f4b3b5c0a) The **Invoices** tab lists issued invoices and lets organization owners download the available invoice document directly from bundle.social. If a subscription is paused or scheduled to end, Billing also shows the available resume action before you attempt another plan change. The **Usage** view shows your post count, API usage, and analytics status for the current period. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/usage.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=a21265154eeea78c08011d6cc49cf6f9) ## Organization settings Click **Settings** to update your organization's basic information and preferences: * **Organization name** - the display name for your organization. * **Enable uploads compression** - compress video uploads to reduce file size and storage costs. * **Show verbose errors** - display detailed error messages in post details. Useful for debugging, but may contain technical information. * **Automatic remote disconnect checks** - run periodic disconnect checks for Facebook, Instagram, and Threads. Disable to opt out of automatic detection. * **Delete disconnected account after** - how many hours to wait before deleting a disconnected social account (0-168, up to 7 days). Click **Save changes** to apply. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/organization/settings.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=202c3edbf852aef8b56dc13c64f9451b) ## Summary You now know what lives at the organization level - API keys, webhooks, billing, and settings - all shared across the teams inside your organization. with lukewarm regards c: - bundle.social staff # Make your first posts with bundle.social Source: https://info.bundle.social/knowledge/posts/create-first-post Create and schedule your first post across several platforms at once, with per-platform customization and the Discord and Slack quirk explained. > [!WARNING] > > 🥺 YOU CAN POST DIFFERENT CONTENT TO ALL THE PLATFORMS ALL AT ONCE 🥴 In this tutorial you will create, customize, and publish your first post across several platforms at once. ## Open the post creator On the sidebar, click **Posts**. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/sidebar-posts.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=603ef6ab9e696941e2ec2b9bcb7334a9) This is your **Posts** dashboard. It's empty for now - click the **+** icon to open the post creator. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/posts-dashboard-empty.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=6cad99b107810142968e1b57a0d38af6) The first page of the post creator is strictly internal. Here you pick which account to post on, what content to post, and when. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/post-creator.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=f8b63488115fd37ce013e4044a79764b) > [!NOTE] > > You can change all of this later, so if your creative juices aren't flowing > from the get-go, don't worry. ## Pick the platforms At the top of the screen you'll see every account connected **to the team you're currently on**. Click a tile to select the account you want to post on. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/select-account.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=aba2de903fef4171f73b2741714b22ac) For this tutorial we'll post to all four connected platforms: * **YouTube** and **Instagram** for video * **LinkedIn** for company updates * **Discord** to engage with the community ## Pick the content You might be on the go and not have the right content on hand. That's why we have the **media library** - internal storage for all of your assets. [Learn more about it here.](/knowledge/posts/media-library) Click **Select media**. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/select-media-button.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=1626d0332a1c57e7c98c4675e842866e) Here you can see all of your media. Pick from what's there or **upload something new**. We'll add one new photo and pull the rest from the [media library](/knowledge/posts/media-library). ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/media-library.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=e4a86aba032eb2741eeaf34b0198df5a) ## Set the time Say your boss wants a post every 3 hours. Instead of sitting down every 3 hours, pick a time once and forget about it. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/set-time.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=1ef427542db35a722b4bb94a28f292f7) > [!TIP] > > If you don't set a time, or set one earlier than the current time, the post > publishes as soon as processing finishes. ## Customize your content In the bottom right corner, click **Customize**. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/customize-button.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=e8da8508b8c469fbbcce2587e2104e9b) Your screen should now look like this: ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/customize-view.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=24a89296af5f46c95f3b090ed9da085a) Starting from the top: * **Title** - internal only * **Date** - when to post Below that are platform icons - these act as tabs. Click between them and you'll notice the fields change: YouTube has a **Text** field and a **Description** field, while Instagram only has **Text**. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/platform-tabs.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=a1c9b2ed2732ad848d8222ed9b526a3f) ### Adjust the content per platform Each tab has its own content field. Hover over a piece of content to delete it - for example, on the YouTube tab we keep only the video we want to post. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/adjust-content-youtube.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=3b7cd43204c0311fe8503c947d712070) > [!WARNING] > > To post multiple images - for example a carousel on Instagram - just leave the > content untouched. We support multi-content on every platform that offers it. Next, switch to the Instagram tab and remove any content you don't want there. > [!NOTE] > > You can also add content at this step. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/adjust-content-instagram.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=f23485cd43ffbf21c6e047422e831540) Now do the same for the remaining platforms. > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/adjust-content-linkedin.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=0110a2a966550572e7fd5ac7840e6996) > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/adjust-content-discord.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=1b88a8b3af05f33d7ff66bb1f8b6f3ac) ## Discord and Slack quirk If you post to Discord or Slack without changing the sender, your message shows up like this: > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/discord-default-sender.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=eaa40940371f44a4dda5e995a8fc3e9b) That's fine if you don't mind. If you do, click the **+** icon to create a new bot. > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/create-bot-button.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=193db0bd24a6b35f5d49aced4eb988b8) A popup appears - upload a bot cover photo and give it a name. The name is shown as the sender in Discord/Slack, so choose carefully. Then click **Create**. > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/create-bot-modal.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=be794a55569db9131738bbac293ed2f2) Your bot is ready to reuse next time. **Don't forget to select the newly created bot from the dropdown.** > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/select-bot.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=4103b79b841555ec5babc5f802e5443d) Now your Discord sender looks like this: > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/discord-bot-sender.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=33f4cc96a14bac65f5a48597e909ef81) > [!NOTE] > > To learn more about bots, [read the bots guide](/knowledge/posts/dc-slack-bots). ## Publish With your captions and images in place, it's time to post. Click **Publish**. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/publish-button.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=9a951ba32b9cad5cefde39c11c60c7b1) The page refreshes and you're back on the **Posts** dashboard - this time with your post on it. If it includes a lot of content, like several large videos, the post may show a **processing** or **scheduled** status. Don't worry, the rest will be published. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/post-dashboard.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=be96ed94bab7b2e526f20c08a66f7ee7) You can also switch to the **calendar view** to see your scheduled and published posts laid out by date. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/calendar-view.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=0580cf796e6ac28591e23684b220f1b7) ## Access the content Click the post instance to see a list of links to each published post. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/post-instance-links.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=d0274ffdf1d9d64445db318efb76efb6) Here's our LinkedIn post: ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/linkedin-post.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=11eb5279442b3542b411a212ae6cffd4) ## Deleting a post For security reasons you can't delete a published post from our app - you can only remove the post instance from bundle.social. > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/remove-post.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=d6ed084a77a6a18059bcd2fd64184b75) > [card] > > ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/remove-post-confirm.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=ee369c5842aca10a110f6a2e7fa41862) If you'd like to delete posts directly through bundle.social, send us an email. If enough people ask, we'll enable that option - 50/50. # Discord and Slack bots on bundle.social Source: https://info.bundle.social/knowledge/posts/dc-slack-bots Learn how to create and manage Discord and Slack bots for posting content through bundle.social. Understand why bots are required and how to set them up. ## Why bots? Discord and Slack don't allow API access to user accounts. To automate anything, they provide **bots** and an API to control them - so that's what bundle.social uses. No tomfoolery on our side. ## How to create a bot There are two ways to create a bot. You can do it while [creating a post](/knowledge/posts/create-first-post#discord-and-slack-quirk), or from the **Bots** page. Click **Bots** in the sidebar. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/bots-sidebar.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=2e913565ad48db11a1413b44cf922e75) This is your **Bots** dashboard. It's empty for now - click the **+** icon to open the bot creator. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/bots-dashboard-empty.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=f65b2da3d04b5db3160f260aebdbafe6) A popup appears. Upload a bot cover photo and give it a name. The name is shown as the sender in Discord/Slack, so choose carefully. Then click **Create**. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/create-bot-modal.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=be794a55569db9131738bbac293ed2f2) Done - your new bot now shows up in the bot list. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/bot-in-list.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=50217b06d22f1bbea904f3f49108abac) Later, when you create a post that goes to Discord or Slack, **don't forget to pick your bot from the dropdown**. ![](https://mintcdn.com/bundlesocial/Xo58NLADtmHCNVc_/images/knowledge/posts/select-bot.png?fit=max\&auto=format\&n=Xo58NLADtmHCNVc_\&q=85\&s=4103b79b841555ec5babc5f802e5443d) # What is the Media Library? Source: https://info.bundle.social/knowledge/posts/media-library Learn how to use the Media Library in bundle.social to store, organize, and manage your social media content. Upload, filter, and track used vs unused media. ## Media Library is a "storage" Yes and no. Let us explain how it works. Media in bundle.social is either: * **used** - you made a post with it, * **unused** - you did not make a post with it. ## How to use the Media Library On the sidebar, click **Media Library**. ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/001_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=6eaa55fbcde888e9b7444a4dedc38220) Now you can see your **Media Library** dashboard. To upload something, either click on the **gray** area or just drop it there. You can also **paste a public URL** in the upload flow so we fetch the file for you (**1 GB** max, **60 second** download window-see [Media Upload](/api-reference/upload-content#upload-from-a-url)). > [card] > > ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/002_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=75579145a233e163c2afd8764cbfebdd) > [card] > > ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/003_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=b9c433ad59b650801c6fa50e9ef4662e) ## How to see content details? Sometimes, if you have multiple versions of a photo/video, you aren't sure if the one you uploaded is the correct one. To check the metadata of the content, hover over the content and click the **eye** icon. > [card] > > ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/004_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=bd0e73bf96030a9dd576f692f4452201) Now you can see the metadata. > [card] > > ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/005_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=52309052efe6f79aa3a53ffdbc2fd108) ## How to delete content from the Media Library? You can hover over content and press the **trash bin** icon or select multiple pieces of content and click **Delete selected**. ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/006_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=a770a264096c6fccec042c809c5c9b2c) > [!NOTE] > > By deleting content that is unused, you are updating your **unused uploads** > limit. ## Filtering in the Media Library Here you can see two filters: one is for status, and the second one is for type, which is either: * image, * video. That's self-explanatory, so let us focus on the status filter. > [card] > > ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/007_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=2216fd7d995ddb7dc656c594ee777537) > [card] > > ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/008_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=a93c256993850a2ed25be29b393d54be) When set to **All**, you can see **ALL** of your content. ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/009_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=de58391b975c27efc7160fffe6d1ddf3) When set to **Used**, you can see **ONLY USED** content. This is the content that you have already used on some platform, like Instagram. ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/010_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=697afdf299aeebaaa52629caea574a37) When set to **Unused**, you can see **ONLY UNUSED** content. This is the content that is not posted anywhere. ![](https://mintcdn.com/bundlesocial/I73jzIjdXCLeLiMD/images/knowledge/media-library/011_media_library.png?fit=max\&auto=format\&n=I73jzIjdXCLeLiMD\&q=85\&s=fa212a35d94c661e2e6ce7926ca4b591) ## Summary The Media Library is a neat feature that lets you post on the go and see what content you have already used. # Connect your Bluesky account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/bluesky Learn how to connect Bluesky to bundle.social using AT Protocol OAuth. In this tutorial, you will learn how to connect a Bluesky account to your team. First things first, create a team or be a part of one If you don't know what teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Bluesky account Open **Social accounts** from the dashboard sidebar and click **Connect** on the Bluesky tile. Bluesky uses AT Protocol OAuth. You may be asked for the account handle and authorization server. For most users, this is the default Bluesky server. Advanced users can use a custom server if their account uses a different issuer. Authorize bundle.social in Bluesky and return to the dashboard. Bluesky does not require channel selection after OAuth. ## What you can do after connecting * publish text posts, * attach up to 4 media files, * create quote posts with `data.BLUESKY.quoteUri`, * add external link cards, * create and import replies, * fetch limited analytics based on available AT Protocol data. ## Errors \[!WARNING] Missing or invalid Bluesky server. Use the default Bluesky issuer unless the account belongs to a custom AT Protocol service. \[!WARNING] This team already has a Bluesky account connected. Each team can connect one Bluesky account. Disconnect the existing account first if you need to replace it. \[!WARNING] Authorization failed. The OAuth session may have expired or the account rejected the request. Start the connection again from bundle.social. # Connect your Discord account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/discord Step-by-step guide to connecting your Discord account to bundle.social. Learn how to authorize permissions and set up Discord bots for automated posting. > [!WARNING] > > Discord and Slack is weird with their API's, to post content you need to use > BOT's that you will create. \ > Don't worry it's their way of doing things not our magic so they wont ban you [**learn > more**](/knowledge/posts/dc-slack-bots.mdx). In this short tutorial you will learn how to connect your Discord account to bundle.social First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Discord account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the Discord tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/discord/001_discord.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=64cf21abde3b838a861ecd5aed6f271b) You will be asked to log. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/discord/002_discord.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=922489f2261bc928f30e794e2c52c1bb) Next, you will see what permissions we need for the app to run. Click **Continue**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/discord/003_discord.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=ece8b2ce49e703b043c18296de8a16a2) Now you will see additional info about permissions, click **Authorize**. > [!NOTE] > > bundle.social staff does not have access to your account or account keys, we > cannot delete your account. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/discord/004_discord.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=5e8a281889c7a58101057278ba760363) After a successful connection, you will be redirected back to bundle.social, and you should see a green popup on the right-hand side, and the Discord tile button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/discord/005_discord.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=02837eadd9d5eaf6c1a0cf7690d2fbf1) ## Errors There should be no errors at this point, but if there are, it will be these two: \[!WARNING] Error connecting to Discord This can mean many things outside our control, maybe Discord had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. > [!WARNING] > > You don't have enough permissions in any of your Discord servers. You are probably not an admin for your Slack workspace. # Connect your Facebook account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/facebook Complete tutorial on connecting your Facebook page to bundle.social. Learn how to authorize permissions and start scheduling Facebook posts. In this tutorial, you will learn how to connect your Facebook account to your team. First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Facebook account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the Facebook tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/001_facebook.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=e73f971fd7cdff480ca9a7d67b6c46b1) You will be asked to log in. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/001_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=c2bf322e98c9f7e53c82980af0253315) > [!NOTE] > > bundle.social staff does not have access to your account or account keys, and > we cannot delete your account. Next, you will be able to pick the Facebook page that you want to post on. Each team can manage only one account/page, so pick the page you like and click **Continue**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/002_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=5529d1cbdcbfc02df039a56317d5a3c3) Now you will be asked to pick an Instagram account. We don't know why they did it like that, but you can't omit this step. We don't use it unless you connect your Instagram separately, so it's just there. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/003_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=7fcb18d5a076d1f5a8b0da2a194eeaad) After the whole page selection debacle, you will see what permissions we are accessing. Click **Save**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/004_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=dccbcc4f4ef39ce6710e384f57cf867b) Here you can see the connection confirmation. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/005_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=032d3040ab351ef6d658f5f05a09d8fc) You will be redirected back to bundle.social, where you will be asked to pick the Facebook page that you want to manage. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/002_facebook.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=fec39e34a33e50c2d2e17aeb3293f798) Pick the page and click **Confirm**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/003_facebook.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=90ffbae84cad50295178f733309f6e05) After a successful connection, you should see a green popup on the right-hand side, and the YouTube button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/004_facebook.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=47e15d07405c6cf6b454eb68dc4ea4ae) > [!NOTE] > > Meta sometimes asks whether to use **Business** login or a **standard** connection. If a **Page does not appear** in the picker, reconnect and try the **other** option-many accounts only show up with business-scoped permissions. Same story if our app shows **Reauthenticate**: use it when the connection looks stale instead of assuming the picker is broken. More detail: [Connect Social Accounts](/api-reference/connect-social-accounts) (section **withBusinessScope**). ## Errors There should be no errors at this point, but if there are, they will likely be one of these two: \[!WARNING] Error connecting Facebook. This can mean many things outside our control, maybe Facebook had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. > [!WARNING] > > You don't have enough permissions on any of your Facebook pages. You are probably not an admin for your Facebook page. # Connect your Google Business Profile to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/google-business Learn how to connect Google Business Profile to bundle.social and select the business location for your team. In this tutorial, you will learn how to connect a Google Business Profile location to your team. First things first, create a team or be a part of one If you don't know what teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Google Business Profile Open **Social accounts** from the dashboard sidebar and click **Connect** on the Google Business tile. You will be redirected to Google. Log in with an account that has access to the Business Profile locations you want to manage and allow the requested permissions. After OAuth succeeds, return to bundle.social and select the Google Business location for this team. > [!WARNING] > > Location selection is required. If no location is selected, the account is connected but publishing, location management, reviews, and analytics can fail because the team has no `externalId` for Google Business. ## What you can do after connecting * publish Google Business updates, events, offers, and alerts, * read and update location profile data, * manage hours, attributes, services, menus, action links, and profile media, * import Google reviews and manage owner replies, * fetch location-level raw analytics. ## Errors \[!WARNING] No Google Business location selected. Select a location after OAuth. If you use a custom API flow, call `POST /api/v1/social-account/set-channel` with `type: "GOOGLE_BUSINESS"` and the selected location ID. \[!WARNING] This team already has a Google Business Profile connected. Each team can connect one Google Business account and selected location. Disconnect the existing account first if you need to replace it. \[!WARNING] You don't have access to this Google Business location. Reconnect with a Google account that has permission to manage the location. # Social Accounts Source: https://info.bundle.social/knowledge/social-accounts/index Tutorials for connecting every supported platform to bundle.social. Each one ends with an error section, so you can fix issues as they come up. ## Connect your social media accounts > [card] [Connect TikTok](/knowledge/social-accounts/tiktok) > > Authorize TikTok and start publishing videos or photo posts. > [card] [Connect YouTube](/knowledge/social-accounts/youtube) > > Connect a Google account and choose the YouTube channel for your team. > [card] [Connect Snapchat](/knowledge/social-accounts/snapchat) > > Connect a Snapchat Public Profile for Stories, Spotlights, and analytics. > [card] [Connect Instagram](/knowledge/social-accounts/instagram) > > Connect Instagram directly or through Facebook Login, depending on your workflow. > [card] [Connect Facebook](/knowledge/social-accounts/facebook) > > Authorize Meta and choose the Facebook Page your team should manage. > [card] [Connect X (Twitter)](/knowledge/social-accounts/x) > > Connect X for scheduled posts with text and media. > [card] [Connect LinkedIn](/knowledge/social-accounts/linkedin) > > Connect a LinkedIn profile or organization page. > [card] [Connect Pinterest](/knowledge/social-accounts/pinterest) > > Connect Pinterest and publish Pins to available boards. > [card] [Connect Reddit](/knowledge/social-accounts/reddit) > > Connect Reddit and publish to subreddits your account can access. > [card] [Connect Threads](/knowledge/social-accounts/threads) > > Connect Threads for text and media posts. > [card] [Connect Mastodon](/knowledge/social-accounts/mastodon) > > Connect a Mastodon account from your instance. > [card] [Connect Bluesky](/knowledge/social-accounts/bluesky) > > Connect Bluesky with AT Protocol app credentials. > [card] [Connect Discord](/knowledge/social-accounts/discord) > > Connect Discord and publish messages through selected webhooks. > [card] [Connect Slack](/knowledge/social-accounts/slack) > > Connect Slack and publish messages to selected channels. > [card] [Connect Google Business](/knowledge/social-accounts/google-business) > > Connect a Google Business Profile and select the location for your team. # Connect your Instagram account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/instagram Learn how to connect your Instagram account to bundle.social. Follow our step-by-step guide to authorize permissions and start scheduling Instagram posts. In this tutorial, you will learn how to connect your Instagram account to your team. First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Instagram account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the Instagram tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/001_instagram.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=ecf702d76a9f212cccf1f3b76c5569db) You will be asked to log in. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/001_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=c2bf322e98c9f7e53c82980af0253315) > [!NOTE] > > bundle.social staff does not have access to your account or account keys, and > we cannot delete your account. Next, you will be able to pick the Facebook page. We don't know why they did it like that, but you can't omit this step. We don't use it unless you connect your Facebook separately, so it's just there. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/002_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=5529d1cbdcbfc02df039a56317d5a3c3) Now you will be asked to pick an Instagram account. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/003_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=7fcb18d5a076d1f5a8b0da2a194eeaad) After the whole page selection debacle, you will see what permissions we are accessing. Click **Save**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/004_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=dccbcc4f4ef39ce6710e384f57cf867b) Here you can see the connection confirmation. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/005_meta.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=032d3040ab351ef6d658f5f05a09d8fc) You will be redirected back to bundle.social, where you will be asked to pick the Instagram account that you want to manage. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/002_instagram.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=9222ff3e1949342cc205455e33b813ac) Pick the account and click **Confirm**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/003_instagram.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=a166ae166024a3c95f997566d84ece17) After a successful connection, you should see a green popup on the right-hand side, and the Instagram button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/meta/004_instagram.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=867929c6fc711497e5eaa37ffeebf04c) > [!NOTE] > > If you connect Instagram through the Facebook flow, you may be offered **Business** vs **standard** login. Some **Instagram accounts only appear** when you use business-scoped permissions. If the account you need is missing, try reconnecting with the other method. **Reauthenticate** in the app is there when we detect a bad connection. See [Connect Social Accounts](/api-reference/connect-social-accounts) (section **withBusinessScope**). ## Errors There should be no errors at this point, but if there are, they will likely be one of these two: \[!WARNING] Error connecting Instagram. This can mean many things outside our control, maybe Instagram had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. > [!WARNING] > > You don't have enough permissions on any of your Instagram accounts. You are probably not an admin for your Instagram account. # Connect your Linkedin account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/linkedin Tutorial on connecting your LinkedIn account or page to bundle.social. Learn how to authorize permissions and start scheduling LinkedIn posts. In this short tutorial you will learn how to connect your Linkedin account to bundle.social First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Linkedin account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the Linkedin tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/linkedin/001_linkedin.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=4e3ec340630ba4c17f1414eba3b4d4a1) You will be asked to log in. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/linkedin/002_linkedin.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=db097726539d75065892e51a80c1d907) > [!NOTE] > > bundle.social staff does not have access to your account or account keys, we > cannot delete your account. After successful login you will be prompted to pick what page or account you want to manage. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/linkedin/003_linkedin.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=524d4d07611192b6e80cf56528f14788) Now pick the account that you want to use and click **Confirm**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/linkedin/004_linkedin.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=efabe3879b942540936c1aa99f964095) After a successful connection, you should see a green popup on the right-hand side and the Linkedin button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/linkedin/005_linkedin.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=1a70a1f5edb6f78d414e455193218643) ## Errors There should be no errors at this point, but if there are, it will be these two: \[!WARNING] Error connecting to Linkedin This can mean many things outside our control, maybe you don't have a Linkedin account connected to this Google account or Linkedin had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. > [!WARNING] > > You don't have enough permissions in any of your LinkedIn organizations. You are probably not an admin for picked account. # Connect your Mastodon account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/mastodon Learn how to connect a Mastodon account from your instance to bundle.social. In this tutorial, you will learn how to connect a Mastodon account to your team. First things first, create a team or be a part of one If you don't know what teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Mastodon account Open **Social accounts** from the dashboard sidebar and click **Connect** on the Mastodon tile. Enter the Mastodon server URL for the account you want to connect, for example `https://mastodon.social`. bundle.social registers an OAuth client for that instance and redirects you to the instance authorization screen. Log in on your Mastodon instance, approve the requested permissions, and return to bundle.social. Mastodon does not require channel selection after OAuth. ## What you can do after connecting * publish statuses with text and media, * choose Mastodon visibility with `data.MASTODON.privacy`, * add content warnings with `data.MASTODON.spoiler`, * import replies, * reply to imported comments. ## Errors \[!WARNING] Invalid Mastodon server URL. Use the full instance URL, including `https://`. The server must support Mastodon OAuth. \[!WARNING] This team already has a Mastodon account connected. Each team can connect one Mastodon account. Disconnect the existing account first if you need to replace it. \[!WARNING] You didn't grant all the necessary permissions. Reconnect and allow the requested permissions so publishing and comments can work. # Connect your Pinterest account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/pinterest Learn how to connect your Pinterest account to bundle.social. Follow our guide to authorize permissions and start scheduling Pinterest pins. In this short tutorial you will learn how to connect your Pinterest account to bundle.social First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Pinterest account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the Pinterest tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/pinterest/001_pinterest.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=86fcbe0a53a540727181f5c9a1a9c78e) You will be asked to log. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/pinterest/002_pinterest.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=c07ef8a2b5d16ddfbb4989a5467d22ca) Next, you will see what permissions we need for the app to run. Click **Allow**. > [!NOTE] > > bundle.social staff does not have access to your account or account keys, we > cannot delete your account. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/pinterest/003_pinterest.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=dc12d39637535b0e423dcfa456963a58) After a successful connection, you will be redirected back to bundle.social, and you should see a green popup on the right-hand side, and the Pinterest tile button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/pinterest/004_pinterest.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=2327f3cf57c7e57643aeb3d1dd76557f) ## Errors There should be no errors at this point, but if you encounter one, it might be this: \[!WARNING] Error connecting to Pinterest This can mean many things outside our control, maybe Pinterest had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. # Connect your Reddit account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/reddit Step-by-step guide to connecting your Reddit account to bundle.social. Learn how to authorize permissions and start scheduling Reddit posts. In this short tutorial you will learn how to connect your Reddit account to bundle.social First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Reddit account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the Reddit tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/reddit/001_reddit.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=48921842ce3523d7101cc43f0b6129a4) You will be asked to log. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/reddit/002_reddit.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=419e181b1f5242a2e0327369e5bddcc2) Next, you will see what permissions we need for the app to run. Click **Allow**. > [!NOTE] > > bundle.social staff does not have access to your account or account keys, we > cannot delete your account. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/reddit/003_reddit.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=865ec21a05e94bf6e5d5af1a78749b6c) After a successful connection, you will be redirected back to bundle.social, and you should see a green popup on the right-hand side, and the Reddit tile button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/reddit/004_reddit.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=66816c806707b81124c7f33f405237f7) ## Errors There should be no errors at this point, but if you encounter one, it might be this: \[!WARNING] Error connecting to Reddit This can mean many things outside our control, maybe Reddit had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. # Connect your Slack account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/slack Complete guide to connecting your Slack workspace to bundle.social. Learn how to authorize permissions and set up Slack bots for automated posting. > [!WARNING] > > Discord and Slack is weird with their API's, to post content you need to use > BOT's that you will create. \ > Don't worry it's their way of doing things not our magic so they wont ban you [**learn > more**](/knowledge/posts/dc-slack-bots.mdx). In this short tutorial you will learn how to connect your Slack account to bundle.social First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Slack account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the Slack tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/slack/001_slack.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=84b161ce32ec9f75ac07b4d4c1618a1e) Great, now allow all access for the app and click. **Allow**. > [!NOTE] > > bundle.social staff does not have access to your account or account keys, we > cannot delete your account. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/slack/002_slack.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=020aaab9ac43e7aa12d657fa45a1e2ae) After a successful connection, you will be redirected back to bundle.social, and you should see a green popup on the right-hand side, and the Slack tile button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/slack/003_slack.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=077b4a3d97685a2f15a71efbbc3b3a66) ## Errors There should be no errors at this point, but if there are, it will be these two: \[!WARNING] Error connecting to Slack This can mean many things outside our control, maybe Slack had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. > [!WARNING] > > You don't have enough permissions in any of your Slack workspaces. You are probably not an admin for your Slack workspace. # Connect your Snapchat account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/snapchat Connect a Snapchat Public Profile to bundle.social for Stories, Spotlights, and analytics. Snapchat integration works with **Snapchat Public Profiles**. Make sure the Snapchat user you authorize can manage the Public Profile you want to publish to. ## Connect Snapchat 1. Open **Social accounts** from the dashboard sidebar. 2. Click **Connect** on the Snapchat tile. 3. Log in to Snapchat with the user that manages the Public Profile. 4. Approve the requested Public Profile permissions. 5. After Snapchat redirects you back, confirm that the tile shows the Public Profile name and a **Disconnect** button. There is no separate channel picker. bundle.social uses the Public Profile returned by Snapchat during OAuth. ## What You Can Do * publish a Public Story with one image or MP4 video, * publish a Spotlight with one MP4 video, * schedule Snapchat content with other platforms, * retrieve Public Profile, Story, and Spotlight analytics. See the [Snapchat API guide](/api-reference/platforms/snapchat) for post fields and media limits. ## Troubleshooting > [!WARNING] > > No Snapchat Public Profile was found. The authorized user does not have access to an eligible Public Profile. Create or finish configuring the profile in Snapchat, then reconnect. > [!WARNING] > > You didn't grant all required permissions. Disconnect Snapchat, start the connection again, and approve all requested permissions. > [!WARNING] > > Snapchat media is still processing. This is normally temporary. Keep the post in its current state while bundle.social polls Snapchat and completes publishing. # Connect your Threads account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/threads Learn how to connect Threads to bundle.social and start publishing text and media posts. In this tutorial, you will learn how to connect a Threads account to your team. First things first, create a team or be a part of one If you don't know what teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your Threads account Open **Social accounts** from the dashboard sidebar and click **Connect** on the Threads tile. You will be redirected to the Threads authorization screen. Log in with the account you want to manage and allow the requested permissions. After authorization, you will return to bundle.social. Threads does not require a separate channel selection step, so the account is ready once the connection succeeds. ## What you can do after connecting * publish text posts, * publish image and video posts, * import replies, * reply to imported replies, * fetch profile and post analytics. ## Errors \[!WARNING] Error connecting Threads. This usually means the OAuth flow was interrupted, the account was not eligible, or Threads temporarily rejected the authorization. Try connecting again. \[!WARNING] You didn't grant all the necessary permissions. Reconnect and allow all requested permissions. Missing reply or insights permissions can block comment import or analytics later. # Connect your TikTok account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/tiktok Learn how to connect your TikTok account to bundle.social. Follow our step-by-step guide to authorize permissions and start scheduling TikTok videos. In this short tutorial, you will learn how to connect your TikTok account to bundle.social. First things first, create a team or be a part of one If you're unfamiliar with what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your TikTok account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this: ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the TikTok tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/tiktok/001_tiktok.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=da9a664f412a877c7f59dcb6df95ec8c) You will be asked to log in; choose your preferred method and proceed. We picked Google. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/tiktok/002_tiktok.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=22e34c195a455690b85f42ce0e3104fb) Next, you will be prompted to pick which Google account you want to log in with. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/tiktok/003_tiktok.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=107b39b4802f9294deb617016b6ea9bc) Log in. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/tiktok/004_tiktok.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=5fa67eef08a4f6fb3c5713b29f9d0e96) Great, now allow all access for the app by selecting all the checkboxes and clicking **Continue**. > [!NOTE] > > bundle.social staff does not have access to your account or account keys; we > cannot delete your account. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/tiktok/005_tiktok.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=0316fd40c916f9eca8ed4ac89e098fdc) After a successful connection, you will be redirected back to bundle.social, and you should see a green popup on the right-hand side, and the TikTok tile button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/tiktok/006_tiktok.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=8d360654ad4f8799dbb4c8ef358412ef) ## Errors There should be no errors at this point, but if there are, they will likely be these two: \[!WARNING] Error connecting to TikTok This can mean many things outside our control maybe there was a bug with Tiktok or a timeout. If you encounter this error, simply retry. Most often, it will resolve the issue. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. \[!WARNING] You don't have enough permissions. Remember when we earlier told you to grant the app all access? You probably didn't. \ Click **Disconnect** and connect your account again, this time with all permissions. # Connect your X (Twitter) account to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/x Step-by-step tutorial on connecting your X (Twitter) account to bundle.social. Learn how to authorize permissions and start scheduling tweets. In this short tutorial you will learn how to connect your X (Twitter) account to bundle.social First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your X (Twitter) account bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the X (Twitter) tile. ![](https://mintcdn.com/bundlesocial/bcahQIsdvGFrEIjL/images/knowledge/social-accounts/x/001_x.png?fit=max\&auto=format\&n=bcahQIsdvGFrEIjL\&q=85\&s=e13aa65e1d3c8aba9a7fafaafce20540) You will be asked to log in. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/x/002_x.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=8f7eb30450ca67574adabcc7d03e6c05) Great, now allow all access for the app and click. **Authorize app**. > [!NOTE] > > bundle.social staff does not have access to your account or account keys, we > cannot delete your account. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/x/003_x.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=b1894fa5654320b3c599d2bdba07c9ff) After a successful connection, you will be redirected back to bundle.social, and you should see a green popup on the right-hand side, and the X (Twitter) tile button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/x/004_x.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=b4c46d2065718aedfc8ad2952c19bbd6) ## Errors There should be no errors at this point, but if you encounter one, it might be this: \[!WARNING] Error connecting to Twitter This can mean many things outside our control, maybe X (Twitter) had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. # Connect your Youtube channel to bundle.social Source: https://info.bundle.social/knowledge/social-accounts/youtube Complete guide to connecting your YouTube channel to bundle.social. Learn how to authorize permissions and start scheduling YouTube videos. In this tutorial, you will learn how to connect your YouTube channel to your team. First things first, create a team or be a part of one If you don't know what the teams are, [click here](/knowledge/teams/what-are-teams) to get up to speed. ## Connect your YouTube channel bundle.social is built in a way that won't let you down. If you are in a team and there is no social account connected, your dashboard will look like this. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/001_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0c0be1e305843bba029a81047a89efd5) But if you are a new person joining an existing team, you will most likely see the **Post** page first. If so, navigate to the left corner of the screen and press the **Social accounts** button. Click it and *voilà*, you are in the right place. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/002_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=90a187c94257c28840e0b125aec72259) Now, click **Connect** on the YouTube tile. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/003_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=36a047348834b3a12a2d00b99cc7a38a) You will be asked to log in via Google. You can choose an existing account or create a new one, but remember to create a channel first. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/004_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=0816d605304bcf596a08886419127da4) Next, you will be prompted to allow login with the chosen account, click **Continue**. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/005_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=949f1ea781f159ea70dfa2bda768c43d) Great, now allow all access for the app, by selecting all of the checkboxes and clicking **Continue**. > [!NOTE] > > bundle.social staff does not have access to your account or account keys, we > cannot delete your account. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/006_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=1c3480a022eed8b5958671c1efa66c5b) You will be redirected back to bundle.social, where you will be asked to pick the YouTube channel that you want to manage. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/007_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=505a3be9a325996506737e26d2a9aff9) Pick the channel and click **Confirm**. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/008_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=66547e06f5f932f47e6f93e5265f951b) After a successful connection, you should see a green popup on the right-hand side and the YouTube button should say **Disconnect**. ![](https://mintcdn.com/bundlesocial/hdzKNcwHOKKDs1Cc/images/knowledge/social-accounts/youtube/009_youtube.png?fit=max\&auto=format\&n=hdzKNcwHOKKDs1Cc\&q=85\&s=829a4cd397ae8f8f6ec4f4961fb8e51f) ## Errors There should be no errors at this point, but if there are, it will be these two: \[!WARNING] Error connecting to YouTube This can mean many things outside our control, maybe you don't have a YouTube channel connected to this Google account or YouTube had a bug or there was a timeout. If you get this error, simply retry. Most often, it will help. > [!WARNING] > > You didn't grant all the necessary permissions This means that you didn't grant all the permissions we need to post on your behalf. You can try to reconnect and grant all the permissions. > [!WARNING] > > You don't have enough permissions on any of your YouTube channels. Remember when we earlier told you to grant the app all access? You probably didn't. \ Click **Disconnect** and connect your account again, this time with all permissions. # Get to know teams in bundle.social Source: https://info.bundle.social/knowledge/teams/what-are-teams How teams work in bundle.social: create them, switch between them, manage settings. A team is a social set grouping accounts for one brand or client. In this tutorial you will learn how teams work in bundle.social - how to create them, switch between them, and manage their settings. ## What is a team? Each organization can have many teams. A team is a **social set** - a group of social accounts that belong to a single entity, such as a company, a project, or a personal brand. A team holds **one account per platform**: one Instagram account, one Facebook Page, one TikTok, and so on. If you manage several Facebook Pages or Instagram accounts, create one team for each; the same Facebook or Instagram login can be used to connect all of them. Teams are only a way of grouping accounts, and paid plans have no limit on how many you create. SaaS products usually create one team per end user or client through the API (`POST /api/v1/team`). ## Create a team When you join for the first time, you'll be asked to create your first free team. You can upgrade it later. ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/onboarding-create-team.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=f8c2fed2d8b3312993e9a3cf3814d0d5) ### Need another team? Navigate to the top left of the page and click the team selector. ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/sidebar-create-team-button.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=2409ece10f11fd1619332def472fb721) From here you can create an additional team. ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/create-team-modal.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=1da5c2b402d833e369a67de8737a1a7a) ## Switch teams Open the team selector in the top left again and pick the team you want to work on. ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/sidebar-change-team.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=096768575653ddfab827bcd2578cc989) ## The team menu Team-level features live in the **Team** section of the sidebar - Link in bio, Google Business, Bots, and Settings. ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/menu.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=155e8f2d775d17841e514731ed4174aa) ## Link in bio The **Link in bio** page is a single shareable page that collects all of your important links - perfect as the one URL in your social profiles. Set an avatar, name, and description, add your social icons, and build a list of links. Each link can be toggled on or off, reordered by dragging, and has its own settings and click analytics. Use the **Preview** link at the top to see the public page, and click **Save** when you're done. ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/link-in-bio.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=4c16e49693daf7ab4c177f943d437b2e) ## Google Business The **Google Business** page manages the Google Business profile connected to the current team. The banner at the top shows which location you're controlling. Use the tabs to edit each part of the profile - Profile, Opening hours, Special hours, More hours, Categories, Attributes, Services, Food menus, and Place actions. The Profile tab covers the core public information: business name, website, phone, and description. Click **Save profile** to publish your changes. ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/google-business.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=c864c75dbbe37bc7ee86416a07160b3d) ## Bots Bots let you customize how posts appear when published to Discord and Slack. To learn more, [read the bots guide](/knowledge/posts/dc-slack-bots). ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/bots.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=cab84d5915a384b63d79e369a3860bb6) > [!NOTE] > > Billing, API keys, and webhooks are managed at the organization level. > See [What is an organization?](/knowledge/organization/what-is-an-organization). ## Change your team name and picture Click **Settings**. From here you can: * Change the team picture * Change the team name * Delete the team ![](https://mintcdn.com/bundlesocial/ABxY9fZPByOJQQHO/images/knowledge/teams/settings.png?fit=max\&auto=format\&n=ABxY9fZPByOJQQHO\&q=85\&s=3476317505ba6c7ec1433c1fc7de5195) ## Summary You now know the basics of teams - how to create them, switch between them, and manage their settings. Attention is already out there; you just need to post and get it. with lukewarm regards c: - bundle.social staff # Welcome Source: https://info.bundle.social/welcome The Unified Social Media API. Write once, post everywhere: one integration for 15+ platforms instead of 15 auth flows and 15 sets of breaking changes. ## Welcome to bundle.social **The Unified Social Media API designed for unlimited scalability.** **Building social media integrations sucks.** You have to deal with 15 different APIs, 15 different authentication flows, random breaking changes, and documentation that was written by an insider robot in 2013. **We fixed it.** bundle.social provides a single, unified API for: * **Unlimited Social Accounts:** Connect 1 or 10,000 accounts. We don't punish you for growing. * **Instagram, TikTok, Snapchat, LinkedIn, YouTube, Facebook, Twitter/X, Pinterest, Reddit, Threads, Mastodon, Bluesky, Discord, Slack, and Google Business.** * **Scheduling & Publishing:** Post images, videos, reels, and stories. * **Analytics:** Get normalized data (views, likes, impressions) and demographic insights across platforms. * **Authentication:** We handle the OAuth nightmares and token refreshes for you. You build the product. We handle the platforms. *** ## What's Included Every bundle.social plan gives you access to a complete social media automation toolkit. No hidden fees, no per-account charges. > [card] Multi-Platform Publishing > > Schedule and publish posts to 15 social networks from a single API call. Support for images, videos, carousels, reels, stories, and platform-specific formats. > [card] Automated First Comments > > Post comments automatically when your content goes live. Supported on Instagram, TikTok, YouTube, Facebook, LinkedIn, Threads, Reddit, Mastodon, Discord, Slack, and Bluesky. > [card] Cross-Platform Analytics > > Unified analytics with normalized metrics. Views, impressions, likes, comments, shares, and demographic data-all in a consistent format regardless of platform. > [card] Media Management > > Upload and manage images, videos, and documents. We handle transcoding, validation, and storage. Support for large files up to 5GB. > [card] Post History Import > > Import existing posts and analytics from connected accounts. Populate your dashboard instantly without starting from scratch. > [card] Webhooks & Real-Time Events > > Get notified when posts are published, fail, or when users connect/disconnect accounts. Build reactive workflows with real-time data. *** ## Quickstart > [card] [API Reference](/api-reference) > > Dive straight into the endpoints. > [card] [Platform Quirks](/api-reference/platforms) > > See what each platform can (and can't) do. ## Explore > [card] [Connect Social Accounts](/api-reference/connect-social-accounts) > > How to get your users connected. > [card] [Upload Media](/api-reference/upload-content) > > Handling images and videos (even the big ones). > [card] [Import History](/api-reference/import-posts) > > Pull past posts and analytics. > [card] [Webhooks](/api-reference/webhooks) > > Listen for events like `post.published` or `post.failed`. ## Resources > [card] [Blog](https://bundle.social/blog) > > Industry insights and rants. > [card] [FAQ](/faq) > > Common questions. > [card] [Status](https://bundlesocial.betteruptime.com) > > System uptime.