Messages

Read Instagram or Facebook conversations and send permitted private replies using existing recipient IDs.

Blotato allows you to read and send direct messages on your Instagram account and Facebook Page. Twitter/X, TikTok, LinkedIn, Pinterest, Threads, Bluesky, and YouTube are not supported at this time. Five endpoints let you list conversations, read a conversation, list messages, read a message, and send a message:

• List Conversations — GET /v2/conversations

• Get Conversation — GET /v2/conversations/:conversationId

• List Messages — GET /v2/messages

• Get Message — GET /v2/messages/:messageId

• Send Message — POST /v2/messages

Messages are available on all paid plans.

To manage Instagram and Facebook conversations in the Blotato web app, see Comments and Messaging Inbox.

To send automatic replies after a comment or incoming message, use DM Automations. You manage these automations in the web app or through an AI tool connected to Blotato MCP.

Each message has a direction:

• Incoming messages your contacts send you. These have direction: "incoming".

• Outgoing messages you send through Blotato. These have direction: "outgoing".

You reply to people who already have a conversation with you. You send to a recipientId taken from an existing conversation or an incoming message, not to an arbitrary user. The social platform limits who you can message and when. See Messaging Windows.

Blotato retains messages for up to 45 days. Messages older than 45 days are not available through these endpoints.

Before You Start

Blotato must have permissions to read and send messages on your account before you can use the Blotato messaging endpoints.

If you connected your account before messaging launched, reconnect it so Blotato has the new permission.

• For Instagram, see Connect Instagram.

• For Facebook, see Connect Facebook.

---

List Conversations

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /conversations

Method: GET

Description

Returns your conversations across connected accounts, ordered by most recent activity. Use cursor-based pagination and the optional filters below.

Query Parameters

Field	Type	Required	Description
limit	integer	No	Maximum conversations to return (1-250). Default 50.
cursor	string	No	Cursor from a previous response. Pass it to fetch the next page.
platform	string	No	Filter by platform. Values: instagram, facebook.
accountId	string	No	Filter to a single connected account.

Response

Status Code: 200 OK

{
  "items": [
    {
      "id": "cnv_abc123",
      "accountId": "98434",
      "platform": "instagram",
      "participants": [
        {
          "id": "1784000000",
          "name": "Jamie Rivera",
          "username": "jamie.rivera",
          "profileImageUrl": "https://example.com/avatar.jpg"
        }
      ],
      "createdAt": "2026-07-01T12:00:00Z",
      "updatedAt": "2026-07-02T09:30:00Z"
    }
  ],
  "cursor": "eyJz..."
}

Field	Type	Description
items	array	List of conversations. See Conversation Object.
cursor	string	Cursor for the next page. Absent when there are no more conversations.

---

Get Conversation

Endpoint

URL: /conversations/:conversationId

Method: GET

Description

Fetches a single conversation by its Blotato ID.

Path Parameters

Field	Type	Required	Description
conversationId	string	Yes	Blotato ID of the conversation.

Response

Status Code: 200 OK

Returns a Conversation Object.

---

List Messages

Endpoint

URL: /messages

Method: GET

Description

Returns your messages across connected accounts, ordered by creation time (most recent first). Use cursor-based pagination and the optional filters below.

Query Parameters

Field	Type	Required	Description
limit	integer	No	Maximum messages to return (1-250). Default 50.
cursor	string	No	Cursor from a previous response. Pass it to fetch the next page.
conversationId	string	No	Filter to messages in a single conversation.
platform	array	No	Filter by platform. Values: instagram, facebook.
accountId	string	No	Filter to a single connected account.

Response

Status Code: 200 OK

{
  "items": [
    {
      "id": "msg_abc123",
      "conversationId": "cnv_abc123",
      "platform": "instagram",
      "direction": "incoming",
      "senderId": "1784000000",
      "recipientId": "17841400000000000",
      "text": "Hi! Is this still available?",
      "status": "delivered",
      "errorCode": null,
      "errorMessage": null,
      "createdAt": "2026-07-02T09:30:00Z"
    }
  ],
  "cursor": "eyJz..."
}

Field	Type	Description
items	array	List of messages. See Message Object.
cursor	string	Cursor for the next page. Absent when there are no more messages.

---

Get Message

Endpoint

URL: /messages/:messageId

Method: GET

Description

Fetches a single message by its Blotato ID. Poll this after Send Message to check whether an outgoing message reached sent or failed.

Path Parameters

Field	Type	Required	Description
messageId	string	Yes	Blotato ID of the message.

Response

Status Code: 200 OK

Returns a Message Object.

---

