List social DM conversations

GET

/v1/social/conversations

• Production

Cursor-paginated DM conversations. Ordering is by id descending, not by last activity, so a page boundary cannot shift under a client walking the whole inbox; every item carries LastMessageAt and UnreadCount for activity sorting, and GET /v1/social/inbox/summary answers “who is waiting” in one call. Pass after=<id> for the next page. Requires scope social:read.

Authorizations

• bearerAuth

Parameters

Query Parameters

platform

string

status

string

Allowed values: active archived

contactId

integer

Only the conversation bridged to this CRM contact.

limit

integer

default: 25 >= 1 <= 100

after

integer

Return conversations with an id lower than this.

Responses

200

Paginated conversation list.

object

items

Array<object>

One direct-message thread with a person on a social network.

object

id

integer

accountId

Connected account that owns the thread.

integer

nullable

externalAccountId

string

externalConversationId

The network’s own thread id.

string

platform

string

Example

whatsapp

participantId

string

nullable

participantName

string

nullable

participantUsername

string

nullable

participantAvatarUrl

string

nullable

participantLanguage

Language detected on the participant’s latest inbound message. Drives outbound auto-translation when it is enabled.

string

nullable

lastMessagePreview

string

nullable

lastMessageOutgoing

True when the last line was sent by the workspace.

boolean

nullable

lastMessageAt

string format: date-time

nullable

unreadCount

integer

status

string

Allowed values: active archived

contactId

CRM contact this thread is bridged to

integer

nullable

createdAt

string format: date-time

updatedAt

string format: date-time

nullable

nextCursor

integer

nullable

hasMore

boolean

400

The request body or parameters failed validation.

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": "bad_request",
  "message": "at least one of name, username, phone is required"
}

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"
}

429

Per-key rate limit exceeded. Retry after the time indicated by X-RateLimit-Reset.

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": "rate_limited",
  "message": "rate limit exceeded"
}

Headers

X-RateLimit-Limit

integer

Maximum requests allowed per minute for this key.

X-RateLimit-Remaining

integer

Requests remaining in the current window.

X-RateLimit-Reset

integer

Unix timestamp (seconds) when the rate limit window resets.