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.
| Platform | platform value | Connected account it uses | Details |
|---|---|---|---|
instagram | The profile's Instagram professional account | Instagram DMs | |
whatsapp | The profile's WhatsApp Business number (how to connect) | WhatsApp Messages | |
| Facebook Messenger | facebook | The profile's Facebook Page (limited rollout) | Messenger Messages |
| Bluesky | bluesky | The profile's Bluesky account (app password with DM access) | Bluesky DMs |
| Telegram | telegram | The profile's own Telegram bot | Telegram 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
| Name | Type | Required | Description |
|---|---|---|---|
| platform | String | Yes | instagram, whatsapp, facebook, bluesky or telegram. |
| user | String | Yes | Upload-Post profile that has the account connected. |
| recipient_id | String | Yes (see Bluesky) | Who receives it. The format depends on the network: see Who you can message. |
| message | String | Yes, unless you send media, a template or an action | The text. |
| attachments / attachment | Object or array | No | Media: {type, url} (a public https:// URL) or a media id the network already has. Types and limits vary: see each platform's page. |
| reply_to | String | No | Id of a message in the chat to reply to it. |
| sender_action | String | No | Typing 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.
| Platform | recipient_id | Can you write first? | Time to answer |
|---|---|---|---|
| Instagram-scoped user id (IGSID) | No | 24 hours after their last message | |
Phone number in international format (+34600111222) | Yes, with an approved template | Free text for 24 hours after their last message; after that, templates only | |
| Messenger | Page-scoped user id (PSID) | No | 24 hours; up to 7 days with tag: "HUMAN_AGENT"; approved utility templates after that |
| Bluesky | Handle (alice.bsky.social) or DID; or conversation_id instead | Yes, if their chat settings allow messages from you | No window |
| Telegram | Numeric chat id of the person | No: they must start your bot first | No 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
| Feature | Messenger | Bluesky | Telegram | ||
|---|---|---|---|---|---|
| Text (max length) | ✓ (1000 bytes) | ✓ (4096) | ✓ (2000) | ✓ (1000) | ✓ (4096) |
| Images, video, audio, files | ✓ | ✓ | ✓ | – (shares posts only) | ✓ (also stickers, voice, video notes) |
| Link or reply buttons | buttons (links) | buttons (replies), list, cta_url | buttons | – | buttons (inline keyboard) |
| Quick replies | ✓ | – (use buttons) | ✓ | – | – |
| Templates | generic_template (cards) | template (Meta-approved) | template (utility) | – | – |
| Reply to a message | ✓ | ✓ | ✓ | ✓ | ✓ |
| Reactions | ✓ | ✓ | – | ✓ | ✓ |
| Typing / mark as read | ✓ | ✓ | ✓ | mark as read | typing 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
429withdaily_dm_limitand 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.401with a*_reauth_requiredcode: 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).