> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Social listening and public-mention triage

> Route public brand mentions — X/Twitter posts, Reddit threads, Trustpilot or G2 reviews, public Instagram and Facebook comments — into the omnichannel inbox, so social care gets triaged and answered from the same queues as your private channels.

# Social listening and public-mention triage

Social care is the work of answering the public conversation about your brand, not just the private one. The inbox already ingests private 1:1 messages — Instagram and Messenger DMs, as well as every other direct channel. A public mention is different: an X/Twitter post, a Reddit thread, a Trustpilot or G2 review, or a comment under one of your Instagram/Facebook posts names the brand without opening a DM thread. Without a listening path, someone has to skim feeds and copy links into the queue. With one, a connector normalizes each mention and the same triage, assignment, and reply workflow your team already uses takes over.

Public mentions differ from DMs in one structural way. A DM is a private thread — conversation context arrives with it. A public mention is a standalone broadcast — it opens with no context, and the connector supplies the details the queue needs: the platform it came from, the author's handle, the permalink back to the original post, and optionally sentiment, reach, and the keyword that matched. The platform token you post (`twitter`, `reddit`, `trustpilot`, `g2`, `google_reviews`, `facebook_public`, `facebook_comment`, `instagram_comment`, `youtube`, `app_store`, `play_store`, `news`, `forum`, or the `other` catch-all) is what the queue filter and the row's chip display.

Public *post comments* — `instagram_comment` and `facebook_comment` — are the one platform family with extra structure. A comment belongs to a parent post, so every comment on the same post threads into one replyable conversation instead of one conversation per author, and `post_id` is required for those platforms.

## The queue in the dashboard

The triage queue lives under **Inbox → Social mentions** — a rail tab next to All conversations, Pending replies, and Archive. Each row shows the mention's sentiment chip (green for positive, red for negative, muted for neutral), the platform token, the author, an unread count, a working preview of the last message, and deep links — one into the conversation view, and one out to the original public post via the stored permalink.

Filter the queue by **platform** and **status** (open by default; snoozed, closed, or all). A first filter pass narrows `Sent to social mentions` to a slice you can clear, and the Load More button pulls through the next page of the mention firehose — the queue pages rather than capping out at one screen. Owners and admins see the rail tab today; it is hidden from agents, with the API itself still readable by every operator when the rail is widened.

## Ingest a mention

A listening connector — a poller or a webhook subscriber to a listening provider — normalizes the mention and posts it to `POST /inbox/social-mentions/ingest`. Only owners, admins, or super-admins can write into the shared queue; agents triage reads.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/inbox/social-mentions/ingest" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "twitter",
    "external_id": "1823412345678901234",
    "permalink": "https://x.com/acme_user/status/1823412345678901234",
    "author_handle": "acme_user",
    "author_display_name": "Acme User",
    "text": "@acme the new dashboard is gorgeous — shipped a week early too",
    "matched_keyword": "acme",
    "sentiment": "positive",
    "reach": 12500,
    "posted_at": "2026-08-29T14:21:10Z"
  }'
# -> 201 { "data": { "conversation_id": "conv_x9w", "message_id": "msg_p3q",
#          "deduped": false, "conversation_created": true } }
```

Three things to get right:

* **Idempotency.** `external_id` is the provider's stable mention id and the dedup key is `(channel, external_id)` — re-deliver a mention and the server returns `200` with `deduped: true` instead of a second conversation. Retry freely.
* **Validation.** A missing or malformed field returns `422 VALIDATION_ERROR` with per-field errors — fix the payload before retrying.
* **Comment platforms.** For `instagram_comment` and `facebook_comment`, `post_id` is required and the comment threads into the post's single conversation; `post_permalink`, `post_title`, and `parent_comment_id` are optional context the queue renders (a View post link, the caption, the parent comment for a nested reply).

Every write is audit-logged, and a genuinely new conversation also rings the org-admins' bell so a fresh public mention never sits silent.

## List and filter the queue

The dashboard page is backed by `GET /inbox/social-mentions`, readable by any operator. It defaults to the open queue; pass `?status=all` for history or `?platform=twitter` to scope to one network.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/inbox/social-mentions?status=open&platform=reddit&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# -> { "data": { "mentions": [ ... ], "next_cursor": "50" } }
```

Each item carries `conversation_id`, `status`, `author_name`, `unread_count`, `last_message`, `last_message_at`, and the full `mention` metadata blob described below. `next_cursor` is an offset token — feed it back as `?cursor=` to page the firehose; the final page returns `null`. Status accepts `open`, `closed`, `snoozed`, or `all`.

