Inbox — Comments

Retrieve and manage comments left on content published through VoxBurst. Comments are synced from each platform’s API and stored against the connected account and, where resolvable, the originating VoxBurst post.

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.

Base URL


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

List Comments

GET /v1/inbox/comments

Returns comments across all connected accounts in the active workspace, most recent first. Pagination is cursor-based.

Auth: Bearer token (user session)

Query Parameters

Parameter	Type	Default	Description
`platform`	string	—	Filter by platform (e.g. `instagram`, `facebook`). Case-insensitive
`accountId`	string	—	Filter by a specific connected account ID
`since`	string (ISO 8601)	—	Only return comments created on the platform at or after this timestamp
`replied`	boolean	—	`true` returns only replied comments, `false` only unreplied. Omit for both
`hiddenOnly`	boolean	`false`	When `true`, returns only hidden comments. When omitted or `false`, hidden comments are excluded. See Hidden comments
`limit`	integer	`20`	Results per page (1–100)
`cursor`	string	—	Pass the `nextCursor` from the previous response to fetch the next page


curl "https://api.voxburst.io/v1/inbox/comments?platform=instagram&replied=false" \
  -H "Authorization: Bearer eyJexample..."

Response (200)


{
  "data": [
    {
      "id": "cmt_example123",
      "accountId": "acc_example456",
      "postId": "pst_example789",
      "platformPostId": "17851234567890123",
      "platformCommentId": "17891234567890456",
      "platform": "instagram",
      "author": {
        "id": "9876543210",
        "username": "janedoe",
        "avatarUrl": "https://cdn.example.com/avatars/janedoe.jpg"
      },
      "content": "This is exactly what I needed, thanks!",
      "createdAt": "2026-08-01T14:23:05.000Z",
      "platformCreatedAt": "2026-08-01T14:23:00.000Z",
      "isReply": false,
      "parentCommentId": null,
      "replied": false,
      "permalinkUrl": "https://www.instagram.com/p/ABC123/c/17891234567890456/",
      "account": {
        "id": "acc_example456",
        "username": "yourbrand",
        "displayName": "Your Brand",
        "avatarUrl": "https://cdn.example.com/avatars/yourbrand.jpg",
        "platform": "instagram"
      },
      "post": {
        "id": "pst_example789",
        "content": "Exciting updates coming next week — stay tuned!",
        "status": "PUBLISHED",
        "scheduledFor": null,
        "publishedAt": "2026-08-01T12:00:00.000Z",
        "mediaUrl": "https://cdn.example.com/media/launch.jpg",
        "mediaContentType": "image/jpeg"
      }
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cmt_example123"
  }
}

Response Fields

Field	Type	Description
`id`	string	VoxBurst comment ID
`accountId`	string	ID of the connected account the comment was left on
`postId`	string \| null	ID of the originating VoxBurst post, when resolvable
`platformPostId`	string	Platform ID of the post the comment belongs to
`platformCommentId`	string	Platform ID of the comment itself
`platform`	string	Lowercased platform slug
`author`	object	Comment author — `id` (string), `username` (string), `avatarUrl` (string, optional)
`content`	string	Text of the comment
`createdAt`	string (ISO 8601)	When VoxBurst recorded the comment
`platformCreatedAt`	string (ISO 8601)	When the comment was created on the platform
`isReply`	boolean	Whether this comment is a reply to another comment
`parentCommentId`	string \| null	VoxBurst ID of the parent comment when `isReply` is `true`
`replied`	boolean	Whether the comment has been replied to or marked as replied
`repliedAt`	string (ISO 8601)	Present only when `replied` is `true`
`ourReplyId`	string	Platform ID of the reply VoxBurst posted. Present only when a reply was sent through the API
`permalinkUrl`	string \| null	Direct public web permalink to the comment on the source platform. `null` where the platform does not expose one
`account`	object	Summary of the connected account — `id`, `username`, `displayName`, `avatarUrl`, `platform`
`post`	object	Summary of the originating VoxBurst post. Omitted when `postId` is `null`. `post.content` is truncated to the first 100 characters

pagination.nextCursor is the id of the last item in data. It is only present when hasMore is true. Pass it back as cursor to page forward.

Account and Post Scoped Lists

GET /v1/accounts/:accountId/comments GET /v1/posts/:postId/comments

Return comments for a single connected account or a single VoxBurst post. Both accept the same query parameters as the workspace-wide list and return the same response shape.

hiddenOnly is accepted but not applied on these two endpoints. Passing hiddenOnly=true to the account-scoped or post-scoped list is silently ignored and the response still excludes hidden comments. To retrieve hidden comments, use GET /v1/inbox/comments?hiddenOnly=true and filter client-side on accountId or postId.


curl "https://api.voxburst.io/v1/accounts/acc_example456/comments" \
  -H "Authorization: Bearer eyJexample..."

Error Responses

Status	Code	Description
404	`NOT_FOUND`	The account or post does not exist in the active workspace

Get Comment Stats

GET /v1/inbox/comments/stats

Returns aggregate comment counts for the active workspace.

Auth: Bearer token (user session)


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

Response (200)


{
  "total": 128,
  "unreplied": 17,
  "repliedToday": 5,
  "byPlatform": {
    "INSTAGRAM": 92,
    "FACEBOOK": 36
  }
}

Stats counts include hidden comments. They are not affected by the default hidden-exclusion applied to the list endpoints.

Get a Comment

GET /v1/inbox/comments/:commentId

Returns a single comment by its VoxBurst ID, in the same shape as a list item.

Auth: Bearer token (user session)

Error Responses

Status	Code	Description
404	`NOT_FOUND`	Comment does not exist or does not belong to the active workspace

Reply to a Comment

POST /v1/inbox/comments/:commentId/reply

Posts a reply to the comment on the source platform and marks the comment as replied.

Auth: Bearer token (user session)

Request Body

Field	Type	Required	Description
`content`	string	Yes	Reply text, 1–10,000 characters


curl -X POST "https://api.voxburst.io/v1/inbox/comments/cmt_example123/reply" \
  -H "Authorization: Bearer eyJexample..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "Thanks for the kind words!" }'

Response (200)


{
  "success": true,
  "replyId": "17891234567890999",
  "replyUrl": "https://www.instagram.com/p/ABC123/c/17891234567890999/"
}

replyId and replyUrl are platform-supplied and may be absent on platforms that do not return them.

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Reply text failed validation, or the platform rejected the reply
404	`NOT_FOUND`	Comment does not exist or does not belong to the active workspace

Mark a Comment as Replied

POST /v1/inbox/comments/:commentId/mark-replied DELETE /v1/inbox/comments/:commentId/mark-replied

Mark a comment as replied without sending a reply, or undo that marking. Use this when the reply was handled outside VoxBurst.

Both return the updated comment. Neither call contacts the source platform.


curl -X POST "https://api.voxburst.io/v1/inbox/comments/cmt_example123/mark-replied" \
  -H "Authorization: Bearer eyJexample..."

Error Responses

Status	Code	Description
404	`NOT_FOUND`	Comment does not exist or does not belong to the active workspace

Hide a Comment

POST /v1/inbox/comments/:commentId/hide

Soft-hides a comment. The comment 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/comments/cmt_example123/hide" \
  -H "Authorization: Bearer eyJexample..."

Unhide a Comment

DELETE /v1/inbox/comments/:commentId/hide

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


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

Response (200) — both endpoints

The hide and unhide endpoints return the stored comment record, not the formatted comment object returned by the list and get endpoints. The shape differs: author fields are flat (authorId, authorUsername, authorAvatarUrl) rather than nested under author, platform is uppercase, timestamps are raw, and permalinkUrl, account, and post are absent. Do not feed this response into code written against the list response shape — re-fetch the comment via GET /v1/inbox/comments/:commentId if you need the formatted form.


{
  "data": {
    "id": "cmt_example123",
    "accountId": "acc_example456",
    "postId": "pst_example789",
    "platformPostId": "17851234567890123",
    "platformCommentId": "17891234567890456",
    "platform": "INSTAGRAM",
    "authorId": "9876543210",
    "authorUsername": "janedoe",
    "authorAvatarUrl": "https://cdn.example.com/avatars/janedoe.jpg",
    "contactId": null,
    "content": "This is exactly what I needed, thanks!",
    "createdAt": "2026-08-01T14:23:05.000Z",
    "platformCreatedAt": "2026-08-01T14:23:00.000Z",
    "isReply": false,
    "parentCommentId": null,
    "replied": false,
    "repliedAt": null,
    "ourReplyId": null,
    "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 comment was hidden. `null` after unhiding

Error Responses

Status	Code	Description
404	`NOT_FOUND`	Comment does not exist or does not belong to the active workspace

Hidden comments

Hiding is a VoxBurst-side visibility control. It does not hide, delete, or otherwise modify the comment on the social platform.

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

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

Hidden comments are excluded from list responses by default, and total / hasMore reflect only the visible set. No tombstone or placeholder is returned for a hidden comment. 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.

Sync Comments

POST /v1/inbox/sync

Triggers a comment sync across every active connected account in the workspace.

Response (200)


{
  "success": true,
  "totalSynced": 14,
  "totalErrors": 0,
  "accounts": [
    {
      "accountId": "acc_example456",
      "platform": "INSTAGRAM",
      "synced": 14,
      "errors": [],
      "message": "Synced 14 comments"
    }
  ]
}

POST /v1/accounts/:accountId/comments/sync

Syncs a single account. Returns { "synced": number, "errors": string[], "message": string }.

Sync is best-effort per account. A failure on one account does not fail the whole request — it is reported in that account’s errors array with totalErrors incremented.