Unified Social Inbox API: How One API Handles Comments, DMs, Reviews, and Mentions

A unified social inbox API is a single API that reads and responds to every inbound interaction on your social accounts (comments, direct messages, reviews, and mentions) across Instagram, Facebook, Threads, TikTok, Google Business Profile, LinkedIn, X/Twitter, and YouTube, and returns all of them in one normalized object shape. Instead of integrating eight separate platform APIs, each with its own OAuth flow, token lifetime, pagination model, rate limit, and payload schema, you integrate one. The interaction your code receives from an Instagram comment has the same shape as a Google review and the same shape as a Threads mention, so the same handler processes all of it. This post explains exactly what that means, how the pull and push delivery models work, where platform capabilities diverge, and how to decide whether to build the integration layer yourself or buy it.

What is a unified social inbox API?

A unified social inbox API is an abstraction over the native APIs of multiple social platforms that exposes their inbound engagement (comments, DMs, reviews, mentions) through a single, consistent interface. The word "unified" is doing two distinct jobs. First, it unifies surfaces: a comment, a DM, a review, and a mention are different objects on every native platform, but a unified inbox treats them as one family of thing, an interaction, with a shared envelope and type-specific content. Second, it unifies platforms: an Instagram comment and a YouTube comment arrive at native APIs that share almost nothing structurally, but a unified inbox normalizes them into one schema with a stable identifier, a platform field, an author, content, and metadata.

The practical test for whether something is genuinely unified is simple. Can one piece of handler code, with no platform-specific branching, take an interaction and route it, store it, or reply to it? If you still need a switch statement on platform to parse the author, or a separate code path to send a reply to TikTok versus Instagram, the API is aggregated but not unified. A true unified social inbox API also unifies the write path: replying to a comment, answering a DM, or responding to a review uses the same call regardless of which platform the interaction came from. The platform routing happens inside the API, decoded from the interaction identifier, not in your application.

This is distinct from a social publishing API, which is concerned with the outbound direction (scheduling and posting content). Some products do both. The inbox half is the harder half, because inbound engagement is real-time, high-cardinality, and shaped by per-platform webhook systems that each behave differently. If you only need to publish, you do not need an inbox API. If you need to listen and respond, the inbox is the thing you are actually buying.

Why use one inbox API instead of N platform APIs?

The argument for a unified social inbox API is the integration tax: every native platform API you add is not one integration but a permanent liability. Reason it out per platform and the cost is obvious. For each platform you own the OAuth and consent flow, encrypted token storage with refresh semantics that differ per platform, rate-limit accounting, cursor pagination, payload parsing, webhook signature verification, and a process that monitors version changes before they break you. Multiply all of that by eight and the recurring maintenance, not the first happy-path build, is the real cost. The integration tax is not about the first integration. It is about everything after it.

Consider what one platform actually costs you over its lifetime. Instagram, Facebook, and Threads run on the Meta Graph API, which versions roughly every few months and deprecates fields on a published schedule you have to track. Google Business Profile reviews arrive through Pub/Sub, a completely different delivery model from Meta's webhooks. TikTok's messaging surface, LinkedIn's engagement events, and the X/Twitter activity API each have their own auth dance, their own token refresh semantics, their own pagination, and their own approval review. Multiply the auth, the token storage, the rate-limit accounting, the pagination, the payload parsing, the webhook verification, and the change tracking by eight, and the steady-state maintenance load is the real cost, not the initial build.

Rate limits make the multiplication concrete. The Meta Graph API rate limit scales as roughly 200 calls per hour multiplied by your app's daily active users, an app-wide ceiling rather than a per-user budget (Meta, 2026). Because that ceiling is shared across every account your app touches, polling every connected account on a tight interval to catch new comments quickly spends one shared budget on inboxes that are mostly empty. A unified inbox API lets you push the rate-limit accounting down a layer and use real-time webhooks for inbound, which is covered in the social listening webhooks playbook and the social media API rate limits breakdown. The point of consolidation is not that one API is magically faster. It is that you write the rate-limit, retry, and parsing logic once instead of eight times, and you stop owning the breakage when a platform changes.

There is also a response-time argument with a hard business edge. In 2025, the Sprout Social Index found that 73 percent of consumers will buy from a competitor if a brand does not respond on social, and nearly three-quarters expect a response within 24 hours (Sprout Social Index 2025). You cannot hit a consistent reply SLA across eight platforms if each platform is its own half-finished integration project. A unified inbox is the substrate that makes a consistent SLA achievable, because every interaction lands in the same queue regardless of where it came from.

What does the inbox cover: comments, DMs, reviews, mentions?

A unified social inbox covers four distinct interaction types, and the distinction matters because they have different lifecycles, different reply mechanics, and different platform support. The four surfaces are comments (public replies on a post you own), direct messages (private one-to-one or thread conversations), reviews (ratings plus text on a business profile), and mentions (a post or comment elsewhere that references your handle). Each one is its own job to be done, and a real unified inbox API gives all four a shared envelope so a single consumer can triage across them.

Comments are public and post-scoped. They are the highest-volume surface for most accounts, they nest (a reply to a comment is itself a comment), and they support moderation actions (hide, delete) on top of replying. A unified inbox handles comment threading and the moderate action with the same call shape across Instagram, Facebook, Threads, LinkedIn, and YouTube. The moderation-specific behavior, including which platforms allow hiding versus only deleting, is covered in the comment moderation API guide.

Direct messages are private and conversation-scoped, and they carry the strictest platform rules. Meta enforces a 24-hour standard messaging window: you can reply to a user freely only within 24 hours of their last message. After that, the API rejects most sends. A unified inbox does not remove that window (no abstraction can, it is a platform policy) but it surfaces it consistently so your code does not have to relearn it per platform. The DM mechanics, including the messaging window and thread lookup, are detailed in the direct messaging API guide.

Reviews and mentions are the brand-monitoring pair, and they behave differently from comments and DMs. Reviews are effectively read-and-respond on Google Business Profile and are best consumed real-time rather than stored, because review content and ratings change. Mentions are discovery, not inbox ownership: a mention is something that happened on someone else's surface, so you can read it and sometimes reply, but you do not control the thread. The review-specific and mention-specific patterns are covered in the online reviews API and social media mentions API guides respectively. The unifying idea across all four is the Interaction object: a stable id whose prefix encodes the type (sapi_cmt_, sapi_dm_, sapi_rev_, sapi_mnt_), a platform field, an author, content, and metadata, so one consumer triages all four without per-type parsers.

Pull vs push: polling and webhooks, and when to use each?

A unified social inbox API delivers interactions two ways, and a production system almost always uses both. Pull is REST: your code asks the API for interactions on a schedule or on demand. Push is webhooks: the API POSTs a signed payload to your endpoint the moment an interaction arrives. The decision is not pull versus push as a religious choice; it is which job each one is right for. Pull owns backfill, historical sync, and periodic metric refresh. Push owns real-time inbound, where detection latency is measured in seconds rather than the one-to-fifteen-minute floor that polling intervals impose.

Use pull for the cases where you are reconstructing state rather than reacting to it. The first time you connect an account, you want history, so you page through existing comments and DMs with keyset cursors. On a cron, you refresh post-level metrics (reach, impressions, saves) because those change over time and no webhook fires when a number ticks up. Pull is also the correct fallback when a webhook endpoint was down: you reconcile by re-reading the window you might have missed. The cost of pull is rate-limit budget and a latency floor set by your interval.

Use push for everything inbound that a human or an agent needs to react to quickly. A new comment, a new DM, a new review, a new mention: these are the events where seconds matter and where polling wastes quota checking inboxes that are empty 95 percent of the time. The cost of push is operational: you must run an always-on HTTPS endpoint, verify the signature on every request with a constant-time comparison, respond with a 2xx fast, and make your handler idempotent because retries are real and the same interaction id can arrive more than once. The verification mechanics are covered in depth in the webhook signature verification guide. The mature pattern is push for inbound, pull for backfill and metrics, and pull again as the reconciliation safety net.

What does the capability matrix look like across platforms?

A unified social inbox API hides the integration work but it cannot invent capabilities a platform does not expose, so the honest version of unification includes a capability matrix. In 2026, the practical reality is that comment read and reply is the most broadly supported surface across platforms, while reviews are effectively single-platform (Google Business Profile) and mentions are unevenly supported. The value of a unified API here is that unsupported capabilities return a single, predictable error code rather than eight different failure modes you discover at runtime.

Read the matrix as a design constraint, not a marketing scorecard. Comments are the surface you can rely on almost everywhere, which is why comment moderation is the most common first feature teams ship on a unified inbox. DMs cluster on the Meta platforms and TikTok, and they carry the 24-hour window everywhere they exist, so a DM feature is really a Meta-plus-TikTok feature with a hard policy constraint baked in. Mentions are uneven because some platforms treat mentions as a first-class webhook event and others require search-style discovery. Reviews are a single-platform surface today: if reviews are central to your product, you are building a Google Business Profile integration that happens to share an envelope with the others.

The architectural payoff of a unified API is how it represents the gaps. When a capability is not available on a platform, a well-designed unified inbox returns one stable not-supported error rather than letting eight native APIs fail in eight idiosyncratic ways (a 400 here, a silent empty array there, a permissions error somewhere else). That single failure contract is itself a feature, because it means your fallback logic is written once. The full, current matrix lives in the API reference rather than in a blog post that would drift, so check it at docs.social-api.ai for the exact per-platform support before you scope a feature.

Build vs buy: what does maintaining platform integrations actually cost?

The build-versus-buy decision for a unified social inbox is almost never decided on the first integration; it is decided on the maintenance curve. Consolidating onto one API removes most of the per-platform integration effort a team would otherwise carry, and the reason that effort is large is that it is not front-loaded. It is a recurring tax that arrives every time a platform versions, deprecates a field, changes a scope, or alters a rate limit, on every one of the eight platforms, independently.

Be precise about what "build" actually contains, because the happy path is the small part. Building it yourself means owning, per platform: the OAuth flow and consent screens, encrypted token storage with refresh semantics that differ per platform, rate-limit accounting that respects per-user and per-app budgets, cursor-based pagination that each API models differently, payload parsing for schemas that share no structure, webhook signature verification with the platform's specific scheme, an idempotent retry-tolerant ingestion path, and a change-monitoring process so you find out about a Graph API version bump before your users do. Then multiply by eight, and add the on-call burden when a platform changes something on a Friday.

Buy is the right default when social inbox is a feature of your product rather than your product itself. If you are building an AI support agent, a social CRM, an agency dashboard, or a brand-monitoring tool, the inbox integration is undifferentiated heavy lifting: your users do not pay you for your OAuth token-refresh code, they pay you for what you do with the interactions. Build is defensible only when the integration itself is your moat, when you need behavior no abstraction exposes, or when contractual data-handling constraints rule out a third party. For most teams the calculation reduces to a question of ownership: do you want to own the breakage when Meta changes the Graph API, or do you want that to be someone else's pager? Pricing for the buy side, including the free tier, is on the unified inbox API pricing page so you can put a number against the build estimate.

How does SocialAPI.ai model a unified inbox?

SocialAPI.ai models the unified inbox around one principle: the Interaction object is identical no matter which platform or surface produced it, so one handler processes everything. As of May 2026 the public API covers comments, DMs, reviews, and mentions across Instagram, Facebook, Threads, TikTok, Google Business Profile, LinkedIn, X/Twitter, and YouTube, and every one of them returns the same shape. The interaction id carries a type prefix (sapi_cmt_, sapi_dm_, sapi_rev_, sapi_mnt_) and an encoded platform, so reply dispatch happens without a database lookup and without per-platform branching in your code.

// One handler. Every platform. Every surface.
// The interaction shape is identical whether it came from an
// Instagram comment, a Google review, or a Threads mention.

app.post("/webhooks/socapi", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifySignature(process.env.SOCAPI_WEBHOOK_SECRET, req.body, req.headers["x-socialapi-signature"])) {
    return res.status(401).send("Invalid signature");
  }
  res.sendStatus(200); // ack first, work after

  const { event, data } = JSON.parse(req.body);

  // No switch on platform. The envelope is the same for all eight.
  // The id prefix tells you the type without a lookup.
  const kind = data.id.slice(5, 8); // cmt | dm_ | rev | mnt

  enqueue({
    interactionId: data.id,        // stable, dedupe on this
    type: data.type,               // comment | dm | review | mention
    platform: data.platform,       // instagram | google | threads | ...
    author: data.author,
    text: data.content.text,
    kind,
  });
});

// Replying is also one call, regardless of platform.
// The platform is decoded from the interaction id server-side.
async function reply(accountId, interactionId, text) {
  return fetch(`https://api.social-api.ai/v1/accounts/${accountId}/interactions/${interactionId}/reply`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SOCAPI_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text }),
  });
}

The read path mirrors the write path. The same Interaction shape is returned by the REST inbox endpoints (comments scoped to a post, the DM thread lookup, reviews, mentions) and by the webhook payloads, so one parser serves both pull and push. Connecting an account is a single OAuth flow per account through SocialAPI.ai's connected-accounts model, after which the platform tokens, refresh, and rate-limit accounting are handled below your code. Unsupported capabilities return one stable not-supported error rather than eight native failure modes, which keeps your fallback logic singular. The endpoint-level reference (exact paths, parameters, payload fields) lives at docs.social-api.ai so it stays current rather than drifting in prose here.

