Manage messages

Find the existing conversation and recipient, send an authorized message, and verify its final status.

Blotato's messaging API and MCP tools support Instagram and Facebook. Replies are subject to the platform's messaging rules and windows.

Prompt for your assistant:

Find the conversation I specify, read its recent messages, and draft a reply. When I ask you to send it, use the existing recipient identifiers and verify the send status.

Find the recipient

1. Use an authenticated connection and confirm messaging permissions and the platform messaging window.

2. Call blotato_list_conversations, filtering by the intended account and platform. Select the conversation from items. Follow returned cursors until the requested conversation is found or the results end.

{"accountId": "98434", "platform": "instagram", "limit": 50}

1. Call blotato_list_messages with the selected conversation's id. Replace all example IDs with returned values.

{"conversationId": "cnv_abc123", "limit": 50}

1. Read direction before selecting the reply recipient. For an incoming message, the other participant is senderId. For an outgoing message, the other participant is recipientId. Use the conversation's accountId as the sending Blotato account. Do not invent a recipient ID from a username or send to the connected account itself.

Send an approved reply

For this Instagram example, assume the selected incoming message's senderId is 1784000000. After the user approves the reply, call blotato_send_message once:

{
  "accountId": "98434",
  "platform": "instagram",
  "recipientId": "1784000000",
  "text": "Thanks for asking. Registration closes on October 10."
}

For REST, send the following JSON to POST https://backend.blotato.com/v2/messages with blotato-api-key: YOUR_API_KEY and Content-Type: application/json. REST uses target, not MCP's top-level platform.

{
  "accountId": "98434",
  "recipientId": "1784000000",
  "text": "Thanks for asking. Registration closes on October 10.",
  "target": {"targetType": "instagram"}
}

For Facebook, select the Page from account lookup and supply MCP pageId or REST target.pageId with the Facebook platform value. Do not reuse the Instagram target or select the first Page without matching the user's request.

REST lookups use GET /v2/conversations?accountId=ACCOUNT_ID&platform=instagram&limit=50 and GET /v2/messages?conversationId=CONVERSATION_ID&limit=50. Use the authentication header and URL-encode query values.

Verify the send

Save the returned message id. The initial queued state is not confirmation of delivery. Call blotato_get_message with:

{"messageId": "msg_abc123"}

For REST, read GET /v2/messages/RETURNED_MESSAGE_ID with the authentication header.

1. On outgoing sent, report the message as sent. This does not establish the recipient read it.

2. On failed, stop and preserve errorCode and errorMessage. Resolve permissions, messaging-window, recipient, or account errors before another attempt.

3. For queued or processing, read the same ID within a bounded client wait, such as 10-second intervals for up to 2 minutes. If still pending, report the saved ID and state. This budget is not a delivery promise.

4. After a send timeout, inspect the saved message or recent conversation messages. Do not resend while the first attempt's outcome remains uncertain.

For buttons, quick replies, and comment-to-DM behavior, read the Messages reference before choosing a message shape. For connection and history questions, see Inbox setup.