> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/api/openapi-reference/messaging.md).

# Messaging

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

## List conversations

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Blotato API","version":"2.0.0"},"tags":[{"name":"messaging","description":"Endpoints related to reading and sending direct messages on connected social media accounts."}],"servers":[{"url":"https://backend.blotato.com","description":"Blotato API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"blotato-api-key","in":"header"}}},"paths":{"/v2/conversations":{"get":{"summary":"List conversations","tags":["messaging"],"description":"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.","parameters":[{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of conversations to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."},{"schema":{"type":"string","enum":["bluesky","facebook","instagram","twitter"]},"in":"query","name":"platform","required":false},{"schema":{"type":"string"},"in":"query","name":"accountId","required":false,"description":"Filter to conversations belonging to a single connected account."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of conversations.","type":"array","items":{"type":"object","properties":{"accountId":{"description":"ID of the social account this conversation belongs to.","type":"string"},"createdAt":{"type":"string"},"id":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Platform-native ID of the participant.","type":"string","nullable":true},"name":{"description":"Display name of the participant.","type":"string","nullable":true},"profileImageUrl":{"type":"string","nullable":true},"username":{"description":"Platform handle / @username of the participant.","type":"string","nullable":true}},"required":["id","name","profileImageUrl","username"]}},"platform":{"type":"string","enum":["bluesky","facebook","instagram","twitter"]},"updatedAt":{"type":"string"}},"required":["accountId","createdAt","id","participants","platform","updatedAt"]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more conversations.","type":"string"}},"required":["items"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"}},"required":["message"]}}}}}}}}}
```

## Get a conversation

> Fetches a single conversation by id, including participant metadata.

```json
{"openapi":"3.0.3","info":{"title":"Blotato API","version":"2.0.0"},"tags":[{"name":"messaging","description":"Endpoints related to reading and sending direct messages on connected social media accounts."}],"servers":[{"url":"https://backend.blotato.com","description":"Blotato API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"blotato-api-key","in":"header"}}},"paths":{"/v2/conversations/{conversationId}":{"get":{"summary":"Get a conversation","tags":["messaging"],"description":"Fetches a single conversation by id, including participant metadata.","parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"description":"ID of the social account this conversation belongs to.","type":"string"},"createdAt":{"type":"string"},"id":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Platform-native ID of the participant.","type":"string","nullable":true},"name":{"description":"Display name of the participant.","type":"string","nullable":true},"profileImageUrl":{"type":"string","nullable":true},"username":{"description":"Platform handle / @username of the participant.","type":"string","nullable":true}},"required":["id","name","profileImageUrl","username"]}},"platform":{"type":"string","enum":["bluesky","facebook","instagram","twitter"]},"updatedAt":{"type":"string"}},"required":["accountId","createdAt","id","participants","platform","updatedAt"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"}},"required":["message"]}}}}}}}}}
```

## List messages

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Blotato API","version":"2.0.0"},"tags":[{"name":"messaging","description":"Endpoints related to reading and sending direct messages on connected social media accounts."}],"servers":[{"url":"https://backend.blotato.com","description":"Blotato API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"blotato-api-key","in":"header"}}},"paths":{"/v2/messages":{"get":{"summary":"List messages","tags":["messaging"],"description":"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.","parameters":[{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of messages to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."},{"schema":{"type":"string"},"in":"query","name":"conversationId","required":false,"description":"Filter to messages within a single conversation."},{"schema":{"type":"array","items":{"type":"string","enum":["bluesky","facebook","instagram","twitter"]}},"in":"query","name":"platform","required":false,"description":"Filter messages by platform. Pass multiple values to include any of them."},{"schema":{"type":"string"},"in":"query","name":"accountId","required":false,"description":"Filter to messages belonging to a single connected account."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of messages.","type":"array","items":{"type":"object","properties":{"conversationId":{"description":"Parent Blotato conversation id.","type":"string","nullable":true},"createdAt":{"type":"string"},"errorCode":{"description":"Set only when status is `failed`.","type":"integer","nullable":true},"errorMessage":{"description":"Set only when status is `failed`.","type":"string","nullable":true},"id":{"type":"string"},"platform":{"type":"string","enum":["bluesky","facebook","instagram","twitter"]},"recipientId":{"type":"string"},"senderId":{"type":"string","nullable":true},"status":{"type":"string","enum":["delivered","failed","processing","queued","sent"]},"text":{"type":"string"}},"required":["conversationId","createdAt","errorCode","errorMessage","id","platform","recipientId","senderId","status","text"]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more messages.","type":"string"}},"required":["items"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"}},"required":["message"]}}}}}}}}}
```

## Send a message

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

```json
{"openapi":"3.0.3","info":{"title":"Blotato API","version":"2.0.0"},"tags":[{"name":"messaging","description":"Endpoints related to reading and sending direct messages on connected social media accounts."}],"servers":[{"url":"https://backend.blotato.com","description":"Blotato API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"blotato-api-key","in":"header"}}},"paths":{"/v2/messages":{"post":{"summary":"Send a message","tags":["messaging"],"description":"Sends a direct message to a single recipient on the specified platform.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"description":"Blotato id of the connected social account the message is sent from.","type":"string"},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"targetType":{"description":"Send via Facebook.","type":"string","enum":["facebook"]},"pageId":{"pattern":"^\\d+$","description":"ID of the Facebook Page to send from.","type":"string"},"commentId":{"description":"Platform-native id of a comment. When set, the message is delivered as a private reply to that comment instead of a direct message.","type":"string"},"responseType":{"type":"string","enum":["RESPONSE","UPDATE","MESSAGE_TAG"]},"tag":{"description":"Required when responseType is MESSAGE_TAG (e.g. HUMAN_AGENT).","type":"string"}},"required":["targetType","pageId"]},{"type":"object","properties":{"targetType":{"description":"Send via Instagram.","type":"string","enum":["instagram"]},"responseType":{"type":"string","enum":["RESPONSE","UPDATE","MESSAGE_TAG"]},"commentId":{"description":"Platform-native id of a comment. When set, the message is delivered as a private reply to that comment instead of a direct message.","type":"string"},"tag":{"description":"Required when responseType is MESSAGE_TAG (e.g. HUMAN_AGENT).","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Send via Twitter.","type":"string","enum":["twitter"]}},"required":["targetType"]}]},"recipientId":{"description":"Platform-native id of the recipient (e.g. Instagram business-scoped user id, Facebook PSID, X user id, Bluesky DID).","type":"string"},"text":{"minLength":1,"maxLength":10000,"description":"Plain-text message body.","type":"string"}},"required":["accountId","target","recipientId","text"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"description":"Parent Blotato conversation id.","type":"string","nullable":true},"createdAt":{"type":"string"},"errorCode":{"description":"Set only when status is `failed`.","type":"integer","nullable":true},"errorMessage":{"description":"Set only when status is `failed`.","type":"string","nullable":true},"id":{"type":"string"},"platform":{"type":"string","enum":["bluesky","facebook","instagram","twitter"]},"recipientId":{"type":"string"},"senderId":{"type":"string","nullable":true},"status":{"type":"string","enum":["delivered","failed","processing","queued","sent"]},"text":{"type":"string"}},"required":["conversationId","createdAt","errorCode","errorMessage","id","platform","recipientId","senderId","status","text"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"}},"required":["message"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Rate limit exceeded","type":"string"}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"}},"required":["message"]}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.blotato.com/api/openapi-reference/messaging.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.