Outstand API Documentation

Connect Instagram with messaging permissions, receive an inbound DM, and send your first reply.

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 explicitly request instagram_business_manage_messages alongside instagram_business_basic:

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_manage_messages"
  }'

Redirect the account owner to the returned auth_url, complete authorization, and finish the account connection flow. An existing publishing-only connection needs to be authorized again with messaging access.

Custom scopes replace the default scope list. If the same connection also publishes posts or reads insights, include those permissions too. The default publishing connection does not request messaging access.

The Meta app used for the connection must have access to the requested messaging permission. For BYOK, configure your own app using the Instagram configuration guide and obtain the messaging permission approval needed for your users. If messaging access is unavailable on your Managed Keys connection, contact support@outstand.so.

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.

2. Receive an inbound message

Send a DM from another Instagram account to the connected account. Conversations are created from incoming platform events; there is no create-conversation endpoint.

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 messaging permission was granted 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.

Getting started