## The mention metadata blob

Every ingested mention is preserved on its conversation and message as a `social_mention` metadata blob — the queue's filter and the row's rendering both read from it:

| Field                                                          | Meaning                                                                |
| -------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `source`                                                       | Always `social_listening`                                              |
| `platform`                                                     | One of the accepted platform tokens                                    |
| `external_id`                                                  | The provider's stable mention id — the dedup key                       |
| `permalink`                                                    | http(s) link back to the original public post                          |
| `author_handle` / `author_display_name`                        | The public author's identity                                           |
| `matched_keyword`                                              | The listening keyword that caught the mention, if any                  |
| `sentiment`                                                    | `positive`, `neutral`, or `negative`, if the provider labels it        |
| `reach`                                                        | Follower/audience estimate, if provided                                |
| `posted_at`                                                    | ISO-8601 timestamp from the source network                             |
| `post_id`, `post_permalink`, `post_title`, `parent_comment_id` | Comment-thread context (`instagram_comment` / `facebook_comment` only) |

## Triage a mention, then reply

Public mentions land in the same conversation machinery as every other channel, so the triage loop is the one your team already runs:

1. Open the mention, read the linked original post through the permalink.
2. Assign the conversation — or let your routing rules assign it — and reply in the thread.
3. Close or snooze the queue row to keep the open view clean; reopen from **status → all** when a customer follows up.

For `instagram_comment` and `facebook_comment` platforms, a new comment can also trigger your published comment-received automation: a private DM goes out to the commenter inside Meta's follow-up window while the public thread stays in the queue. Replies and automation both flow as tenant-owned settings; nothing here routes messages outside your tenant's own channels.

## Authorization and isolation

| Route                                | Role required                                                  |
| ------------------------------------ | -------------------------------------------------------------- |
| `POST /inbox/social-mentions/ingest` | owner, admin, or super-admin (a connector acts on your behalf) |
| `GET /inbox/social-mentions`         | any operator reads the tenant's queue                          |

Tenant isolation is enforced at the schema layer: mentions live inside the same conversations and messages tables every other channel uses, under the `social_mention` channel — no new tables, no new DDL. Your connector writes only into your tenant's queue; operators page their own tenant's queue.

## Example connectors

All of these post to the same endpoint with the same idempotency contract — pick a platform, keep the provider's stable id as `external_id`, and retry without duplicating conversations.

**X/Twitter mention:**

```json theme={null}
{
  "platform": "twitter",
  "external_id": "1823412345678901234",
  "permalink": "https://x.com/acme_user/status/1823412345678901234",
  "author_handle": "acme_user",
  "text": "@acme the new dashboard is gorgeous",
  "sentiment": "positive",
  "posted_at": "2026-08-29T14:21:10Z"
}
```

**Reddit thread:**

```json theme={null}
{
  "platform": "reddit",
  "external_id": "t3_1n4kq2m",
  "permalink": "https://www.reddit.com/r/saas/comments/1n4kq2m/orbit_review_thread/",
  "author_handle": "u/ops_lead",
  "text": "PSA: Orbit's SLA timers finally answer the queue-stall question",
  "matched_keyword": "Orbit"
}
```

**Trustpilot review:**

```json theme={null}
{
  "platform": "trustpilot",
  "external_id": "65d0a1e2b9d1b02d1a2b3c4d",
  "permalink": "https://www.trustpilot.com/reviews/65d0a1e2b9d1b02d1a2b3c4d",
  "author_handle": "R. Alvarez",
  "author_display_name": "R. Alvarez",
  "text": "Support answered in minutes and the reviewer joined on video.",
  "sentiment": "positive"
}
```

**Instagram/Facebook comment (comment thread):**

```json theme={null}
{
  "platform": "instagram_comment",
  "external_id": "17853920015561234",
  "post_id": "17912345678901234",
  "permalink": "https://www.instagram.com/p/Cz9aBcD1234/",
  "author_handle": "design_curator",
  "text": "This launch looks unreal — how do I get in?"
}
```

## See also

* [Inbox SLA timers](/guides/inbox-sla-timers) — conversation-level first-response and resolution clocks over the same queue.
* [Per-digital-queue inbox SLA escalation policies](/inbox/sla-escalation-policies) — queue-level breach alerts for queues that include social.
* [Inbox API endpoints](/api-reference/endpoints/inbox) — conversation, message, and assignment operations the queue reuses.