Get a social conversation

GET

/v1/social/conversations/{id}

• Production

Returns one DM conversation with its participant and the CRM contact it is bridged to. Requires scope social:read.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

integer

Responses

200

Conversation found.

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

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