Skip to main content

Direct Messages: all platforms

Upload-Post uses the same two endpoints to send and read private messages on every network. You choose the network with platform; the rest of the request is the same shape everywhere, with a few extra fields that only some networks understand.

Platformplatform valueConnected account it usesDetails
InstagraminstagramThe profile's Instagram professional accountInstagram DMs
WhatsAppwhatsappThe profile's WhatsApp Business number (how to connect)WhatsApp Messages
Facebook MessengerfacebookThe profile's Facebook Page (limited rollout)Messenger Messages
BlueskyblueskyThe profile's Bluesky account (app password with DM access)Bluesky DMs
TelegramtelegramThe profile's own Telegram botTelegram DMs

Send a message​

POST https://api.upload-post.com/api/uploadposts/dms/send
Authorization: Apikey YOUR_API_KEY
Content-Type: application/json

Common fields​

NameTypeRequiredDescription
platformStringYesinstagram, whatsapp, facebook, bluesky or telegram.
userStringYesUpload-Post profile that has the account connected.
recipient_idStringYes (see Bluesky)Who receives it. The format depends on the network: see Who you can message.
messageStringYes, unless you send media, a template or an actionThe text.
attachments / attachmentObject or arrayNoMedia: {type, url} (a public https:// URL) or a media id the network already has. Types and limits vary: see each platform's page.
reply_toStringNoId of a message in the chat to reply to it.
sender_actionStringNoTyping indicator, mark as read, reactions… Sent alone, it never counts towards the daily DM limit. Values per network on each page.

Examples​

The same text to a person on three networks:

# Instagram: recipient_id is the person's Instagram-scoped id
curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H "Authorization: Apikey YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"platform": "instagram", "user": "my_profile", "recipient_id": "17841400000000000", "message": "Thanks for your message!"}'

# WhatsApp: recipient_id is the phone number with country code
curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H "Authorization: Apikey YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"platform": "whatsapp", "user": "my_profile", "recipient_id": "+34600111222", "message": "Thanks for your message!"}'

# Bluesky: recipient_id is a handle or DID
curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H "Authorization: Apikey YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"platform": "bluesky", "user": "my_profile", "recipient_id": "alice.bsky.social", "message": "Thanks for your message!"}'

Outside WhatsApp's 24-hour window, send an approved template instead of text:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H "Authorization: Apikey YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"platform": "whatsapp", "user": "my_profile", "recipient_id": "+34600111222",
"template": {"name": "order_update", "language": "en_US"}}'

Who you can message​

None of these networks let a business message anyone out of the blue. In practice you answer people who wrote to you first; take their id from Get conversations or from the dm_received webhook.

Platformrecipient_idCan you write first?Time to answer
InstagramInstagram-scoped user id (IGSID)No24 hours after their last message
WhatsAppPhone number in international format (+34600111222)Yes, with an approved templateFree text for 24 hours after their last message; after that, templates only
MessengerPage-scoped user id (PSID)No24 hours; up to 7 days with tag: "HUMAN_AGENT"; approved utility templates after that
BlueskyHandle (alice.bsky.social) or DID; or conversation_id insteadYes, if their chat settings allow messages from youNo window
TelegramNumeric chat id of the personNo: they must start your bot firstNo window

A message outside the window is refused before it reaches the network, with a code that says what to do (for example whatsapp_template_required).


What each network accepts​

FeatureInstagramWhatsAppMessengerBlueskyTelegram
Text (max length)✓ (1000 bytes)✓ (4096)✓ (2000)✓ (1000)✓ (4096)
Images, video, audio, files✓✓✓– (shares posts only)✓ (also stickers, voice, video notes)
Link or reply buttonsbuttons (links)buttons (replies), list, cta_urlbuttons–buttons (inline keyboard)
Quick replies✓– (use buttons)✓––
Templatesgeneric_template (cards)template (Meta-approved)template (utility)––
Reply to a message✓✓✓✓✓
Reactions✓✓–✓✓
Typing / mark as read✓✓✓mark as readtyping and other chat actions
Location, contact cards–✓–––

The exact field names, limits and examples are on each platform's page (links in the first table).


Read conversations​

GET https://api.upload-post.com/api/uploadposts/dms/conversations?platform=whatsapp&user=my_profile
Authorization: Apikey YOUR_API_KEY

Returns the conversations of the connected account, newest first, each with its latest messages, in the same shape on every network. Useful filters: participant_id (one person), since (only recent activity), limit and cursor for paging.

  • Instagram, Messenger, Bluesky, Telegram: read from the network.
  • WhatsApp: WhatsApp has no API to read old chats, so Upload-Post serves the messages it received and sent since the number was connected.

To get new messages as they arrive instead of polling, subscribe to the dm_received webhook.


Media​

  • GET /api/uploadposts/dms/media: download a file someone sent you (WhatsApp and Messenger give only an id; Upload-Post fetches it for you).
  • POST /api/uploadposts/dms/media: upload a file once and reuse its id in several messages (WhatsApp, Messenger).

Details on the WhatsApp and Messenger pages.


Limits and common errors​

  • Daily DM limit per plan. Each sent message counts once; typing, mark-as-read and reactions don't. Over the limit you get 429 with daily_dm_limit and the reset time. See Instagram DMs.
  • 400: a required field is missing, the field is not supported on that network, or the message is outside its window.
  • 401 with a *_reauth_required code: the connection expired or was removed; reconnect the account from the dashboard.
  • 403 messenger_not_enabled: Messenger is not enabled on the account (limited rollout).
  • 403 bluesky_dm_scope_missing: the Bluesky app password was created without DM access.

All codes: Error codes.

Automate replies​

AutoDMs send a DM automatically when someone comments with a keyword or messages you (Instagram).