Overview

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

Messaging currently supports Instagram only. Support for publishing on other Outstand networks does not imply support for direct messages on those networks.

Conversations and messages

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 Instagram'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, you can only start a conversation with a private reply to the contact's comment on one of the account's posts. See Comment-to-DM.

Build your integration

1. Connect an Instagram account with messaging access. Messaging is not requested by default, so pass instagram_business_manage_messages in scopes.
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 windows

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. Scheduled replies must also fall within the applicable window.

See messaging windows and scheduling before implementing delayed replies.

Authentication and reference

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.