---
title: "List messages"
method: GET
path: "/inbox/conversations/{conversationId}/messages"
tags: ["Inbox"]
---

# List messages

`GET /inbox/conversations/{conversationId}/messages`

## Request

- Base URL: `https://api.omnisocials.com/v1`
- URL: `https://api.omnisocials.com/v1/inbox/conversations/{conversationId}/messages`
- Auth: HTTP bearer

Returns the full message history of a conversation, oldest first, cursor-paginated. Requires the `inbox:read` scope (API keys) or the `access_social_inbox` permission (OAuth/MCP).

## Path parameters

- `conversationId` string, required

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

A page of messages

- object
  - `data` InboxMessage[]
    - `id` string
    - `conversation_id` string
    - `platform` string
    - `type` 'dm' | 'comment' | 'mention'
    - `direction` 'incoming' | 'outgoing'
    - `text` string
    - `timestamp` string, date-time
    - `is_read` boolean
    - `is_replied` boolean
    - `reaction` string, nullable
    - `parent_comment_id` string, nullable
    - `hidden` boolean, nullable: Comments only: true when the comment is hidden on the platform (see POST /inbox/messages/{id}/hide). Null for DMs.
    - `liked` boolean, nullable: Incoming Facebook, LinkedIn Page and TikTok comments: true when the connected account liked the comment (see POST /inbox/messages/{id}/like). Facebook and LinkedIn report likes made through OmniSocials; TikTok also reports likes made in the TikTok app. Null for DMs, outgoing messages and the other platforms.
    - `permalink` string, nullable: Link to the reply or mentioning post on the platform, when known
    - `attachment` object, nullable: Media sent with this message, when present. Incoming Instagram/Facebook DM images, videos, voice messages, and story mentions are re-hosted on our CDN so the URL stays valid indefinitely (the platform's own URL is short-lived). `type` reflects the fetched bytes, not the platform's label: a photo the platform sent under an unlabelled attachment type is `image`, a story mention that is really an MP4 is `video`. `type: file` covers media we could fetch but could not classify. `type: link` means the platform's URL did not point at media (for example a shared post that resolves to an instagram.com page); `url` is then the platform's own link, not re-hosted, and may require login or expire.
      - `url` string
      - `type` 'image' | 'video' | 'audio' | 'file' | 'link'
    - `sender` InboxParticipant
      - `id` string: Platform-scoped id of the other party
      - `name` string
      - `username` string
      - `profile_picture` string, nullable
    - `post` InboxPostContext, nullable: The post a comment/mention conversation belongs to, so a reply can be drafted with the post in view ("what size is this?" needs the caption and the picture). Null for DMs. `url` is the public link to the post when the platform provides one (Instagram, Facebook, YouTube, TikTok, LinkedIn, Threads); `media_type` is the platform's label (e.g. IMAGE, VIDEO, CAROUSEL_ALBUM on Instagram) when known.
      - `id` string, nullable
      - `caption` string, nullable
      - `thumbnail` string, nullable: Image URL of the post (or the video's cover)
      - `url` string, nullable
      - `media_type` string, nullable
  - `pagination` InboxCursorPagination
    - `next_cursor` string, nullable: Pass as ?cursor= to fetch the next page; null when there are no more results
    - `has_more` boolean
    - `limit` integer

## Other responses

- `404`: Conversation not found in this workspace

## Changes

- **2026-10-27** `79cdeec29f82`: 1 info
  - added the optional property `data/items/liked` to the response with the `200` status
- **2026-09-07** `bff746fd6191`: 1 warning, 2 info
  - added the new `link` enum value to the `data/items/attachment/type` response property for the response status `200`
  - added the optional property `data/items/post/media_type` to the response with the `200` status
  - added the optional property `data/items/post/url` to the response with the `200` status

[Operation history](https://skmtc.dev/omnisocials/apis/omnisocials-api/changes/inbox/conversations/:conversationId/messages/get.md)

---

[API](https://skmtc.dev/omnisocials/apis/omnisocials-api.md) - [All operations](https://skmtc.dev/omnisocials/apis/omnisocials-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisocials/apis/omnisocials-api/revisions/46e479c09474?raw)