Messages

Blotato allows you to read and send direct messages on your Instagram account. Twitter/X, TikTok, 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

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.

---

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. Value: instagram.
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. Value: instagram.
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.
target	object	Yes	Where and how to send. See Target.

Target

Field	Type	Required	Description
targetType	string	Yes	Value: instagram.
commentId	string	No	Blotato comment ID. When set, Blotato delivers the message as a private reply to that comment instead of a direct message.
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).

Response

Status Code: 201 Created

Returns a Message Object with status queued.

Errors

Status	Reason
404	The connected account was not found, or messaging is not enabled for your account.
422	The message exceeds the platform's character limit, the messaging window has closed, the comment you are replying to is invalid, your connected account expired, or you reached your plan's monthly active-contacts limit.
429	Rate limit exceeded (30 requests per minute).

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 plan's 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.
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.
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.
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.

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