Getting started

This guide uses an Outstand API key and an Instagram Business or Creator account. Keep your API key on your backend; see Authentication.

1. Connect with messaging access

Create a connection using the authentication URL endpoint and pass the scopes field in the JSON body. It is a comma-separated list, and it replaces the default Instagram scopes rather than adding to them, so include the four default scopes as well as instagram_business_manage_messages:

curl -X POST https://api.outstand.so/v1/social-networks/instagram/auth-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uri": "https://your-app.example.com/social/callback",
    "scopes": "instagram_business_basic,instagram_business_content_publish,instagram_business_manage_comments,instagram_business_manage_insights,instagram_business_manage_messages"
  }'

Redirect the account owner to the returned auth_url, complete authorization, and finish the account connection flow. The account owner must approve access to messages on the Instagram consent screen.

Direct Messages are available on Managed Keys only for now. Inbound messages reach Outstand through webhooks configured on Outstand's own Meta app, so connections made through your own Meta app (BYOK) do not receive them. If you are on BYOK and need Direct Messages, contact support@outstand.so. See the Instagram configuration guide for details.

When messaging permission is granted, Outstand's OAuth callback subscribes the Instagram account to messaging webhooks. This platform subscription brings DMs into Outstand. Your own Outstand webhook endpoint is a separate subscription that forwards events to your application.

Existing accounts

An account connected without instagram_business_manage_messages must be reconnected with the request above before it can receive or send DMs. Reconnecting updates the existing social account in place, so its ID, scheduled posts and history are kept.

Until it is reconnected, Outstand is not subscribed to the account's messages: no conversations are created for it, GET /v1/conversations returns nothing for it, and no conversation.started or message.received webhooks fire. There is no error; the account simply stays silent.

The dashboard requests the default scopes only, so reconnecting there does not enable messaging, and reconnecting a messaging-enabled account there (or with a scopes list that omits instagram_business_manage_messages) removes it.

If a reply is sent from an account whose token lacks the permission, the request is still accepted with 202, and delivery then fails: the message's status becomes failed, a message.failed webhook fires, and its error field carries Instagram's rejection in the form Instagram send failed: <HTTP status> <Instagram error body>.

2. Receive an inbound message

Send a DM from another Instagram account to the connected account. Conversations are created from incoming platform events, or when you start one.

List the connected account's conversations:

curl 'https://api.outstand.so/v1/conversations?social_account_id=YOUR_SOCIAL_ACCOUNT_ID&limit=25' \
  -H "Authorization: Bearer YOUR_API_KEY"

Use an id from the response's data array as CONVERSATION_ID below. An empty list means no matching conversations have been ingested yet. Check that the account was connected with instagram_business_manage_messages in scopes (see Existing accounts) and send a fresh inbound DM.

3. Read the messages

curl 'https://api.outstand.so/v1/conversations/CONVERSATION_ID/messages?limit=50' \
  -H "Authorization: Bearer YOUR_API_KEY"

The response's data array contains messages, newest first. Each message includes its direction and status. Follow pagination.nextCursor while pagination.hasMore is true to fetch additional pages.

4. Send a reply

Reply within 24 hours of the contact's last inbound message:

curl -X POST https://api.outstand.so/v1/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello! How can I help you today?"}'

A successful request returns 202 Accepted, with a message object whose status is pending. Store its id to correlate delivery updates. Acceptance does not mean the recipient has received the reply.

Subscribe to message.sent and message.failed in webhook settings, or poll the message list and find the stored message ID. See Message lifecycle and webhooks for scheduling, media attachments, and error handling.

5. Mark the conversation as read

When the account owner reads the conversation in your inbox, call:

curl -X POST https://api.outstand.so/v1/conversations/CONVERSATION_ID/read \
  -H "Authorization: Bearer YOUR_API_KEY"

This marks inbound messages as read, resets unreadCount to zero, and sends a read receipt on Instagram. Fetching the message list alone does not mark it as read.

Keep your inbox updated

Subscribe to conversation.started, message.received, message.sent, and message.failed. Use the event's conversation and message IDs to refresh the relevant thread. Follow the shared webhook setup and signature verification guide and the messaging event reference.