Inbox

The unified inbox aggregates DMs, comments, mentions, and reviews from connected profiles into a single API.

List messages

curl "https://api.aetherhq.dev/v1/inbox?platform=instagram&type=dm&isRead=false" \
  -H "Authorization: Bearer $AETHER_API_KEY"

Query parameters:

Parameter	Description
`platform`	Filter by platform (`instagram`, `facebook`, etc.)
`type`	`dm`, `comment`, `mention`, or `review`
`isRead`	`true` or `false`
`profileId`	Filter by SocialProfile ID
`page`, `perPage`	Pagination

const messages = await client.inbox.list({
  platform: "instagram",
  type: "dm",
  isRead: false,
});

Reply to a message

POST /v1/inbox/{messageId}/reply routes by message type:

Type	Behavior
`comment`	Public comment reply on the post
`dm`, `story_reply`	Direct message via Meta Messaging API (Instagram/Facebook only)
`mention`, `review`	Not supported (`422 REPLY_UNSUPPORTED`)

For DMs and story replies, Aether uses the sender's platform user ID captured during webhook ingestion. Meta allows replies within 24 hours of the user's last message; older threads return 422 DM_OUTSIDE_24H_WINDOW.

curl -X POST https://api.aetherhq.dev/v1/inbox/{messageId}/reply \
  -H "Authorization: Bearer $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Thanks for your message!" }'

Mark as read

curl -X PATCH https://api.aetherhq.dev/v1/inbox/{messageId}/read \
  -H "Authorization: Bearer $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isRead": true }'

Private reply to a comment

Send a DM in response to a comment (Instagram/Facebook):

curl -X POST https://api.aetherhq.dev/v1/inbox/comments/{platformPostId}/{commentId}/private-reply \
  -H "Authorization: Bearer $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prof_ig123",
    "message": "Sent you the details in DM!"
  }'

With inline buttons (recommended for Instagram Message Requests — cold reach):

curl -X POST https://api.aetherhq.dev/v1/inbox/comments/{platformPostId}/{commentId}/private-reply \
  -H "Authorization: Bearer $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prof_ig123",
    "message": "Thanks for commenting! Tap below:",
    "buttons": [
      { "type": "url", "title": "Get link", "url": "https://example.com" }
    ]
  }'

When buttons are present, message must be 640 characters or fewer.

See Automations for keyword-triggered private replies.

Webhook events

inbox.message_received — new DM or inbox item
inbox.comment_received — new comment

See Inbox API.