Skip to content

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.

Send a DM reply request
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."
  }'
Illustrative request
Example line 1

curl -X POST "{{API_BASE_URL}}/v1/messages/" \

Illustrative request
Example line 2

-H "x-access-key: YOUR_ACCESS_KEY" \

Illustrative request
Example line 3

-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.

Send-reply field map
FieldRequiredness / valuePurpose
platformRequired; must be instagramIdentifies the platform for the send
accountIdRequiredIdentifies the connected Instagram account
recipientIdRequiredIdentifies the person receiving the reply
textRequiredMessage text to send
successResponse fieldIndicates the send result in the captured response
messageIdResponse fieldSent 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.

Messaging failure checks
CheckWhat to verifySource basis
Closed messaging windowSend attempted outside the limited window after the user's last message; API surfaces the failure clearlyPlatform messaging windows are platform rules
Missing fieldOne of platform, accountId, recipientId, or text is absentFour values are needed to send a message
Wrong platform valueplatform is not set to instagram for the current Messaging APIFAQ states platform must be instagram
Missing messageIdResponse does not return a messageId to track and reconcileResponse returns the sent message ID

No status codes, window durations, or error codes are stated in the source, so none are invented here.

Inbox build checklist
DecisionUse whenCollect before calling
List onlyYou need inbox ordering and participant displayConnected account; participant name, username, profile picture, most recent message, updated time
List plus historyYou need to render a full threadConversation identifier; sender and timestamp per message
Send onlyYou already have the recipient and connected accountplatform, accountId, recipientId, text; store returned messageId
Full inboxYou need a branded support inbox or CRM/help-desk wiringAll 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.

Send a DM reply response
{
  "success": true,
  "messageId": "MESSAGE_ID"
}