Inbox — Mentions

Retrieve @mention events delivered to connected social accounts via platform webhooks. Mentions are created automatically when a connected Facebook Page or Instagram account is @mentioned — no polling required.

Access status: pending approval. These endpoints are currently available to authenticated VoxBurst app sessions only. Public API key access is disabled pending VoxBurst API program approval. This documentation is provided for transparency.

Mention endpoints are scoped to the authenticated user. Results include mentions across all workspaces the authenticated user belongs to.

Base URL


https://api.voxburst.io/v1/inbox/mentions

List Mentions

GET /v1/inbox/mentions

Returns a paginated list of @mention events across all connected accounts the authenticated user has access to, ordered by most recent first.

Auth: Bearer token (user session)

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (min 1)
`limit`	integer	`20`	Results per page (1–100)
`platform`	string	—	Filter by platform (e.g. `FACEBOOK`, `INSTAGRAM`)
`accountId`	string	—	Filter by a specific connected account ID
`unreadOnly`	boolean	—	When `true`, returns only unread mentions
`hiddenOnly`	boolean	`false`	When `true`, returns only hidden mentions. When omitted or `false`, hidden mentions are excluded. See Hidden mentions


curl "https://api.voxburst.io/v1/inbox/mentions?platform=FACEBOOK&unreadOnly=true" \
  -H "Authorization: Bearer eyJexample..."

Response (200)


