Read a profile's direct message conversations and answer them, on Instagram, Facebook (Messenger, from a Page), X, Bluesky, Mastodon and Reddit. Reading needs a key with the read scope; sending needs publish.
List conversations
curl "https://api.reelspan.com/v1/dms/conversations?platform=instagram&user=my-brand" \
-H "Authorization: Bearer $REELSPAN_API_KEY"import { Reelspan } from 'reelspan';
const reelspan = new Reelspan();
const { conversations } = await reelspan.dms.conversations({ platform: 'instagram', user: 'my-brand' });from reelspan import Reelspan
reelspan = Reelspan()
conversations = reelspan.dms.conversations("instagram", "my-brand")["conversations"]{
"success": true,
"platform": "instagram",
"conversations": [
{
"id": "aWdfZAG06…",
"updated_at": "2026-12-01T09:14:51.000Z",
"participants": [{ "id": "17841400000000000", "username": "a_fan" }],
"messages": [
{ "id": "aWdfZAG1…", "created_at": "2026-12-01T09:14:51.000Z", "from": { "id": "17841400000000000", "username": "a_fan" }, "text": "Do you ship to Canada?", "attachments": [] }
]
}
],
"pagination": { "next_cursor": null, "has_more": false }
}- Newest first, each with its latest messages.
limitis 1 to 50 conversations (default 20) andmessages_limit1 to 25 messages each (default 10). participant_idreturns only the conversation with that person. Passpagination.next_cursorascursorfor the next page.- Every network returns the same shape:
id,updated_at,participants(anidandusernameeach) andmessages, each withid,created_at,from,textand anyattachments(typeandurl). A message whosefrom.idis the account's own was sent by you.
Send a message
curl -X POST https://api.reelspan.com/v1/dms/send \
-H "Authorization: Bearer $REELSPAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "instagram",
"user": "my-brand",
"recipient_id": "17841400000000000",
"message": "Yes, we ship to Canada in 3 to 5 days.",
"buttons": [{ "title": "Shipping", "url": "https://example.com/shipping" }]
}'await reelspan.dms.send({
platform: 'instagram',
user: 'my-brand',
recipientId: '17841400000000000',
message: 'Yes, we ship to Canada in 3 to 5 days.',
buttons: [{ title: 'Shipping', url: 'https://example.com/shipping' }],
});reelspan.dms.send("instagram", "my-brand", "17841400000000000", "Yes, we ship to Canada in 3 to 5 days.", buttons=[{"title": "Shipping", "url": "https://example.com/shipping"}]){ "success": true, "platform": "instagram", "recipient_id": "17841400000000000", "message_id": "aWdfZAG1…" }| Field | |
|---|---|
platform, user |
The network and the profile (also profile_username). |
recipient_id |
Who gets it. Instagram and Facebook: the id the conversation or the dm_received webhook gives (sender_id). X: the user id. Bluesky: a handle or DID. Mastodon: @user@server. |
message |
The text, up to 10,000 characters (the network may allow less). |
buttons |
Up to 3 link buttons, { "title", "url" }. Instagram and Facebook show them as buttons; elsewhere they are added as links. |
attachments |
Up to 10 `{ "type": "image" |
quick_replies |
Up to 13 { "title", "payload" } reply chips (Instagram, Facebook). |
reply_to |
A message id to reply to, where the network threads replies. |
Messages sent through the API show up in the dashboard's Messages page at once.
What each network needs
- Instagram and Facebook let a business answer only people who wrote to the account in the last 24 hours. They need the
instagram_manage_messagesandpages_messagingpermissions. - X needs the
x_dmspermission, and X bills direct messages per call. - Bluesky needs an app password made with direct message access when the account was connected.
An account connected before Reelspan asked for a permission gets 409 permission_reconnect: reconnect it and allow it. See Permissions. A network without direct messages in its API gets 400 platform_not_supported.
New messages
Subscribe to the dm_received webhook to hear about new Instagram and Facebook messages as Meta reports them, and to answer them with POST /v1/dms/send using the event's sender_id.
To answer comments with a message automatically, see AutoDM; to answer one comment, see private replies.
Errors
| Status | error_code |
When |
|---|---|---|
| 400 | platform_not_supported |
The network has no direct messages in its API. |
| 403 | The account hasn't granted a permission this needs. | |
| 404 | profile_platform_mapping_invalid |
The profile has no account on that network. |
| 409 | reauth_required, permission_reconnect |
Reconnect the account. |
| 502 | The network's code | The network refused, for example a message outside Instagram's 24-hour window. |