--- title: "List messages for a conversation" method: GET path: "/v3/conversations/{id}" tags: ["Conversations"] --- # List messages for a conversation `GET /v3/conversations/{id}` ## Request - Base URL: `https://api.sent.dm` - URL: `https://api.sent.dm/v3/conversations/{id}` - Auth: one of: - API key in header `x-api-key` - HTTP bearer Retrieves a paginated list of the messages in a single conversation (scoped to the authenticated customer), ordered by created date (most recent first). ## Path parameters - `id` string, uuid, required ## Query parameters - `page` integer, required - `page_size` integer, required ## Headers - `x-profile-id` string, uuid ## Response `200` Messages retrieved successfully - SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfConversationMessagesListResponse: Standard API response envelope for all v3 endpoints - `success` boolean: Indicates whether the request was successful - `data` SentDmServicesEndpointsCustomerAPIv3ConversationsResponsesConversationMessagesListResponse: A paginated list of messages — used by both conversation read endpoints. - `messages` SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageResponse[]: The messages on this page. - `id` string, uuid - `customer_id` string, uuid - `contact_id` string, uuid - `phone` string - `phone_international` string - `region_code` string - `template_id` string, uuid, nullable - `template_name` string, nullable - `template_category` string, nullable - `channel` string - `message_body` SentDmServicesCommonEntitiesMessageBody: Structured message body format for database storage. Preserves channel-specific components (header, header media, body, footer, buttons, MMS subject and media). Persisted as the messageBody jsonb column on Messages. Every write path goes through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope shape is stable regardless of channel or status. Anything that rebuilds this object field by field — the four IMessageBodyStrategy implementations and MessageUtils.BuildSegmentBody — has to carry every member, or that member is silently dropped on whichever path forgot it. - `header` string, nullable - `content` string - `footer` string, nullable - `buttons` SentDmServicesCommonEntitiesMessageButton[], nullable - `type` string - `text` string, nullable - `value` string - `postbackData` string, nullable - `subject` string, nullable: MMS subject line. Null on every other channel. - `media` SentDmServicesCommonEntitiesMessageMedia[], nullable: MMS attachments, as the publicly fetchable URLs handed to the carrier. Null on every other channel. Persisted rather than derived because a resend and a curfew release rebuild the send from the stored row — MessageReplayCommandBuilder reads templateId and templateVariables and nothing else — so media that lives only on the original request would silently turn a replayed MMS into a text message. - `url` string, nullable: Where the file lives. Outbound: the URL the customer gave us and the carrier fetched. Inbound: the URL the carrier hosts it at, relayed unchanged. - `mediaType` string, nullable: One of MmsMediaTypes when the content type is known. Advisory — a reader should trust the fetched object's own Content-Type. - `mimeType` string, nullable: Content type as the provider declared it. Null when it declared none. - `sizeBytes` integer, nullable: Size as the provider declared it. Never measured here — nothing downloads the file. - `sourceHashSha256` string, nullable: Inbound only: the SHA-256 the provider declared alongside the attachment, when it declared one. Relayed to the customer so they can verify what they fetch matches what the carrier said it sent. It is the only integrity signal available on an attachment nobody here has read. - `headerMedia` SentDmServicesCommonEntitiesMessageHeaderMedia: The media asset that rode a message's header, recorded as sent. - `type` string: "image", "video" or "document" — taken from the header's media variable. - `url` string: The https URL the caller supplied for this send. Never the template's stored props.sample, which is Meta's expiring header_handle rather than what was delivered. - `status` string - `direction` string - `created_at` string, date-time - `price` number, nullable - `active_contact_price` number, nullable - `events` SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageEventV3[], nullable - `status` string, required - `timestamp` string, date-time, required - `description` string, nullable - `reason_code` string, nullable: Why the message reached this status, as a stable platform code such as DELIVERY_007. Present on FAILED, FILTERED and BLOCKED events; omitted on every status that needs no explanation. Same wire name and vocabulary as on the activities list and the webhook. - `reason` string, nullable: A human-readable sentence for reason_code. Omitted whenever reason_code is. - `reason_code` string, nullable: Why the message is at its current status, as a stable platform code such as DELIVERY_007, BUSINESS_003 or DELIVERY_003. Present when the current status is FAILED, FILTERED or BLOCKED and the lifecycle was loaded; omitted otherwise. Switch on this rather than on reason: the code is stable, the wording may be improved. It is the platform's classification of the outcome, never a carrier or vendor code. - `reason` string, nullable: A human-readable sentence for reason_code, for example "Insufficient balance". Omitted whenever reason_code is. - `pagination` SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta: Pagination metadata for list responses - `page` integer: Current page number (1-indexed) - `page_size` integer: Number of items per page - `total_count` integer: Total number of items across all pages - `total_pages` integer: Total number of pages - `has_more` boolean: Whether there are more pages after this one - `cursors` SentDmServicesEndpointsCustomerAPIv3SharedPaginationCursors: Cursor-based pagination. Never populated — see Cursors. - `after` string, nullable: Cursor to fetch the next page. - `before` string, nullable: Cursor to fetch the previous page. - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information - `code` string: Machine-readable error code (e.g., "RESOURCE_001") - `message` string: Human-readable error message - `details` object, nullable: Additional validation error details (field-level errors) - `doc_url` string, nullable: URL to documentation about this error - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata - `request_id` string: Unique identifier for this request (for tracing and support) - `timestamp` string, date-time: Server timestamp when the response was generated - `version` string: API version used for this request ## Other responses - `400`: Invalid request parameters - `401`: Unauthorized - Invalid API credentials - `403`: Forbidden - `500`: Internal server error ## Changes - **2026-10-16** `6c829543a93e`: 3 breaking, 12 info - added `#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta` to the `meta` response property `oneOf` list for the response status `200` - added `#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta` to the `meta` response property `oneOf` list for the response status `400` - added `#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta` to the `meta` response property `oneOf` list for the response status `500` - the endpoint scheme security `BearerAuth` was added to the API - …11 more - **2026-07-02** `1e113b6a003b`: 2 info - the response property `data/allOf[#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ResponsesConversationMessagesListResponse]/messages/items/events/items/status` became required for the status `200` - the response property `data/allOf[#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ResponsesConversationMessagesListResponse]/messages/items/events/items/timestamp` became required for the status `200` - **2026-06-29** `39acec16c055`: 1 info - endpoint added [Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/conversations/:id/get.md) --- [API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)