---
title: "List Conversations"
method: POST
path: "/conversations/list"
tags: ["Conversations"]
---

# List Conversations

`POST /conversations/list`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/conversations/list`
- Auth: API key in header `PINNACLE-API-KEY`

Retrieves conversations by page with optional filtering based off provided parameters.

## Request body

- ListConversationsRequest: Parameters for listing conversations.
  - `brandId` string: The unique identifier of the brand to filter conversations. This identifier is a string that always begins with the prefix `b_`, for example: `b_1234567890`.
  - `campaignId` string: The unique identifier of the campaign to filter conversations. This identifier is a string that begins with the prefix: - TOLL_FREE: `tf_` (e.g., `tf_1234567890`) - 10DLC: `dlc_` (e.g., `dlc_1234567890`) - RCS: `rcs_` (e.g., `rcs_1234567890`)
  - `campaignType` 'TOLL_FREE' | '10DLC' | 'RCS': The type of campaign: - TOLL_FREE: Toll-free number campaigns - 10DLC: 10-digit long code campaigns for A2P messaging - RCS: Rich Communication Services campaigns
  - `pageIndex` integer, required: Zero-based index for pagination.
  - `pageSize` integer: Number of conversations to return per page.
  - `receiver` string: Receiver's phone number in E.164 format.
  - `sender` string: The sender identifier. Can be either: - A phone number in E.164 format - An RCS agent ID prefixed with 'agent_'

## Response `200`

Returns conversations that meets your filters.

- ListConversationsResponse: Response for list conversation.
  - `count` integer, required: Total number of conversations matching the filter.
  - `conversations` Conversation[], required
    - `brandId` string, nullable, required: The unique identifier of the brand associated with this conversation. This identifier is a string that always begins with the prefix `b_`, for example: `b_1234567890`.
    - `campaign` CampaignQuery, required: Information about the campaign associated with a conversation
      - `id` string, required: Unique identifier for the campaign. This identifier is a string that begins with the prefix: - TOLL_FREE: `tf_` (e.g., `tf_1234567890`) - 10DLC: `dlc_` (e.g., `dlc_1234567890`) - RCS: `rcs_` (e.g., `rcs_1234567890`)
      - `type` 'TOLL_FREE' | '10DLC' | 'RCS', required: The type of campaign: - TOLL_FREE: Toll-free number campaigns - 10DLC: 10-digit long code campaigns for A2P messaging - RCS: Rich Communication Services campaigns
    - `contact` ConversationContact, required: Contact information for the recipient in a conversation.
      - `id` string, required: Unique ID of the contact. This identifier is a string that always begins with the prefix `co_`, for example: `co_1234567890`.
      - `phoneNumber` string, required: The contact's phone number in E.164 format.
    - `createdAt` string, required: ISO 8601 timestamp when the conversation was created.
    - `id` string, required: Unique identifier for the conversation. This identifier is a string that always begins with the prefix `conv_`, for example: `conv_1234567890`.
    - `notes` string, required: Free-form notes or comments about the conversation.
    - `sender` union, required: The sender of messages in this conversation. Can be: - A phone number with its capabilities and metadata - An RCS agent with ID and name - `null` if no sender is associated
      - ConversationSender0: Information about a phone number sender in a conversation.
        - `capabilities` PhoneCapabilities, required: Represents the communication capabilities available for a phone number.
          - `mms` boolean, required: Whether the phone number supports MMS (multimedia messaging).
          - `sms` boolean, required: Whether the phone number supports SMS messaging.
          - `voice` boolean, required: Whether the phone number supports voice calls.
        - `createdAt` string, required: ISO 8601 timestamp when the phone sender was created.
        - `isSandbox` boolean, required: Whether this phone number is in sandbox/testing mode.
        - `phoneNumber` string, required: The sender's phone number in E.164 format.
        - `updatedAt` string, required: ISO 8601 timestamp when the phone sender was last updated
      - ConversationSender1: Information about an RCS agent sender in a conversation.
        - `agentId` string, required: Unique identifier for the RCS agent.
        - `agentName` string, required: Display name of the RCS agent.
    - `updatedAt` string, required: ISO 8601 timestamp when the conversation was last updated.
  - `hasMore` boolean, required: Indicates if more conversations are available beyond the current page.

## 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.
- `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)