Skip to content

Send Message API

The Send Message API sends a direct message reply on Instagram or Twitter/X. Use it with a connected Instagram Business or Creator account, or a connected Twitter/X account, by calling POST /v1/messages with the platform, accountId, recipientId, and text fields described below.

Send Message API overview and supported platforms

This endpoint sends a direct message reply using a recipientId taken from a conversation's participants. Authentication uses the x-access-key header, and the payload is sent as JSON. The complete request and response shapes are illustrated in the examples titled Send Message API request example, Send Message API request body example, and Send Message API response example, while the input contract is summarized in the table titled Request fields for POST /v1/messages.

Request: POST /v1/messages with headers and body

Call POST {{API_BASE_URL}}/v1/messages with the x-access-key header set to your access key and Content-Type: application/json. The body must contain platform, accountId, recipientId, and text. All four fields are required strings. The platform value must be instagram or twitter. The accountId is the integration ID returned by list_integrations. The recipientId identifies the other participant in the conversation. The text is the message text and must have a minimum length of 1. On success, the response contains success set to true and a messageId for the sent message.

Finding recipientId from conversation participants

Look at the participants listed for the conversation and pick the entry whose id differs from selfId; that entry supplies recipientId. This check prevents addressing your own account by mistake. For Twitter/X, recipientId should be the numeric user id belonging to the recipient. Verify the chosen participant before sending, since an incorrect identifier will direct the reply to the wrong person. Once the call succeeds, keep the returned messageId alongside the conversation details so you can trace the reply when reviewing history later.

Platform constraints and credit costs

On Instagram, Meta permits replies only during the 24 hours following the recipient's most recent message. Attempting a send after that period ends will be turned away by the platform. Twitter/X does not impose a comparable fixed deadline, yet delivery depends on the recipient's privacy choices: only people who allow incoming messages from you can be reached this way. Each attempt is charged differently depending on the network — Instagram sends consume 1 credit, whereas Twitter/X sends consume 5 credits, reflecting per-request DM billing that mirrors how X posts are billed. If a send fails, first confirm the Instagram timing, then the Twitter/X messaging permission, and finally that recipientId came from the correct participant.

Request fields for POST /v1/messages
FieldTypeRequiredDescription
platformstringYesinstagram or twitter
accountIdstringYesIntegration ID from list_integrations
recipientIdstringYesThe other participant's ID (from the conversation's participants)
textstringYesMessage text (min length 1)

Exact source field contract for POST /v1/messages

Platform constraints and credit costs
PlatformReply window / recipient conditionCredit cost per send
InstagramOnly within 24 hours of the recipient's last message; outside that window the send is rejected by the platform1 credit
Twitter/XNo fixed reply window; only accounts whose settings accept messages from you5 credits

Source-stated constraints; runtime rejection behavior not tested

Send Message API request example
POST {{API_BASE_URL}}/v1/messages
x-access-key: YOUR_ACCESS_KEY
Content-Type: application/json

{
	"platform": "instagram",
	"accountId": "6a8df8be8572dce3a2937c99",
	"recipientId": "17841400000000001",
	"text": "An example comment."
}
Send Message API response example
{
	"success": true,
	"messageId": "mid.aWdfbXNnXzEwMDA"
}
Contract example 1
POST /v1/messages
x-access-key: YOUR_ACCESS_KEY
Content-Type: application/json
Contract example 2
{
	"platform": "instagram",
	"accountId": "6a8df8be8572dce3a2937c99",
	"recipientId": "17841400000000001",
	"text": "An example comment."
}