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

apiKey

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.

404

Not found

application/json

422

Validation error

application/json

500

Server error

application/json

get

/v2/conversations

HTTPcURLJavaScriptPython

GET /v2/conversations HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "accountId": "text",
      "createdAt": "text",
      "id": "text",
      "participants": [
        {
          "id": "text",
          "name": "text",
          "profileImageUrl": "text",
          "username": "text"
        }
      ],
      "platform": "bluesky",
      "updatedAt": "text"
    }
  ],
  "cursor": "text"
}

Get a conversation

get

Fetches a single conversation by id, including participant metadata.

Authorizations

apiKey

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

404

Not found

application/json

500

Server error

application/json

get

/v2/conversations/{conversationId}

HTTPcURLJavaScriptPython

GET /v2/conversations/{conversationId} HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "accountId": "text",
  "createdAt": "text",
  "id": "text",
  "participants": [
    {
      "id": "text",
      "name": "text",
      "profileImageUrl": "text",
      "username": "text"
    }
  ],
  "platform": "bluesky",
  "updatedAt": "text"
}

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

apiKey

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.

404

Not found

application/json

422

Validation error

application/json

500

Server error

application/json

get

/v2/messages

HTTPcURLJavaScriptPython

GET /v2/messages HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "conversationId": "text",
      "createdAt": "text",
      "errorCode": 1,
      "errorMessage": "text",
      "id": "text",
      "platform": "bluesky",
      "recipientId": "text",
      "senderId": "text",
      "status": "delivered",
      "text": "text"
    }
  ],
  "cursor": "text"
}

Send a message

post

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

Authorizations

apiKey

blotato-api-keystringRequired

Body

application/json

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

201

Default Response

application/json

404

Not found

application/json

422

Validation error

application/json

429

Rate limit exceeded

application/json

500

Server error

application/json

post

/v2/messages

HTTPcURLJavaScriptPython

POST /v2/messages HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 169

{
  "accountId": "text",
  "target": {
    "targetType": "facebook",
    "pageId": "123456789",
    "commentId": "text",
    "responseType": "RESPONSE",
    "tag": "text"
  },
  "recipientId": "text",
  "text": "text"
}

{
  "conversationId": "text",
  "createdAt": "text",
  "errorCode": 1,
  "errorMessage": "text",
  "id": "text",
  "platform": "bluesky",
  "recipientId": "text",
  "senderId": "text",
  "status": "delivered",
  "text": "text"
}