Send Message

Endpoint

URL: /messages

Method: POST

Description

Sends a direct message to one recipient. Blotato queues the message and sends it in the background, so the response returns status queued. Poll Get Message with the returned id to confirm the message reached sent or failed.

Send to a recipientId taken from an existing conversation or an incoming message. The social platform limits who you can message and when. See Messaging Windows.

Request Body

{
  "accountId": "98434",
  "recipientId": "1784000000",
  "text": "Thanks for reaching out! Yes, it's available.",
  "target": {
    "targetType": "instagram"
  }
}

Field	Type	Required	Description
accountId	string	Yes	Blotato ID of the connected account the message is sent from.
recipientId	string	Yes	Social platform (e.g. Instagram) ID of the recipient. Get it from an existing conversation or incoming message.
text	string	Yes	Plain-text message body. Instagram messages are limited to 1000 bytes, Facebook to 2000 characters. With buttons attached, the limit drops to 640 characters. See Buttons and Quick Replies.
target	object	Yes	Where and how to send. See Target.

Target

Field	Type	Required	Description
targetType	string	Yes	Value: instagram or facebook.
pageId	string	For Facebook	ID of the Facebook Page to send from, from subaccounts. Required when targetType is facebook.
commentId	string	No	Blotato comment ID. When set, Blotato delivers the message as a private reply to that comment instead of a direct message.
attachment	object	No	Up to 3 call-to-action buttons pinned under the message. See Buttons and Quick Replies.
quickReplies	array	No	Up to 13 tappable reply chips shown under the message. See Buttons and Quick Replies.
responseType	string	No	How the message fits the platform's messaging window: RESPONSE, UPDATE, or MESSAGE_TAG. Default RESPONSE. See Messaging Windows.
tag	string	No	Required when responseType is MESSAGE_TAG (e.g. HUMAN_AGENT).

Buttons and Quick Replies

Facebook and Instagram support buttons and quick replies in direct messages. Set target.attachment for buttons, or target.quickReplies for chips. The two are mutually exclusive: a request carrying both is rejected with 422.

For any platform-applied limitations, see:

• Instagram Limitations

• Facebook Limitations

Buttons

Buttons sit under the message and stay there. Up to 3 buttons are supported.

Instagram Limitation: Instagram only renders buttons in the Instagram mobile app. A recipient reading the conversation on instagram.com in a desktop browser sees the message text with no buttons.

Send an attachment or a URL inside text, not both. A message carrying both leaves the URL in text unclickable on desktop, so a desktop recipient ends up with no working link. For a primarily desktop audience, drop the attachment and put the URL in text.

{
  "accountId": "98434",
  "recipientId": "1784000000",
  "text": "Thanks for reaching out! Pick an option below.",
  "target": {
    "targetType": "instagram",
    "attachment": {
      "type": "button",
      "buttons": [
        { "type": "web_url", "title": "View pricing", "url": "https://example.com/pricing" },
        { "type": "postback", "title": "Talk to sales", "payload": "SALES" }
      ]
    }
  }
}

Field	Type	Required	Description
type	string	Yes	Value: button.
buttons	array	Yes	1 to 3 buttons.

Each button has:

Field	Type	Required	Description
type	string	Yes	web_url opens a link. postback reports the tap back to you.
title	string	Yes	Button label, 1 to 20 characters.
url	string	For web_url	Link the button opens. Starts with https://.
payload	string	For postback	Value echoed back on tap, 1 to 1000 characters.

With buttons set, text is required and limited to 640 characters.

Quick Replies

Quick replies are tappable chips offered as canned answers. They disappear once the person taps one or types their own message. Pass 1 to 13.

{
  "accountId": "98434",
  "recipientId": "1784000000",
  "text": "What size do you need?",
  "target": {
    "targetType": "instagram",
    "quickReplies": [
      { "title": "Small", "payload": "SIZE_S" },
      { "title": "Medium", "payload": "SIZE_M" },
      { "title": "Large", "payload": "SIZE_L" }
    ]
  }
}

Field	Type	Required	Description
title	string	Yes	Chip label, 1 to 20 characters.
payload	string	Yes	Value echoed back on tap, 1 to 1000 characters.

Quick replies require non-empty message text.

Reading a Tap

A quick-reply tap and a postback tap both arrive as the next incoming message carrying payload.selection, but they reach you differently.

Quick replies send a real text message. text holds the chip label, adn Blotato attaches payload.selection alongside it.

{
  "id": "msg_def456",
  "direction": "incoming",
  "text": "Your chip label",
  "payload": {
    "selection": { "type": "quick-reply", "payload": "The chip payload" }
  }
}

