Direct Messages

Send direct messages (DMs) and retrieve conversations on connected social media accounts.

---

Send a Direct Message

Send a DM directly to a user using their platform-specific User ID.

Endpoint

POST /api/uploadposts/dms/send

Headers

Name	Value	Description
Authorization	Apikey your-api-key-here	Your API key for authentication

Body Parameters (JSON)

Name	Type	Required	Description
platform	String	Yes	The platform to send the DM on (e.g., "instagram").
user	String	Yes	Profile username (as configured in Upload-Post).
recipient_id	String	Yes	The platform-specific User ID of the recipient.
message	String	Yes	The text message to send.
buttons	Array	No	Up to 3 web_url buttons rendered in the Instagram DM. Each item is an object {title, url} (title max 20 chars, url must be http/https).
attachments / attachment	Object or array	No	{type, url} or {type, attachment_id}. Up to 10 images. Types: image, video, audio, file, like_heart, media_share.
quick_replies	Array	No	Up to 13 options; title max 20 characters.
generic_template	Object	No	Up to 10 elements; title max 80 characters; 3 buttons.
reply_to	String	No	Message id (mid) to reply to.
sender_action	String	No	typing_on, typing_off, mark_seen, react, unreact. Does not consume the daily DM quota.

Example Request

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
  -H 'Authorization: Apikey your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "instagram",
    "user": "my-profile",
    "recipient_id": "17841400123456789",
    "message": "Hello! Thanks for reaching out.",
    "buttons": [
      { "title": "Visit site", "url": "https://example.com" }
    ]
  }'

Responses

• 200 OK (DM sent successfully)

{
  "success": true,
  "recipient_id": "17841400123456789",
  "message_id": "aWdGM...",
  "message": "DM sent successfully"
}

• 400 Bad Request (missing fields, invalid account)

{
  "success": false,
  "error": "Missing required fields: platform, user, recipient_id, message"
}

• 429 Too Many Requests (daily DM limit exceeded)

{
  "success": false,
  "error": "Daily DM limit exceeded."
}

• 500 Internal Server Error

{
  "success": false,
  "error": "An internal server error occurred."
}

---

Get Conversations

Retrieve the list of DM conversations for an account, including participants and recent messages.

Endpoint

GET /api/uploadposts/dms/conversations

Headers

Name	Value	Description
Authorization	Apikey your-api-key-here	Your API key for authentication

Query Parameters

Name	Type	Required	Description
platform	String	Yes	The platform to retrieve conversations from (e.g., "instagram").
user	String	Yes	Profile username (as configured in Upload-Post).

Example Request

curl 'https://api.upload-post.com/api/uploadposts/dms/conversations?platform=instagram&user=my-profile' \
  -H 'Authorization: Apikey your-api-key-here'

Responses

• 200 OK

{
  "success": true,
  "conversations": [
    {
      "id": "t_123456789",
      "participants": {
        "data": [
          { "id": "17841400123456789", "username": "user_one" },
          { "id": "17841400987654321", "username": "user_two" }
        ]
      },
      "messages": {
        "data": [
          {
            "id": "aWdGM...",
            "created_time": "2025-01-15T10:30:00+0000",
            "from": { "id": "17841400123456789", "username": "user_one" },
            "to": { "data": [{ "id": "17841400987654321", "username": "user_two" }] },
            "message": "Hey, thanks for the info!"
          }
        ]
      }
    }
  ]
}

• 400 Bad Request

{
  "success": false,
  "error": "Missing required query parameters: platform, user"
}

• 500 Internal Server Error

{
  "success": false,
  "error": "An internal server error occurred."
}

---

Important Notes

1. Messaging policies vary by platform: Each platform has its own messaging rules. For example, Instagram requires the recipient to have messaged your account first (24-hour window).

2. Daily DM limits: Upload-Post enforces a configurable daily DM limit per user to prevent accidental overuse. When the limit is reached, the API returns a 429 status code.

Where to find the recipient ID

The recipient's User ID can be obtained from:

• The Get Conversations endpoint above (each participant has an id field).
• The Get Post Comments endpoint (GET /api/uploadposts/comments) where each comment includes the commenter's user.id.

Difference from Comment Replies

Feature	Comment Reply (/comments/reply)	Direct Message (/dms/send)
Recipient	comment_id — replies to a specific comment	recipient_id — sends to a user by ID
Use case	Auto-reply to post engagement	Customer support, follow-up conversations