---
title: "List Conversation Messages"
method: POST
path: "/conversations/{id}/messages"
tags: ["Conversations"]
---

# List Conversation Messages

`POST /conversations/{id}/messages`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/conversations/{id}/messages`
- Auth: API key in header `PINNACLE-API-KEY`

Retrieve a paginated and filtered list of messages for a specific conversation.

## Path parameters

- `id` string, required

## Query parameters

- `pageIndex` integer
- `pageSize` integer
- `sortOrder` 'asc' | 'desc'
- `direction` 'INBOUND' | 'OUTBOUND'
- `status` 'PENDING' | 'SENT' | 'SEND_FAILED' | 'DELIVERED' | 'DELIVERY_FAILED' | 'FALLBACK_SENT' | 'RECEIVED' | 'READ'
- `type` 'SMS' | 'MMS' | 'RCS'
- `dateFrom` string, date-time
- `dateTo` string, date-time

## Response `200`

Returns a paginated list of messages in the conversation.

- ListConversationMessagesResponse: Paginated list of messages in a conversation.
  - `messages` MessageWithReactions[], required: Array of messages in the conversation.
    - `content` union, required: Content type of the message.
      - SMSContent: SMS message containing plain text only.
        - `text` string, required: Message content.
      - MMSContent: Message with text and/or media files from a phone number.
        - `mediaUrls` string[], required: URLs of media files in this message. <br> See [supported media types](https://app.pinnacle.sh/supported-file-types?type=MMS).
        - `text` string: Text content that accompanies the media files.
      - union: Message with richer content (longer text, media files, cards, and buttons) from interacting with an RCS agent.
        - RcsTextContent: Message containing longer text content with optional quick reply buttons.
          - `quickReplies` RichButton[]: List of interactive quick reply buttons in the message. <br><br> **Limit:** 10 max
            - union
              - …
          - `text` string, required: Text content of the RCS message.
        - RcsMediaContent: Message containing a media file and/or text with optional quick reply buttons. <br> See (supported file types)[https://app.pinnacle.sh/supported-file-types?type=RCS-MEDIA].
          - `media` RcsMediaDetailsContent, required: Metadata about the media file in the message.
            - `fullPath` string: Path to the file in Pinnacle's storage.
            - `mimeType` string, required: Detected MIME type of the media file.
            - `url` string, required: Direct URL to the media file.
          - `quickReplies` RichButton[]: List of interactive quick reply buttons in the message. <br><br> **Limit:** 10 max
            - union
              - …
        - RcsCardsContent: Message containing cards, each with its own title, subtitle, and/or buttons. Quick replies can also be added. <br> See (supported file types)[https://app.pinnacle.sh/supported-file-types?type=RCS-CARD].
          - `cards` RcsCardsContentCardsItems[], required: Collection of cards attached to the message. <br><br> **Limit:** 1 to 10
            - `buttons` RichButton[]: While buttons resemble quick replies, they remain on screen after being clicked and are card-specific. <br><br> **Limit:** 4 max
              - …
            - `media` RcsMediaDetailsContent: Metadata about the media file in the message.
              - …
            - `subtitle` string: Secondary text displayed below the title for additional context.
            - `title` string, required: Title displayed on the card.
          - `quickReplies` RichButton[]: List of interactive quick reply buttons in the message. <br><br> **Limit:** 10 max
            - union
              - …
      - union
        - ButtonClickedData: Unified data structure for button click events.
          - `button` ButtonClickedDataButton, required: Information about the button that was clicked.
            - `type` 'CARD' | 'QUICK_REPLY': Type of button clicked. - `CARD` for card buttons, - `QUICK_REPLY` for quick replies. - `null` if we cannot determine the button type. This is a rare edge case and is mainly here for backward compatibility.
            - `raw` union, required: Raw button data. Contains the entire button that was clicked by the user. In rare cases where we cannot determine the exact button, this will return only the button title.
              - …
            - `payload` string, nullable: Extracted payload from the button's `payload` field, if provided. Provides quick access to any payload that was attached to the button.
            - `metadata` string, nullable: Additional metadata attached to the button's `metadata` field, if provided.
            - `clicks` integer, required: Number of times the button has been clicked.
          - `messageId` string, nullable, required: ID of the message this button was sent in, or null if not available. To get the message details, use the [GET /messages/{id}](/api-reference/messages/get) endpoint.
        - LocationShareAction
          - `data` LocationShareActionData, required: Location data shared by the user.
            - `address` string, required: Address corresponding to the shared location.
            - `latitude` number, double, required: Latitude of the shared location.
            - `longitude` number, double, required: Longitude of the shared location.
            - `text` string: Text message sent with the location.
    - `cost` number, double, nullable, required: Total cost charged for sending the message. <br> Null means the message incurred no cost or has not been charged yet.
    - `deliveredAt` string, nullable, required: Timestamp indicating when the message was successfully delivered to the recipient. <br> Null indicates the message has not yet been delivered.
    - `error` string, nullable, required: Detailed explanation of any errors that occurred while delivering the message. <br> Null indicates no errors.
    - `id` string, required: Unique identifier of the message. This identifier is a string that always begins with the prefix `msg_`, for example: `msg_1234567890`.
    - `method` 'API' | 'SDK' | 'OTHER', required: Method used to send the message.
    - `numSegments` integer, required: Number of segments the message was split into for delivery.
    - `receiver` string, required: Phone number that received the message in E.164 format.
    - `sender` string, required: Phone number or agent that sent the message.
    - `sentAt` string, nullable, required: Timestamp indicating when the message was submitted for delivery. <br> Null indicates the message is still in the queue.
    - `status` 'QUEUED' | 'PENDING' | 'SENT' | 'SEND_FAILED' | 'DELIVERED' | 'DELIVERY_FAILED' | 'RECEIVED' | 'READ' | 'FALLBACK_SENT', required: Current status of the message.
    - `type` 'SMS' | 'MMS' | 'RCS', required: Delivery protocol used for sending this message.
    - `direction` 'INBOUND' | 'OUTBOUND', required: Direction of the message flow.
    - `reactions` string[], required: Array of unicode emoji reactions attached to this message. <br> Empty array indicates no reactions have been added.
  - `hasMore` boolean, required: Indicates if more messages are available beyond the current page.
  - `count` integer, required: Total number of messages in the conversation.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `404`: Conversation not found
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)