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.
| Field | Type | Required | Constraints / Description |
|---|---|---|---|
| platform | string | true | "instagram" | "twitter" |
| accountId | string | true | Integration ID. |
| recipientId | string | true | Platform ID of the recipient. |
| text | string | true | Message text. Length: 1 <= length |
Exact documented request contract for POST {{API_BASE_URL}}/v1/messages/
| Status | Content Type | Response Fields |
|---|---|---|
| 200 | application/json | success: boolean, messageId: string |
| 400 | application/json | success: boolean, message: string |
| 402 | application/json | success: boolean, message: string |
| 403 | application/json | success: boolean, message: string |
| 404 | application/json | success: boolean, message: string |
| 502 | application/json | success: boolean, message: string |
Documented statuses and preserved response shapes; trigger meanings are not specified in the source and are not invented here.
| Platform | Prerequisite | Recipient Identifier | Documented Credit Cost |
|---|---|---|---|
| 24-hour window; instagram_business_manage_messages | Platform ID of the recipient | 1 credit | |
| dm.write scope | Recipient user id | 5 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.
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"
}'{
"success": true,
"messageId": "string"
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.platform | string | __1 | Yes | kind: schemaValueIn; value: "instagram" | "twitter" | |
| body#1 | body.accountId | string | __2 | Yes | Integration ID. | |
| body#1 | body.recipientId | string | __3 | Yes | Platform ID of the recipient. | |
| body#1 | body.text | string | __4 | Yes | Message text. | kind: schemaLength; value: 1 <= length |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.messageId | string | __2 | Yes | ID of the sent message. | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |