Skip to main content

​
Social mentions not arriving

The Inbox → Social Mentions queue stays empty although your brand is being mentioned publicly, or your connector’s POSTs to POST /inbox/social-mentions/ingest return errors. Mentions enter Orbit only through the ingest endpoint, so every arrival problem is either a visible ingest rejection or a silent drop between your source and the queue. Work the ladder in order: ingest response first, then silent drops, then dedup.

​
1. Read the ingest response

Have your connector log the status code of every POST and, on errors, the request id from the error envelope. 201 means a new conversation, 200 means dedup, and anything else is one of the following.

​
403 INSUFFICIENT_PERMISSIONS

The envelope reads “Only owners or admins can ingest social mentions”: the API key your connector sends does not hold owner or admin in your organization. Ingest writes into the shared queue on behalf of an automated caller, so it is restricted to those roles, while reading the queue stays open to every operator. Fix it at the connector: mint or switch to an admin-scoped key under Settings → API keys and send it as the X-API-Key header, then replay one mention and expect 201 (or 200 if it was ingested earlier).

​
422 VALIDATION_ERROR

The body failed validation and the response carries the per-field errors. The usual culprits:
  • platform is not one of the accepted tokens, or does not match the source. An X post must be posted as twitter, a Trustpilot review as trustpilot, and so on; the queue filter and row chip render exactly the token you send. The full token table is in the Social listening model.
  • A required field is missing. platform, external_id, permalink, author_handle, and text are always required.
  • post_id is missing on a comment platform. instagram_comment and facebook_comment thread under their parent post and are rejected without post_id.
A 422 is a payload bug: retrying the unchanged body fails forever. Read the per-field errors, fix the connector’s mapping, then replay. The reference carries a worked body per platform to diff yours against.

​
5xx or network errors

Retry. Ingest is idempotent on (channel, external_id), so a retry can never create a duplicate conversation.

​
2. The silent-drop ladder

Ingest returns 200/201 yet the queue still looks empty. Walk these in order:
  1. The connector never POSTs. Your listening source’s own filter (keyword, handle, date range) may match nothing, so nothing is ever sent. Send one manual mention with the worked curl from the reference; if it shows up in the queue, the pipeline is healthy and your source’s capture filter is the culprit.
  2. The queue filter hides the source. The platform and status filters both start on All but stay where they were last set, so a queue narrowed to one platform or to open hides everything else. Reset both filters, and check status → all for rows that were closed or snoozed. Also mind the role: the rail tab is an owner/admin surface today, and agents work a mention once its conversation is assigned to them.
  3. Use the bell to separate “not ingested” from “ingested but hidden.” A genuinely new mention rings the org admins’ notification bell, and every ingest write is audit-logged. If an admin saw the bell at the time your connector claims a fresh mention, the row is ingested and a filter hides it (step 2). If the bell stayed quiet and your connector log shows only 200 with deduped: true, that external_id was already delivered earlier. If the connector logged no successful POST at all, the drop is upstream of Orbit (step 1).

​
3. Duplicate mentions and false dedup

Re-sending a mention with the same external_id returns 200 with deduped: true and no second conversation. That is the idempotency contract working as designed: it is what lets a poller retry or overlap windows without duplicating your queue. Not a bug. The interesting failure is the reverse: a genuinely new mention comes back deduped: true. Then the culprit is the connector’s external_id mint rule. The id must be the provider’s stable id and unique per mention; collisions appear when a connector truncates or re-derives the id per run, or reuses the parent post’s id for several comments (a comment carries its own id in external_id and the post’s id in post_id). Keep external_id byte-stable and unique per mention, and let the server own dedup.

​
4. Do not try

  • Re-POSTing the same external_id to force a new conversation. Dedup keys on (channel, external_id); the re-send returns deduped: true forever and the original conversation remains the only one. If the row was closed, reopen it from status → all.
  • Loosening the connector’s role to fix a schema error. A 422 is a payload problem; a broader role changes nothing about validation and only widens who can write into the shared queue. Fix the body, not the key.
  • Retrying a 422 unchanged. Only 5xx and network errors are retryable; a validation error never heals by itself.

​
5. Escalate with the right bundle

If the ladder above does not locate the drop, open a support ticket with:
  • the connector’s per-POST status codes and the request ids from the error envelopes,
  • one sample external_id and platform pair that should have arrived,
  • the full response body of one 200/201,
  • the affected time window in UTC.
With those four, the ingest path is traceable end to end without guesswork.

​
See also