Inbox

Read and reply to Instagram and Facebook DMs, comments, and mentions, plus LinkedIn company-page comments and mentions (LinkedIn has no API DMs). Reads require the inbox:read scope; replies and marking read require inbox:write.

GET

/inbox/conversations

Returns one entry per conversation (the latest message in each), across Instagram and Facebook DMs, comments, and mentions, plus LinkedIn company-page comments and mentions (LinkedIn has no DMs via API). Cursor-paginated: follow pagination.next_cursor until it is null. Requires the inbox:read scope (API keys) or the access_social_inbox permission (OAuth/MCP).

limit

integer · max: 100

Max conversations per page (1-100, default 25).

Default: 25

cursor

string

Opaque pagination cursor from a previous response.

platform

string · enum

Filter to a single platform.

Enum values:

instagram

facebook

type

string · enum

Filter to a single conversation type.

Enum values:

comment

mention

unread

boolean

When true, only conversations with unread incoming messages.

200

A page of conversations

InboxConversation[]

InboxCursorPagination

GET/inbox/conversations

curl /inbox/conversations \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "conversation_id": "conversation_id",
      "platform": "instagram",
      "type": "dm",
      "participant": {
        "id": "id",
        "name": "name",
        "username": "username",
        "profile_picture": "profile_picture"
      },
      "unread_count": 0,
      "last_message": {
        "id": "id",
        "direction": "incoming",
        "text": "text",
        "timestamp": "2024-08-25T15:00:00Z",
        "is_read": true
      },
      "post": {
        "id": "id",
        "caption": "caption",
        "thumbnail": "thumbnail"
      }
    }
  ],
  "pagination": {
    "next_cursor": "next_cursor",
    "has_more": true,
    "limit": 0
  }
}

json

application/json

Get the full message history of a conversation

GET

/inbox/conversations/{conversationId}/messages

Returns messages in a conversation, oldest first, cursor-paginated. Requires the inbox:read scope (API keys) or the access_social_inbox permission (OAuth/MCP).

Get the full message history of a conversation › path Parameters

conversationId

string · required

Get the full message history of a conversation › query Parameters

limit

integer · max: 100

Default: 50

cursor

string

Get the full message history of a conversation › Responses

A page of messages

InboxMessage[]

InboxCursorPagination

GET/inbox/conversations/{conversationId}/messages

curl /inbox/conversations/:conversationId/messages \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "id",
      "conversation_id": "conversation_id",
      "platform": "platform",
      "type": "dm",
      "direction": "incoming",
      "text": "text",
      "timestamp": "2024-08-25T15:00:00Z",
      "is_read": true,
      "is_replied": true,
      "reaction": "reaction",
      "parent_comment_id": "parent_comment_id",
      "sender": {
        "id": "id",
        "name": "name",
        "username": "username",
        "profile_picture": "profile_picture"
      },
      "post": {
        "id": "id",
        "caption": "caption",
        "thumbnail": "thumbnail"
      }
    }
  ],
  "pagination": {
    "next_cursor": "next_cursor",
    "has_more": true,
    "limit": 0
  }
}

json

application/json

Mark all incoming messages in a conversation as read

POST

/inbox/conversations/{conversationId}/read

Marks every unread incoming message in the conversation as read and returns how many were updated. Requires the inbox:write scope (API keys) or the access_social_inbox permission (OAuth/MCP).

Mark all incoming messages in a conversation as read › path Parameters

conversationId

string · required

Mark all incoming messages in a conversation as read › Responses

Read state updated

conversation_id

string

marked_read

integer

Reply to a conversation

POST

/inbox/conversations/{conversationId}/reply

Sends a reply in an existing conversation (DM, comment, or mention) on Instagram, Facebook, or LinkedIn. You can only reply to conversations that already exist in your inbox — the API cannot start new conversations (Instagram requires the user to message first, and cold outreach violates Meta policy). Direct-message replies must be within the platform's messaging window (24 hours since the user's last message); replies outside the window are rejected. Each workspace can send up to 1,000 replies per rolling 24 hours (429 reply_limit_reached beyond that) — contact [email protected] if you need a higher limit. Requires the inbox:write scope (API keys) or the access_social_inbox permission (OAuth/MCP).

Reply to a conversation › path Parameters

conversationId

string · required

Reply to a conversation › Request Body

text

string · maxLength: 2000 · required

