Messaging

Endpoints related to reading and sending direct messages on connected social media accounts.

List conversations

get

Lists the current user's direct-message conversations from their connected social accounts, ordered by last activity time (most recent first). Supports cursor-based pagination and filtering by platform and account.

Authorizations
blotato-api-keystringRequired
Query parameters
limitinteger ยท min: 1 ยท max: 250Optional

Maximum number of conversations to return. Defaults to 50.

Default: 50
cursorstringOptional

Opaque cursor returned by a previous call. Pass it to fetch the next page.

platformstring ยท enumOptionalPossible values:
accountIdstringOptional

Filter to conversations belonging to a single connected account.

Responses
200

Default Response

application/json
cursorstringOptional

Cursor for the next page. Absent when there are no more conversations.

get
/v2/conversations

Get a conversation

get

Fetches a single conversation by id, including participant metadata.

Authorizations
blotato-api-keystringRequired
Path parameters
conversationIdstringRequired
Responses
200

Default Response

application/json
accountIdstringRequired

ID of the social account this conversation belongs to.

createdAtstringRequired
idstringRequired
platformstring ยท enumRequiredPossible values:
updatedAtstringRequired
get
/v2/conversations/{conversationId}

List messages

get

Lists the current user's messages from their connected social accounts, ordered by creation time (most recent first). Supports cursor-based pagination and filtering by platform and conversation.

Authorizations
blotato-api-keystringRequired
Query parameters
limitinteger ยท min: 1 ยท max: 250Optional

Maximum number of messages to return. Defaults to 50.

Default: 50
cursorstringOptional

Opaque cursor returned by a previous call. Pass it to fetch the next page.

conversationIdstringOptional

Filter to messages within a single conversation.

accountIdstringOptional

Filter to messages belonging to a single connected account.

Responses
200

Default Response

application/json
cursorstringOptional

Cursor for the next page. Absent when there are no more messages.

get
/v2/messages

Send a message

post

Sends a direct message to a single recipient on the specified platform.

Authorizations
blotato-api-keystringRequired
Body
accountIdstringRequired

Blotato id of the connected social account the message is sent from.

targetone ofRequired
or
or
recipientIdstringRequired

Platform-native id of the recipient (e.g. Instagram business-scoped user id, Facebook PSID, X user id, Bluesky DID).

textstring ยท min: 1 ยท max: 10000Required

Plain-text message body.

Responses
post
/v2/messages

Last updated