Overview

The Conversations API lets you build an inbox for connected Instagram accounts, Facebook Pages and X accounts. Read inbound direct messages, reply with text, media, quick replies or buttons, react to messages, schedule a reply, start new conversations, and track delivery through webhooks.

Messaging supports Instagram, Facebook Pages and X. Support for publishing on other Outstand networks does not imply support for direct messages on those networks.

The endpoints, the conversation and message objects and the webhook events are the same on all three. What differs is the connection step, because each network names its messaging permission differently, and who you are allowed to message first.

Conversations and messagesCopy Anchor Link

A conversation is a thread between a connected social account and a contact. A message belongs to that conversation and has an inbound or outbound direction. Use the Outstand conversation and message IDs returned by the API when calling endpoints, not the network's platform IDs.

A conversation starts when a contact messages the connected account, or when you start one. Networks limit who a business can message first: on Instagram and Facebook, you can only start a conversation with a private reply to the contact's comment on one of the account's posts. X has no such limit, so an X account can message anyone whose DM settings accept it, with or without a comment to answer. See Comment-to-DM.

Build your integrationCopy Anchor Link

1. Connect an account with messaging access. Messaging is not requested by default, so pass instagram_business_manage_messages in scopes for Instagram, pages_messaging for a Facebook Page, or dm.read for X. On X, also register Outstand's webhook URL on your own X app before connecting the account, see X comment webhooks and Direct Messages.
2. List conversations and read their messages.
3. Send a reply. A 202 Accepted response means the message is pending delivery.
4. Optionally, answer comments in a DM with Comment-to-DM.
5. Follow message lifecycle and webhooks to update your inbox as messages arrive, succeed, fail, or are read.

Messaging windowsCopy Anchor Link

On Instagram and Facebook, free-form replies must fall within 24 hours of the contact's last inbound message. Eligible human support replies can use instagram.tag: "HUMAN_AGENT" for a window of up to seven days, subject to the Meta app's approval requirements and enabled per organization on request.

X has no reply window: an X account can message anyone whose DM settings accept it at any time. Starting a conversation with someone whose settings do not accept it is rejected with 422.

Scheduled replies must also fall within the applicable window.

See messaging windows and scheduling before implementing delayed replies.

Authentication and referenceCopy Anchor Link

All requests use https://api.outstand.so and the same Bearer API key authentication as the Publishing API. Conversations belong to your organization.

The endpoint reference is generated from the Conversations OpenAPI specification. Use the sidebar dropdown to switch between publishing and messaging documentation.