Inbox

Read and send Messenger DMs as a connected Facebook Page.

List Conversations

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.listInboxConversations({
  accountId: "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  limit: 50,
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "convos": [
    {
      "id": "t_987654321",
      "members": [
        {
          "id": "987654321",
          "username": null,
          "displayName": null
        }
      ],
      "muted": false,
      "unreadCount": 1,
      "lastMessage": {
        "id": "mid_abc123",
        "text": "Do you ship abroad?",
        "sentAt": "2026-09-08T12:00:00.000Z"
      }
    }
  ],
  "cursor": null
}

Newest first. A conversation id returned by create (a bare recipient id before the first message) reads as empty until someone writes in it. Media messages carry text: null plus an attachments entry (image, video, audio, file, or other with a direct URL).

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.listInboxMessages({
  convoId: "t_987654321",
  accountId: "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  limit: 50,
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "convoId": "t_987654321",
  "messages": [
    {
      "id": "mid_abc123",
      "text": "Do you ship abroad?",
      "senderId": "987654321",
      "sentAt": "2026-09-08T12:00:00.000Z",
      "attachments": []
    }
  ],
  "cursor": null
}

Start a Conversation

Accepts a page-scoped user id (numeric only, Facebook exposes no username lookup). Returns a conversation shell; the first sent message opens the thread in Messenger.

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.createInboxConversation({
  createInboxConversationBody: {
    "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
    "recipient": "987654321"
  },
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "convo": {
    "id": "987654321",
    "members": [
      {
        "id": "987654321",
        "username": null,
        "displayName": null
      }
    ],
    "muted": false,
    "unreadCount": 0,
    "lastMessage": null
  }
}

Send a Message

Text is limited to 2,000 characters. Attach an image, video, audio file, or document with attachmentUrl (public HTTPS URL).

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.sendInboxMessage({
  sendInboxMessageBody: {
    "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
    "convoId": "t_987654321",
    "text": "Yes, worldwide!"
  },
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "message": {
    "id": "mid_def456",
    "text": "Yes, worldwide!",
    "senderId": "123456789012345",
    "sentAt": "2026-09-08T12:00:00.000Z",
    "attachments": []
  }
}

Rich Messages

Add quickReplies (max 13 tappable replies) to any text message. Add buttons (max 3, web_url or postback) for a button template, or templateElements (max 10) for a generic carousel. Attachments cannot be combined with buttons or carousel elements:

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.sendInboxMessage({
  sendInboxMessageBody: {
    "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
    "convoId": "t_987654321",
    "text": "Choose:",
    "buttons": [
      {
        "type": "web_url",
        "title": "View Website",
        "url": "https://example.com"
      }
    ]
  },
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "message": {
    "id": "3k7y...",
    "text": "Hey, loved your latest post!",
    "senderId": "did:plc:alice",
    "sentAt": "2026-09-08T12:00:00.000Z",
    "attachments": [
      {
        "type": "image",
        "url": "https://cdn.example.com/photo.jpg"
      }
    ]
  }
}

Private Replies

Answer a Page post comment with a Messenger DM. One per comment, same 7-day window:

import { Configuration, CommentsApi } from "@onepostly/sdk";

const commentsApi = new CommentsApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await commentsApi.createPrivateReply({
  body: {
    "post": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
    "commentId": "123456789012345_987654321",
    "text": "Thanks! Check your DMs."
  },
});
console.log(response);

{
  "reply": {
    "postId": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
    "destinationId": "d9e8f7a6-5b4c-4a3d-8e2f-1a2b3c4d5e6f7",
    "platform": "facebook",
    "commentId": "123456789012345_987654321",
    "reply": {
      "id": "mid_def456",
      "text": "Thanks! Check your DMs.",
      "timestamp": "2026-09-08T12:00:00.000Z"
    }
  }
}

Webhooks

Inbound messages also arrive as inbox webhooks.

Errors

Code	Cause	Fix
`INBOX_PERMISSION`	Connection lacks `pages_messaging`	Reconnect the Page
`RECIPIENT_NOT_FOUND`	Id is not a valid page-scoped user id	Use the numeric recipient id
`TEXT_TOO_LONG`	Over 2,000 characters	Trim the text
`INVALID_ATTACHMENT`	`attachmentUrl` is not a public HTTPS URL	Use a direct HTTPS media URL
`INVALID_QUICK_REPLIES`	More than 13 quick replies	Keep at most 13
`INVALID_TEMPLATE`	Too many buttons/elements, missing button url/payload, or attachment combined with a template	Max 3 buttons, 10 elements; web_url needs url, postback needs payload
`MESSAGE_WINDOW_EXPIRED`	24-hour window lapsed	Wait for the customer to message again
`TOKEN_INVALID`	Connection token expired or revoked	Reconnect the Page