Skip to content

Send Message API

The Send Message API lets you send a DM through POST {{API_BASE_URL}}/v1/messages/ by supplying the platform, accountId, recipientId and text fields. Use this operation when you need to send a message to a specific recipient on Instagram or Twitter/X, after confirming the platform prerequisites for the account you are sending from.

Send Message API overview

Send a message is the core operation on this page. The endpoint is POST {{API_BASE_URL}}/v1/messages/ with the trailing slash preserved exactly. The request sends a DM to one recipient identified by recipientId, using the integration identified by accountId, and the platform field selects Instagram or Twitter/X. Before sending, confirm that the selected account can send on the chosen platform and that the recipient identifier matches the platform ID format expected for that platform.

Authorization with x-access-key

Authorization uses the x-access-key header. Send the header named x-access-key with your token value on the request, as shown in the Send a message request example. Keep the token out of public examples and replace the placeholder with the actual credential supplied to your application.

Request field map

The request body is application/json and every field is required. The platform field is a string with the value "instagram" or "twitter". The accountId field is a string containing the integration ID. The recipientId field is a string containing the platform ID of the recipient. The text field is a string containing the message text and must satisfy the length constraint of 1 <= length. See the Request field map table for the complete field-by-field contract.

Platform prerequisites

Instagram sends are only available inside the 24-hour window and need the instagram_business_manage_messages permission. Check that the conversation is still inside that window before sending an Instagram reply, and confirm the permission is present on the connected account. Twitter/X requires the dm.write scope, and recipientId is the recipient user id. Confirm the dm.write scope is granted before sending on Twitter/X, and use the recipient user id rather than a handle or other identifier. The documented credit costs are 1 credit on Instagram and 5 credits on Twitter/X, preserved here as contract facts for planning. See the Platform prerequisites checklist table for a side-by-side summary.

Worked example and 200 response

The worked HTTP example in the Send a message request example shows the exact POST request with the x-access-key header and the four required body fields. A successful 200 response, shown in the 200 success response example, returns success as true and messageId as the string ID of the sent message. Keeping messageId alongside your own record of the send is a practical way to correlate the request with the returned identifier later.

Failure matrix for error responses

The documented error statuses are 400, 402, 403, 404 and 502, each returning success as a boolean and message as a string, as shown in the Error response shape example. The source does not specify distinct trigger meanings for these statuses beyond the codes and shapes, so do not assume a specific cause from the status alone. Check the request fields, authorization, account and recipient identifiers, and platform prerequisites, then inspect the message field in the response for the returned detail. See the Response and failure matrix table for the preserved response shape for each status.

Implementation notes

Keep the method and path exact, including the trailing slash on /v1/messages/, and use {{API_BASE_URL}} as the origin placeholder in examples. Validate platform, accountId, recipientId and text before sending, and verify the Instagram 24-hour window and instagram_business_manage_messages permission or the Twitter/X dm.write scope as applicable. This page is a staging specification for the documented contract, so confirm behavior against the implemented service before relying on it in production.

Request field map
FieldTypeRequiredConstraints / Description
platformstringtrue"instagram" | "twitter"
accountIdstringtrueIntegration ID.
recipientIdstringtruePlatform ID of the recipient.
textstringtrueMessage text. Length: 1 <= length

Exact documented request contract for POST {{API_BASE_URL}}/v1/messages/

Response and failure matrix
StatusContent TypeResponse Fields
200application/jsonsuccess: boolean, messageId: string
400application/jsonsuccess: boolean, message: string
402application/jsonsuccess: boolean, message: string
403application/jsonsuccess: boolean, message: string
404application/jsonsuccess: boolean, message: string
502application/jsonsuccess: boolean, message: string

Documented statuses and preserved response shapes; trigger meanings are not specified in the source and are not invented here.

Platform prerequisites checklist
PlatformPrerequisiteRecipient IdentifierDocumented Credit Cost
instagram24-hour window; instagram_business_manage_messagesPlatform ID of the recipient1 credit
twitterdm.write scopeRecipient user id5 credits

Source contract facts preserved without reinterpretation.

Frequently asked questions

What do I need to check before calling the Send Message API?

Send the x-access-key header with your token, set Content-Type to application/json, and include platform, accountId, recipientId and text in the request body. For Instagram, check the 24-hour window and instagram_business_manage_messages permission. For Twitter/X, check the dm.write scope and use the recipient user id as recipientId.

What fields are returned when a message is sent successfully?

A 200 response contains success as a boolean and messageId as a string identifying the sent message. The documented error statuses 400, 402, 403, 404 and 502 use a success boolean and a message string.

Which request fields are required and what values do they accept?

The platform field accepts "instagram" or "twitter". The accountId field is the integration ID, recipientId is the platform ID of the recipient, and text must have a length of at least 1.

Send a message request example
curl -X POST "{{API_BASE_URL}}/v1/messages/" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "platform": "instagram",
    "accountId": "string",
    "recipientId": "string",
    "text": "string"
  }'
200 success response example
{
  "success": true,
  "messageId": "string"
}
Error response shape example for 400, 402, 403, 404 and 502
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.platformstring__1Yeskind: schemaValueIn; value: "instagram" | "twitter"
body#1body.accountIdstring__2YesIntegration ID.
body#1body.recipientIdstring__3YesPlatform ID of the recipient.
body#1body.textstring__4YesMessage text.kind: schemaLength; value: 1 <= length
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.messageIdstring__2YesID of the sent message.
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes