Social Media Messaging API
A social media messaging API lets your product list conversations, read message history, and send replies without building each platform's messaging integration separately.
curl -X POST "{{API_BASE_URL}}/v1/messages/" \
-H "x-access-key: YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "instagram",
"accountId": "INTEGRATION_ID",
"recipientId": "RECIPIENT_ID",
"text": "An example comment."
}'curl -X POST "{{API_BASE_URL}}/v1/messages/" \
-H "x-access-key: YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
This guide covers the exact send-reply contract for Instagram DM replies, the inbox workflows around it, and the checks to run before you call the endpoint.
What a social media messaging API does and when to use it
A social media messaging API brings social conversations into your own product so you can respond to messages programmatically instead of switching between platform apps. A typical use case is an e-commerce or support product that answers product and order questions from social DMs inside its existing workflow. The reader task here is to evaluate and implement programmatic sending and management of social media DM replies, especially Instagram DM replies, through a unified messaging endpoint: list conversations, read history, send a reply with platform, accountId, recipientId, and text, track the returned messageId, and build an inbox or CRM workflow without building each platform's messaging integration.
Add messaging to your product in three steps
Getting started takes three moves. Obtain an API key through sign-up. Connect your product once so publishing, scheduling, analytics, comment handling, and messaging all run through a shared API. Then expose major social platforms to your users without your team constructing and upkeep-ing a separate connector for each network. Ahead of a call, gather the identifiers you will use: which connected account is sending, who should receive it, and the precise wording. The concrete request and response shapes appear in the Send a DM reply request and Send a DM reply response examples, with a field-by-field breakdown in the Send-reply field map table.
List Conversations and Read Message History
For inbox discovery, List Conversations returns threads belonging to a linked account, showing for each thread the other party's display name, handle, and avatar alongside the latest entry and its last-change time; move through results using cursor-based paging. For thread detail, Read Message History returns entries for a chosen thread in pages, each entry carrying who sent it and when, which lets your client assemble the complete exchange and present it in your preferred layout. This page describes those two flows in prose only, since their exact endpoint contracts are not reproduced here beyond the send contract. Consult the Inbox build checklist table to judge whether you need discovery, history, sending, or a complete inbox, and to confirm which identifiers to have ready before calling.
Send Replies
A single send operation delivers a reply to a chosen recipient. On success the API hands back an identifier for the dispatched message, which you should persist next to your internal thread and recipient records so delivery can be followed and later matched to your own records; if that identifier is absent, treat the attempt as unsuccessful until you have checked it. The call itself is a POST to the messages endpoint, authenticated with the x-access-key header and carrying a JSON payload with platform, accountId, recipientId, and text, exactly as illustrated in the Send a DM reply request example.
Build your own inbox
Because the same capabilities behind the hosted dashboard inbox are exposed via the API, you can present a support inbox under your own branding or feed DM activity into a CRM, help desk, or automation system you already run. A workable pattern: pull the thread list for the linked account, open the chosen thread's history, display each entry with its sender and time, and dispatch answers via the shared endpoint. Retain display name, handle, and avatar from the thread list for presentation, and use latest entry plus last-change time to order the inbox.
Platform messaging windows and failure handling
Some networks restrict outbound messages to a short period following the other party's most recent message. That restriction originates with the network itself rather than this API, and when it applies the API reports the rejection explicitly. Plan your checks around three situations: the send falls outside the permitted period, one of the four required inputs (platform, accountId, recipientId, text) is missing, or platform carries a value other than instagram as required by the current contract. The Messaging failure checks table lays these out. Do not assume a specific period length or error code, since neither is stated in the contract.
Instagram Messaging API and Twitter Messaging API scope
For Instagram, the Instagram Messaging API dispatches DM replies from linked Business and Creator accounts by supplying the recipient, the linked account, and the message wording in a single API call. For Twitter Messaging API, verify which platform value and account scope your implementation supports before designing the send flow, because the send contract on this page specifies platform as instagram. That verification prevents a Twitter/X inbox design from borrowing Instagram-specific values on assumption.
| Field | Requiredness / value | Purpose |
|---|---|---|
| platform | Required; must be instagram | Identifies the platform for the send |
| accountId | Required | Identifies the connected Instagram account |
| recipientId | Required | Identifies the person receiving the reply |
| text | Required | Message text to send |
| success | Response field | Indicates the send result in the captured response |
| messageId | Response field | Sent message ID returned for tracking and reconciliation |
Requiredness and values are as stated in the captured source: four values are needed, and platform must be set to instagram for the current Messaging API. No types beyond the source are invented.
| Check | What to verify | Source basis |
|---|---|---|
| Closed messaging window | Send attempted outside the limited window after the user's last message; API surfaces the failure clearly | Platform messaging windows are platform rules |
| Missing field | One of platform, accountId, recipientId, or text is absent | Four values are needed to send a message |
| Wrong platform value | platform is not set to instagram for the current Messaging API | FAQ states platform must be instagram |
| Missing messageId | Response does not return a messageId to track and reconcile | Response returns the sent message ID |
No status codes, window durations, or error codes are stated in the source, so none are invented here.
| Decision | Use when | Collect before calling |
|---|---|---|
| List only | You need inbox ordering and participant display | Connected account; participant name, username, profile picture, most recent message, updated time |
| List plus history | You need to render a full thread | Conversation identifier; sender and timestamp per message |
| Send only | You already have the recipient and connected account | platform, accountId, recipientId, text; store returned messageId |
| Full inbox | You need a branded support inbox or CRM/help-desk wiring | All of the above, plus cursor pagination for the inbox |
Decision aid derived from the source-stated list, history, send, and inbox workflows.
Frequently asked questions
What is a social media messaging API?
It is an interface that lets software read social conversations and answer them from inside another application. A shop, for instance, could deal with questions about products or orders arriving by DM without leaving its normal support workflow.
Can I send Instagram DM replies through the API?
Yes. You can dispatch Instagram DM replies from code with POST /v1/messages/. Supply the linked Instagram account, the recipient identifier, and the reply text, and the message goes out through that linked account.
What information do I need to send a message through the API?
Four inputs are required: platform, accountId, recipientId, and text. In the contract described here platform has to be instagram. accountId points to the linked Instagram account, and recipientId points to the person who should receive the reply.
Can I try Instagram messaging before integrating the API?
Yes. You can walk through an Instagram DM inbox directly first, then decide how to build that flow into your own application.
{
"success": true,
"messageId": "MESSAGE_ID"
}