Skip to main content

​
The social-listening ingestion-to-queue model

Social listening brings the public conversation about your brand — X/Twitter posts, Reddit threads, Trustpilot or G2 reviews, public comments under your Instagram and Facebook posts — into the same Inbox workspace your team already uses for private channels. A mention arrives as an ordinary conversation, and the work your team already does for every other channel — assignment, triage, reply, SLA clocks, audit — applies to it unchanged. This page defines the ingestion-to-queue path the code ships today: the ingest endpoint a connector calls with a conversation-ready mention payload, the dedup and threading rules the payload carries, the queue filters anyone can read, and the role gates each surface enforces. It does not define sentiment scoring or analytics — the sentiment value ships from your provider and the queue merely displays it. What your provider labels as a sentiment score, a keyword match, or a follower-reach estimate is your provider’s call and yours to send; the queue renders it.

​
What social listening ingests, and what enters the queue

A social mention is a public post that names your brand. When your connector normalizes one of these and posts it to POST /inbox/social-mentions/ingest, the ingest writer makes it a conversation on the social_mention channel:
  • Standalone posts (X/Twitter, Reddit, reviews, news, forums, YouTube, app stores) group into one conversation per public author — a second post from the same author continues their thread.
  • Post comments (instagram_comment and facebook_comment) require a post_id and thread per parent post into a single replyable conversation, because the post is the context.
  • Duplicates collapse on the (channel, external_id) pair. Re-delivering a mention the connector already sent is a safe no-op returning deduped: true, and a genuinely new mention rings the org-admins’ notification bell.
The queue filter and the row chip read from the platform token you post (twitter, reddit, trustpilot, g2, google_reviews, facebook_public, facebook_comment, instagram_comment, youtube, app_store, play_store, news, forum, other). The rest of the mention payload the queue renders — sentiment (green/red/muted), matched_keyword, and reach — passes through untouched from the provider. post_id is required for the two comment platforms, with post_permalink, post_title, and parent_comment_id as optional context.

​
How a supervisor configures a listening connector

Posting into the queue requires owner, admin, or super-admin scope — a connector acts on your behalf, writes on behalf of an automated account. Any operator can read the queue list endpoint, and reading is not gated.
  • Point your listening connector at the ingest endpoint, one POST per mention. Set up the connection once per source and let the source retry idempotently on the provider’s stable mention id.
  • Route by sentiment and keyword, not by channel. Routing rules cannot match on the mention channel itself, but they can match on the sentiment label and the matched_keyword text the connector supplies — this is how a supervisor pushes negative mentions to a senior queue and sends a campaign hashtag to the owning team.
  • Attach SLA policy at the channel level. A per_channel-scoped SLA policy applied to social_mention puts first-response and resolution clocks on every mention conversation — see Inbox SLA timers.
  • Comment automations live with the commenter’s platform. For instagram_comment and facebook_comment, a new comment can trigger your published comment-received automation — a private DM goes out inside Meta’s follow-up window while the public thread stays in the queue. The automation is a tenant-owned flow on your own account; nothing routes outside your tenant.

​
How agents read mention context in the thread

Open a mention row and the conversation the row links to displays the original public post with its permalink, the author’s handle, and the metadata the connector supplied. The queue row links both into the Inbox conversation view and out to the original public post in a new tab so triage has both a deep link and the context at one click. Rows also carry the provider’s machines — the sentiment chip, keyword that matched, reach estimate — on the row itself. The chips read directly from the mention metadata blob the ingest writer preserved on the conversation. Because a mention lands in the same conversation machinery every channel uses, thread threading applies: a public author’s second post shows up in their existing thread, not as a new conversation.

​
Listening is not ordinary inbound

Do not treat public mentions as private inbound routed through the same writers, quotas, and routing — they are structurally different:
  • Private inbound opens a thread with context; a mention opens with none. A DM arrives with a conversation attached; a mention supplies a permalink to the original public post instead.
  • Public mentions collapse and unwind differently from private. Their dedup is keyed to the provider’s stable external_id on the social_mention channel; do not route a mention through the private channel ingest writers and expect the queue to pick it up — it will not join the Social mentions rail.
  • Post comments thread per parent post. Instagram and Facebook comments group by post_id, not by author, which is a different threading contract from every private channel.
  • Some mentions are not support work. Praise back-linked to marketing is a social-media team’s call; tracked issues that need a status lifecycle and assignment history graduate to a ticket — the Inbox Tickets workflow is the right surface, not the queue.

​
Tenant-owned controls and isolation

Every control here — the connector you attach, the routing condition you configure, the SLA policy you attach, the comment automations you publish — is an operator action on your own organization. Ingest writes audit entries with actor context, and mention conversations live in the same tenant_<id> schema as your other channels — no second data plane, no cross-org read. A mention nobody routes stays unassigned at the top of the queue until a human works it.

​
See also