Reply body

attachment_url

string

Optional media URL (Facebook DMs only)

attachment_type

string · enum

Required if attachment_url is set

Enum values:

image

video

audio

file

Reply to a conversation › Responses

Reply sent

InboxMessage

POST/inbox/conversations/{conversationId}/reply

curl /inbox/conversations/:conversationId/reply \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "text": "text",
  "attachment_url": "attachment_url",
  "attachment_type": "image"
}'

Example Request Body

{
  "text": "text",
  "attachment_url": "attachment_url",
  "attachment_type": "image"
}

json

Example Responses

{
  "data": {
    "id": "id",
    "conversation_id": "conversation_id",
    "platform": "platform",
    "type": "dm",
    "direction": "incoming",
    "text": "text",
    "timestamp": "2024-08-25T15:00:00Z",
    "is_read": true,
    "is_replied": true,
    "reaction": "reaction",
    "parent_comment_id": "parent_comment_id",
    "sender": {
      "id": "id",
      "name": "name",
      "username": "username",
      "profile_picture": "profile_picture"
    },
    "post": {
      "id": "id",
      "caption": "caption",
      "thumbnail": "thumbnail"
    }
  }
}

json

application/json

Audio

List social inbox conversations (newest activity first)

GET

/inbox/conversations

limit

integer · max: 100

Max conversations per page (1-100, default 25).

Default: 25

cursor

string

Opaque pagination cursor from a previous response.

platform

string · enum

Filter to a single platform.

Enum values:

instagram

facebook

type

string · enum

Filter to a single conversation type.

Enum values:

comment

mention

unread

boolean

When true, only conversations with unread incoming messages.

200

A page of conversations

InboxConversation[]

InboxCursorPagination

Get the full message history of a conversation

GET

/inbox/conversations/{conversationId}/messages

Returns messages in a conversation, oldest first, cursor-paginated. Requires the inbox:read scope (API keys) or the access_social_inbox permission (OAuth/MCP).

Get the full message history of a conversation › path Parameters

conversationId

string · required

Get the full message history of a conversation › query Parameters

limit

integer · max: 100

Default: 50

cursor

string

Get the full message history of a conversation › Responses

A page of messages

InboxMessage[]

InboxCursorPagination

Mark all incoming messages in a conversation as read

POST

/inbox/conversations/{conversationId}/read

Marks every unread incoming message in the conversation as read and returns how many were updated. Requires the inbox:write scope (API keys) or the access_social_inbox permission (OAuth/MCP).

Mark all incoming messages in a conversation as read › path Parameters

conversationId

string · required

Mark all incoming messages in a conversation as read › Responses

Read state updated

conversation_id

string

marked_read

integer

Reply to a conversation

POST

/inbox/conversations/{conversationId}/reply

Reply to a conversation › path Parameters

conversationId

string · required

Reply to a conversation › Request Body

text

string · maxLength: 2000 · required

Reply body

attachment_url

string

Optional media URL (Facebook DMs only)

attachment_type

string · enum

Required if attachment_url is set

Enum values:

image

video

audio

file

Reply to a conversation › Responses

Reply sent

InboxMessage

Inbox

List social inbox conversations (newest activity first)

List social inbox conversations (newest activity first) › query Parameters

List social inbox conversations (newest activity first) › Responses

Get the full message history of a conversation

Get the full message history of a conversation › path Parameters

Get the full message history of a conversation › query Parameters

Get the full message history of a conversation › Responses

Mark all incoming messages in a conversation as read

Mark all incoming messages in a conversation as read › path Parameters

Mark all incoming messages in a conversation as read › Responses

Reply to a conversation

Reply to a conversation › path Parameters

Reply to a conversation › Request Body

Reply to a conversation › Responses

Inbox

List social inbox conversations (newest activity first)

List social inbox conversations (newest activity first) › query Parameters

List social inbox conversations (newest activity first) › Responses

Get the full message history of a conversation

Get the full message history of a conversation › path Parameters

Get the full message history of a conversation › query Parameters

Get the full message history of a conversation › Responses

Mark all incoming messages in a conversation as read

Mark all incoming messages in a conversation as read › path Parameters

Mark all incoming messages in a conversation as read › Responses

Reply to a conversation

Reply to a conversation › path Parameters

Reply to a conversation › Request Body

Reply to a conversation › Responses