Setup

Once your organization is on the allowlist, do this for every Facebook and Instagram account that should receive DMs:

Reconnect it with messaging permissions. This includes accounts that were already connected before we switched the feature on. They don’t have the permissions yet.
Subscribe it to messages with messaging/enable. This registers the account for Meta’s message webhooks. Without it, no DM ever reaches us.
Make sure your webhook endpoint accepts the new events (see Webhooks).

Step 1: Connect With Messaging Permissions

Add withMessagingScope: true when you generate the connect link. It works on both the hosted portal and the custom connect flow.

const res = await fetch("https://api.bundle.social/api/v1/social-account/connect", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BUNDLE_API_KEY,
  },
  body: JSON.stringify({
    teamId: "team_123",
    type: "INSTAGRAM",
    redirectUrl: "https://yourapp.com/connected",
    withMessagingScope: true,
  }),
});

const { url } = await res.json(); // send your user here

For the hosted portal, pass the same withMessagingScope: true to POST /api/v1/social-account/create-portal-link.

Accounts connected before the feature was enabled must be reconnected. That includes accounts connected with withMessagingScope: true, because the flag is ignored until your organization is on the allowlist. Meta only grants messaging permissions on its login screen, so there is no way to add them silently afterwards. The same reconnect also subscribes the account to new comments, which comment automations need.

Connecting an account never subscribes it to DMs by itself. messaging/enable registers the account for Meta’s message webhooks and starts processing its DMs. You opt in per account, so a customer who only wants scheduling never has their DMs processed. Endpoint: POST /api/v1/social-account/messaging/enable

curl -X POST "https://api.bundle.social/api/v1/social-account/messaging/enable" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "teamId": "team_123", "type": "INSTAGRAM" }'

{
  "socialAccountId": "sa_789",
  "type": "INSTAGRAM",
  "messagingStatus": "ENABLED",
  "messagingLastError": null
}

The call is idempotent, so calling it twice is harmless.

Response	Meaning
`200`	Subscribed, messaging is `ENABLED`. New DMs will start showing up.
`400`	The account is missing the messaging permissions (reconnect it with `withMessagingScope: true`), the team has no account of that type, or no page or account was selected for the connection. The `message` says which.
`404`	Your organization is not on the allowlist yet.
`502`	Meta refused the subscription. The account keeps its previous status (normally `DISABLED`); retry in a bit.

Turning It Off

Endpoint: POST /api/v1/social-account/messaging/disable (same body) We stop processing DMs for that account immediately. Existing conversations stay readable, but sending, reactions and private replies return 403 until you enable it again. If Meta doesn’t confirm the change right away, the status becomes DISABLE_PENDING and the call returns 502, so you can safely retry it.

We only collect messages that arrive after messaging is enabled. Older DM history from before that moment is not imported, and each message we collect is kept for 30 days.

API Documentation

Platforms

Guides

Endpoints

Step 1: Connect With Messaging Permissions

Turning It Off

​Step 1: Connect With Messaging Permissions

​Step 2: Subscribe The Account To Messages

​Turning It Off

Step 1: Connect With Messaging Permissions

Step 2: Subscribe The Account To Messages

Turning It Off