List messages in a conversation

GET

/v1/social/conversations/{id}/messages

• Production

A conversation’s messages, newest first. Pass after=<messageId> to page into older messages. Voice notes carry their transcript and auto-translated messages carry both wordings. Inbound attachments are rewritten to a signed media proxy on this same host that needs no credentials of its own; the URL is relative, so prefix it with the API base. Requires scope social:read.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

integer

Query Parameters

limit

integer

default: 50 >= 1 <= 100

after

integer

Return messages with an id lower than this.

Responses

200

Paginated message list.

object

items

Array<object>

One message inside a social DM thread.

object

id

integer

conversationId

integer

externalMessageId

string

platform

string

direction

string

Allowed values: inbound outbound

senderExternalId

string

nullable

senderName

string

nullable

text

Empty on an attachment-only message.

string

nullable

attachmentUrl

Attachment link. Inbound network media is rewritten to a signed proxy path on this host (relative, no credentials needed); outbound and already-public URLs pass through unchanged.

string

nullable

attachmentType

string

nullable

Allowed values: image video audio file

replyToExternalMessageId

string

nullable

transcript

Speech-to-text for a voice note.

string

nullable

transcriptStatus

string

nullable

Allowed values: pending processing done failed unsupported

translation

Inbound, the message rendered in the operator’s language. Outbound, the operator’s original wording (text then holds what the participant received).

string

nullable

translationStatus

string

nullable

status

string

Allowed values: pending sent delivered read failed

errorMessage

string

nullable

sentAt

string format: date-time

nullable

deliveredAt

string format: date-time

nullable

readAt

string format: date-time

nullable

createdAt

string format: date-time

nextCursor

integer

nullable

hasMore

boolean

401

Missing or invalid bearer token.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden payment_required provider_rejected rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "unauthorized",
  "message": "Invalid bearer principal"
}

402

The workspace’s plan does not include this module. The social inbox needs channel_social_inbox and the post scheduler needs marketing_social_scheduler; details.FeatureKey names the one that is missing. Upgrading unlocks it, there is nothing to retry.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden payment_required provider_rejected rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "payment_required",
  "message": "your plan does not include this feature; upgrade to unlock it",
  "details": {
    "FeatureKey": "marketing_social_scheduler",
    "UpgradeRequired": true
  }
}

403

The API key does not have the required scope for this operation.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden payment_required provider_rejected rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "forbidden",
  "message": "scope contacts:write is required"
}

404

The requested resource does not exist or is not owned by the caller.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden payment_required provider_rejected rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "not_found",
  "message": "contact not found"
}