{
  "data": [
    {
      "id": "mnt_example123",
      "accountId": "acc_example456",
      "postId": "pst_example789",
      "platform": "FACEBOOK",
      "platformMentionId": "mention_123456789_987654321",
      "platformMediaId": "123456789_987654321",
      "authorId": "987654321",
      "authorUsername": "janedoe",
      "content": "Love what @YourPage is doing — great post!",
      "permalinkUrl": "https://www.facebook.com/123456789_987654321?comment_id=987654321",
      "read": false,
      "platformCreatedAt": "2026-07-01T14:23:00.000Z",
      "createdAt": "2026-07-01T14:23:05.000Z",
      "updatedAt": "2026-07-01T14:23:05.000Z",
      "hidden": false,
      "hiddenAt": null,
      "account": {
        "id": "acc_example456",
        "username": "yourpage",
        "displayName": "Your Page",
        "avatarUrl": "https://cdn.example.com/avatars/yourpage.jpg",
        "platform": "FACEBOOK"
      },
      "post": {
        "id": "pst_example789",
        "content": "Exciting updates coming next week — stay tuned!"
      }
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

Response Fields

Field	Type	Description
`id`	string	VoxBurst mention ID
`accountId`	string	ID of the connected account that was mentioned
`postId`	string \| null	ID of the VoxBurst post where the mention occurred, if resolvable
`platform`	string	Platform the mention came from
`platformMentionId`	string	Platform-specific identifier for this mention event
`platformMediaId`	string	Platform ID of the post or media where the mention occurred
`authorId`	string	Platform-specific identifier for the author who mentioned the account. For Facebook `item: "comment"` mentions, this may be a non-resolvable placeholder — see Facebook Mention Author Identity below
`authorUsername`	string \| null	Username of the author, when provided by the platform. May be `null` for Facebook `item: "comment"` mentions and is always `null` for Instagram mentions
`content`	string \| null	Text of the mention or comment. May be `null` for Instagram media mentions (platform does not include text in the webhook payload)
`permalinkUrl`	string \| null	Direct public web permalink to the original content on the source platform. Populated for Facebook mentions; `null` for Instagram and all other platforms
`read`	boolean	Whether the mention has been marked as read
`hidden`	boolean	Whether the mention has been soft-hidden from the default inbox view
`hiddenAt`	string (ISO 8601) \| null	When the mention was hidden. `null` when not hidden
`platformCreatedAt`	string (ISO 8601)	Timestamp from the platform webhook
`account`	object	Summary of the connected account that was mentioned — `id`, `username`, `displayName`, `avatarUrl`, `platform`. `displayName` and `avatarUrl` may be `null` where the platform did not supply them
`post`	object \| null	Summary of the linked VoxBurst post, if resolved

Get Mention Stats

GET /v1/inbox/mentions/stats

Returns the count of unread mentions across all workspaces the authenticated user belongs to.

Auth: Bearer token (user session)


curl "https://api.voxburst.io/v1/inbox/mentions/stats" \
  -H "Authorization: Bearer eyJexample..."

Response (200)


{
  "unreadCount": 7
}

Get a Mention

GET /v1/inbox/mentions/:id

Returns a single mention by its VoxBurst ID.

Auth: Bearer token (user session)


curl "https://api.voxburst.io/v1/inbox/mentions/mnt_example123" \
  -H "Authorization: Bearer eyJexample..."

Response (200)

Same shape as a single item in the List Mentions response.

Error Responses

Status	Code	Description
404	`NOT_FOUND`	Mention does not exist or does not belong to the authenticated user’s workspaces

Mark a Mention as Read

PATCH /v1/inbox/mentions/:id/read

Marks a mention as read. Idempotent — calling this on an already-read mention returns the unchanged record.

Auth: Bearer token (user session)


curl -X PATCH "https://api.voxburst.io/v1/inbox/mentions/mnt_example123/read" \
  -H "Authorization: Bearer eyJexample..."

Response (200)

Returns the updated mention object with read: true.

Error Responses

Status	Code	Description
404	`NOT_FOUND`	Mention does not exist or does not belong to the authenticated user’s workspaces

Hide a Mention

POST /v1/inbox/mentions/:id/hide

Soft-hides a mention. The mention is retained in full and is not deleted from VoxBurst or from the source platform — it is only excluded from the default inbox list.

Auth: Bearer token (user session)


curl -X POST "https://api.voxburst.io/v1/inbox/mentions/mnt_example123/hide" \
  -H "Authorization: Bearer eyJexample..."

Unhide a Mention

DELETE /v1/inbox/mentions/:id/hide

Reverses a hide, returning the mention to the default list.


curl -X DELETE "https://api.voxburst.io/v1/inbox/mentions/mnt_example123/hide" \
  -H "Authorization: Bearer eyJexample..."

Response (200) — both endpoints

The hide and unhide endpoints return the stored mention record, not the enriched object returned by the list and get endpoints. In particular permalinkUrl, account, and post are absent from this response. Re-fetch via GET /v1/inbox/mentions/:id if you need the enriched form.


{
  "data": {
    "id": "mnt_example123",
    "accountId": "acc_example456",
    "postId": "pst_example789",
    "platform": "FACEBOOK",
    "read": false,
    "hidden": true,
    "hiddenAt": "2026-08-19T09:15:00.000Z"
  }
}

Field	Type	Description
`hidden`	boolean	`true` after `POST`, `false` after `DELETE`
`hiddenAt`	string (ISO 8601) \| null	When the mention was hidden. `null` after unhiding

Error Responses

Status	Code	Description
404	`NOT_FOUND`	Mention does not exist or does not belong to the authenticated user’s workspaces

Hidden mentions

Hiding is a VoxBurst-side visibility control. It does not hide or delete the mention on the social platform.

The filter is binary — there is no value of hiddenOnly that returns hidden and non-hidden mentions together:

`hiddenOnly`	Returns
omitted	Non-hidden mentions only
`false`	Non-hidden mentions only
`true`	Hidden mentions only

Hidden mentions are excluded from list responses by default, and meta.total reflects only the visible set. No tombstone or placeholder is returned for a hidden mention. An integration performing a full sync must issue two requests — one with hiddenOnly=true and one without — and merge the results. A single unqualified request will silently under-report.

GET /v1/inbox/mentions/stats counts all unread mentions, including hidden ones. A hidden unread mention still contributes to unreadCount, so the badge count can exceed the number of rows returned by the default list.

Facebook Mention Author Identity

authorId and authorUsername may be absent for a meaningful fraction of Facebook mentions. This is a documented Meta platform constraint, not a VoxBurst limitation.

Meta’s Page webhook delivers two distinct mention types:

Someone comments on a public post tagging your Page — the most common real-world case. Meta’s mention webhook field does not include sender identity for this event type when delivered to third-party consumer apps via the pages_read_user_content permission. VoxBurst makes a best-effort enrichment call to the Graph API, but when Meta does not return sender data, authorUsername will be null and authorId will hold a non-resolvable placeholder value.
Someone creates a new post (including a Facebook Story) that tags your Page — Meta sometimes includes sender identity inline for this event type. When it does, VoxBurst uses those real values for authorId and authorUsername.

Recommended handling: treat authorUsername: null as a normal, expected state for Facebook mentions. Fall back to displaying “Unknown” or use permalinkUrl to provide a click-through to the original content rather than relying on author identity for navigation.

Platform Coverage

Platform	Mention delivery	Author username	Content text	Permalink URL
Facebook	Via Page `mention` webhook field	Included when Meta provides it (see note above)	Included	Included
Instagram	Via `mentions` webhook field	Not included	Not included	`null`