Skip to content
reelspanDocs

Engage

Direct messages

Read a connected account's direct message conversations and send messages, with link buttons, attachments and quick replies where the network has them.

POSTapi.reelspan.com/v1/dms/sendTry it →

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"
{
  "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. limit is 1 to 50 conversations (default 20) and messages_limit 1 to 25 messages each (default 10).
  • participant_id returns only the conversation with that person. Pass pagination.next_cursor as cursor for the next page.
  • Every network returns the same shape: id, updated_at, participants (an id and username each) and messages, each with id, created_at, from, text and any attachments (type and url). A message whose from.id is 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" }]
  }'
{ "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_messages and pages_messaging permissions.
  • X needs the x_dms permission, 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.
POSTapi.reelspan.com/v1/dms/sendTry it →

Request body

application/json

  • platformstringrequired

    The network

  • userstring

    Profile username (also profile_username)

  • profile_usernamestring
  • recipient_idstringrequired

    Instagram/Facebook: the scoped user id (from a conversation or webhook); X: the user id; Bluesky: handle or DID; Mastodon: @user@server

  • messagestringrequired
  • buttonsobject[]

    Instagram, Facebook: link buttons; elsewhere added as links

    • titlestringrequired
    • urlstringrequired
  • attachmentsobject[]
    • typestringrequired

      imagevideoaudiofile

    • urlstringrequired
  • quick_repliesobject[]
    • titlestringrequired
    • payloadstring
  • reply_tostring

Responses

200 Sent

{
  "success": true,
  "platform": "string",
  "recipient_id": "string",
  "message_id": "string"
}

400 Invalid input, or the network can’t do this (`platform_not_supported`, `action_not_supported`)

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

403 The connected account hasn’t granted a permission this needs: reconnect it and allow it

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}
GETapi.reelspan.com/v1/dms/conversationsTry it →

Parameters

  • platformstring · queryrequired

    The network

  • userstring · query

    Profile username (also profile_username)

  • profile_usernamestring · query
  • limitinteger · query
  • cursorstring · query
  • participant_idstring · query

    Only the conversation with this person

  • messages_limitinteger · query

Responses

200 Conversations

{
  "success": true,
  "platform": "string",
  "conversations": [
    {}
  ],
  "pagination": {
    "next_cursor": "string",
    "has_more": true
  }
}

400 Invalid input, or the network can’t do this (`platform_not_supported`, `action_not_supported`)

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

403 The connected account hasn’t granted a permission this needs: reconnect it and allow it

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

Something unclear or missing? Write to [email protected] and we’ll fix the page.