---
title: "Get Conversation"
method: POST
path: "/conversations/get"
tags: ["Conversations"]
---

# Get Conversation

`POST /conversations/get`

## Request

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

Fetch a specific conversation using either its unique identifier or by matching sender and recipient details.

## Request body

- union: Parameters for getting a specific conversation.
  - GetConversationRequest0: Retrieve conversation information by ID.
    - `id` string, required: Unique identifier of the conversation you want to retrieve. This identifier is a string that always begins with the prefix `conv_`, for example: `conv_1234567890`.
  - GetConversationRequest1: Retrieve conversation information by sender and recipient.
    - `recipient` string, required: The recipient's phone number in E.164 format
    - `sender` string, required: The sender identifier. Can be either: - A phone number in E.164 format - An RCS agent ID prefixed with 'agent_'

## Response `200`

Returns the full conversation details, or null if not found.

- Conversation: Conversation that was found.
  - `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.

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