Messaging
Endpoints related to reading and sending direct messages on connected social media accounts.
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.
Maximum number of conversations to return. Defaults to 50.
50Opaque cursor returned by a previous call. Pass it to fetch the next page.
Filter to conversations belonging to a single connected account.
Default Response
Cursor for the next page. Absent when there are no more conversations.
Forbidden
Not found
Validation error
Server error
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": "facebook",
"updatedAt": "text"
}
],
"cursor": "text"
}Fetches a single conversation by id, including participant metadata.
Default Response
ID of the social account this conversation belongs to.
Forbidden
Not found
Server error
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": "facebook",
"updatedAt": "text"
}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.
Maximum number of messages to return. Defaults to 50.
50Opaque cursor returned by a previous call. Pass it to fetch the next page.
Filter to messages within a single conversation.
Filter to messages belonging to a single connected account.
Default Response
Cursor for the next page. Absent when there are no more messages.
Forbidden
Not found
Validation error
Server error
GET /v2/messages HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*
{
"items": [
{
"conversationId": "text",
"createdAt": "text",
"direction": "incoming",
"errorCode": 1,
"errorMessage": "text",
"id": "text",
"payload": {
"attachment": {
"type": "button",
"buttons": [
{
"type": "web_url",
"title": "text",
"url": "text"
}
]
},
"quickReplies": [
{
"title": "text",
"payload": "text"
}
],
"selection": {
"payload": "text",
"type": "postback"
}
},
"platform": "facebook",
"recipientId": "text",
"senderId": "text",
"status": "delivered",
"text": "text"
}
],
"cursor": "text"
}Sends a direct message to a single recipient on the specified platform.
Blotato id of the connected social account the message is sent from.
Platform-native id of the recipient (e.g. Instagram business-scoped user id).
Plain-text message body.
Default Response
Parent Blotato conversation id.
Set only when status is failed.
Set only when status is failed.
Forbidden
Not found
Validation error
Rate limit exceeded
Server error
POST /v2/messages HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 310
{
"accountId": "text",
"target": {
"targetType": "facebook",
"pageId": "123456789",
"attachment": {
"type": "button",
"buttons": [
{
"type": "web_url",
"title": "text",
"url": "text"
}
]
},
"commentId": "text",
"quickReplies": [
{
"title": "text",
"payload": "text"
}
],
"responseType": "RESPONSE",
"tag": "text"
},
"recipientId": "text",
"text": "text"
}{
"conversationId": "text",
"createdAt": "text",
"direction": "incoming",
"errorCode": 1,
"errorMessage": "text",
"id": "text",
"payload": {
"attachment": {
"type": "button",
"buttons": [
{
"type": "web_url",
"title": "text",
"url": "text"
}
]
},
"quickReplies": [
{
"title": "text",
"payload": "text"
}
],
"selection": {
"payload": "text",
"type": "postback"
}
},
"platform": "facebook",
"recipientId": "text",
"senderId": "text",
"status": "delivered",
"text": "text"
}Fetches a single direct message by its Blotato ID. The message may be an inbound message received from a contact, or an outbound message the user sent through Blotato.
Blotato id of the message to fetch.
Default Response
Parent Blotato conversation id.
Set only when status is failed.
Set only when status is failed.
Forbidden
Not found
Server error
GET /v2/messages/{messageId} HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*
{
"conversationId": "text",
"createdAt": "text",
"direction": "incoming",
"errorCode": 1,
"errorMessage": "text",
"id": "text",
"payload": {
"attachment": {
"type": "button",
"buttons": [
{
"type": "web_url",
"title": "text",
"url": "text"
}
]
},
"quickReplies": [
{
"title": "text",
"payload": "text"
}
],
"selection": {
"payload": "text",
"type": "postback"
}
},
"platform": "facebook",
"recipientId": "text",
"senderId": "text",
"status": "delivered",
"text": "text"
}Last updated