Postbacks do not send a text message. Blotato records the tap as an incoming message, sets text to the button label, and attaches payload.selection.

{
  "id": "msg_ghi789",
  "direction": "incoming",
  "text": "Your button label",
  "payload": {
    "selection": { "type": "postback", "payload": "SALES" }
  }
}

Field	Value	Meaning
selection.type	quick-reply	The person tapped a chip. text is the chip label.
selection.type	postback	The person tapped a button you attached. text is the button label.
selection.payload	string or null	The payload received with the tap. A postback is null when the platform webhook supplies no payload. Creating a postback button through this API requires a payload of 1–1000 characters.

Branch on selection.payload, not on text. Two chips that share a label are distinguishable only by their payload.

A web_url button produces no selection. The link opens and nothing comes back.

Blotato subscribes your account to the postback webhook when you connect it. If you connected your account before buttons were launched, reconnect to start receiving postback events. Quick-reply taps need no reconnect.

Response

Status Code: 201 Created

Returns a Message Object with status queued.

Errors

Send Message returns 201 on success, 422 when the request is rejected, and 429 when you exceed 30 requests per minute.

Messaging is available on every plan, so there is no "not enabled" rejection, and this endpoint does not return 404. A connected account that is missing or expired surfaces after the message is queued, as a failed message.

A 422 means one of:

• The message exceeds the platform's character limit. Instagram allows 1000 bytes, Facebook 2000 characters, and either drops to 640 characters when buttons are set.

• You passed both attachment and quickReplies. Send one or the other.

• You set buttons or quick replies without message text.

• The messaging window has closed.

• The comment you are replying to is invalid, or it already received a private reply.

• You reached your monthly active-contacts limit (error code 20101).

• responseType is MESSAGE_TAG and you did not set tag.

Message-send failures that happen after the message is queued do not return an error here. The message reaches status failed with an errorCode and errorMessage. See Messaging Errors.

---

Messaging Windows

The social platform limits who you can message and when. You reply to people who already have a conversation with you, not arbitrary users.

• Standard window: send a RESPONSE within 24 hours of the contact's last message.

• Private reply to a comment: set commentId on the target to reply once, within 7 days of the comment.

• Outside the window: set responseType to MESSAGE_TAG with an approved tag (e.g. HUMAN_AGENT) to send a permitted follow-up.

These windows come from the social platform, not Blotato. A message sent outside an allowed window reaches status failed.

Sending a message to a new person also counts toward your monthly active-contacts limit. See Active Contacts.

---

Conversation Object

Field	Type	Description
id	string	Blotato conversation ID.
accountId	string	ID of the connected account this conversation belongs to.
platform	string	instagram or facebook.
participants	array	The other people in the conversation. Each has id, name, username, and profileImageUrl, any of which may be null.
createdAt	string	ISO 8601 timestamp when the conversation started.
updatedAt	string	ISO 8601 timestamp of the most recent activity.

---

Message Object

Field	Type	Description
id	string	Blotato message ID.
conversationId	string or null	Blotato ID of the parent conversation.
platform	string	instagram or facebook.
direction	string	incoming for messages you receive, outgoing for messages you send.
senderId	string or null	Social platform (e.g. Instagram) ID of the sender.
recipientId	string	Social platform (e.g. Instagram) ID of the recipient.
text	string	Message text.
payload	object or null	Rich content on the message. See Payload.
status	string	Message status. See Status Values.
errorCode	integer or null	Set only when status is failed. See Messaging Errors.
errorMessage	string or null	Set only when status is failed.
createdAt	string	ISO 8601 timestamp when the message was created.

Payload

payload is null on a plain-text message. Otherwise it holds one or more of:

Field	Type	Description
attachment	object	Buttons you attached to an outgoing message. See Buttons.
quickReplies	array	Quick-reply chips you attached to an outgoing message. See Quick Replies.
selection	object	Set on an incoming message where the person tapped a postback button or a quick reply. Holds type (postback or quick-reply) and your payload string. See Reading a Tap.

Status Values

An outgoing message you send moves through queued, processing, then sent, or failed if it does not go through. An incoming message you receive shows as delivered.

Status	Meaning
queued	Accepted and waiting to send.
processing	Sending to the social platform.
sent	Handed to the social platform.
delivered	An incoming message delivered to you.
failed	Did not send. See errorMessage.

Rate Limits

Endpoint	Limit
GET /conversations	60 / min
GET /conversations/:conversationId	60 / min
GET /messages	60 / min
GET /messages/:messageId	60 / min
POST /messages	30 / min