Where to go next in this cluster

This post is the conceptual map. Each inbox surface and each cross-cutting concern has its own deeper guide, and they assume the model described here: one Interaction object, pull and push delivery, a capability matrix that varies by platform. If you are scoping a specific feature, start from the surface guide that matches it (comments, reviews, mentions, or DMs) and then read the two operational guides (webhook signature verification and rate limits) before you write the ingestion path. The links below go down to each spoke in the cluster.

Frequently asked questions

What is a unified social inbox API?

A unified social inbox API is a single API that reads and responds to comments, direct messages, reviews, and mentions across multiple social platforms (Instagram, Facebook, Threads, TikTok, Google Business Profile, LinkedIn, X/Twitter, YouTube) and returns all of them in one normalized Interaction object. The same handler code processes an Instagram comment, a Google review, and a Threads mention because the envelope is identical. It removes the need to integrate, authenticate, and maintain each platform API separately.

How is a unified social inbox API different from a publishing API?

A publishing API handles the outbound direction: scheduling and posting content to platforms. A unified social inbox API handles the inbound direction: reading and responding to comments, DMs, reviews, and mentions. The inbox half is harder because inbound engagement is real-time, high-cardinality, and shaped by per-platform webhook systems that each behave differently. Some products do both, but if you only need to publish you do not need an inbox API at all.

Should I use polling or webhooks with a unified social inbox API?

Use both. Pull (REST polling) is right for backfill on first connect, historical sync, periodic metric refresh, and reconciliation after an endpoint outage. Push (webhooks) is right for real-time inbound where seconds matter: new comments, DMs, reviews, and mentions. Polling has a 1-15 minute latency floor and burns rate-limit budget on empty inboxes; webhooks deliver in seconds but require an always-on signed endpoint. The mature pattern is push for inbound and pull for backfill and metrics.

Does a unified social inbox API support every capability on every platform?

No, and any API claiming otherwise is overselling. A unified API hides integration work but cannot invent capabilities a platform does not expose. As of 2026, comment read and reply is the most broadly supported surface, DMs cluster on the Meta platforms and TikTok with a 24-hour messaging window, mentions are uneven, and reviews are effectively Google Business Profile only. The value of unification here is that unsupported capabilities return one stable error rather than eight different runtime failures.

When should I build my own social integrations instead of buying a unified API?

Build only when the integration itself is your moat, when you need behavior no abstraction exposes, or when data-handling constraints rule out a third party. For most teams, social inbox is a feature, not the product, so the OAuth flows, token refresh, rate-limit accounting, and per-platform change tracking are undifferentiated heavy lifting. Most of what a unified API removes is recurring maintenance: eight APIs that each change independently, not the first build.

What is the Interaction object in a unified social inbox API?

The Interaction object is the single normalized shape every interaction is returned in, regardless of platform or surface. In SocialAPI.ai it has a stable id whose prefix encodes the type (sapi_cmt_ for comments, sapi_dm_ for DMs, sapi_rev_ for reviews, sapi_mnt_ for mentions), plus a platform field, an author, content, and metadata. Reply dispatch decodes the platform from the id server-side, so one handler reads and one call replies without per-platform branching in your code.

Can one handler really process every platform without branching?

Yes, that is the defining test of a genuinely unified inbox. Because the Interaction envelope is identical across platforms and surfaces, one webhook handler parses everything and one reply call answers everything; the platform is decoded from the interaction id by the API, not by your code. If you still need a switch on platform to parse an author or send a reply, the API is aggregated, not unified. Per-platform capability gaps surface as one stable not-supported error, so even your fallback logic stays single.

A unified social inbox API is not a latency trick or a convenience wrapper. It is a decision about who owns the permanent maintenance of eight diverging platform APIs. If social inbox is a feature of your product, the model in this post (one Interaction object, pull for backfill and push for real-time, a capability matrix that varies by platform) is the substrate every spoke in this cluster builds on. Start from the surface guide that matches your feature, read the operational guides before you write the ingestion path, and check docs.social-api.ai for the current endpoint reference and per-platform matrix.

Third-party statistics in this guide are linked inline so every number can be checked at its source. Primary sources: Meta Graph API: rate limiting overview (app-level ceiling of 200 calls/hour times daily active users) · Sprout Social Index 2025: social media customer service expectations