Dev_Socialbuddy_Backend/DM_API_TEST_EXAMPLES.md

DM Automation API - HTTPie Test Examples

Prerequisites

# Install httpie if not already installed
pip install httpie

# Set your base URL and user email
export BASE_URL="https://api.socialbuddy.co"
export USER_EMAIL="alaguraj0361@gmail.com"

1. Test Auto-Reply (Static Template)

Test the static reply generator without connecting to Instagram:

http POST $BASE_URL/api/dm/messages/test-autoreply \
  messageText="What are your prices?"

Expected response:

{
  "originalMessage": "What are your prices?",
  "autoReply": "For pricing information, please check our website or DM us with specific requirements."
}

2. Get Conversations

Fetch all Instagram DM conversations for a user:

http GET "$BASE_URL/api/dm/messages/conversations?userId=$USER_EMAIL"

With pagination:

http GET "$BASE_URL/api/dm/messages/conversations?userId=$USER_EMAIL&after=CURSOR_VALUE"

Expected response:

{
  "data": [
    {
      "id": "conversation_id_123",
      "updated_time": "2026-01-20T10:30:00+0000",
      "participants": {...},
      "messages": {...}
    }
  ],
  "paging": {
    "cursors": {
      "before": "...",
      "after": "..."
    },
    "next": "..."
  }
}

3. Get Messages in a Conversation

Fetch messages from a specific conversation:

export CONVERSATION_ID="your_conversation_id_here"

http GET "$BASE_URL/api/dm/messages/conversations/$CONVERSATION_ID/messages?userId=$USER_EMAIL"

With pagination:

http GET "$BASE_URL/api/dm/messages/conversations/$CONVERSATION_ID/messages?userId=$USER_EMAIL&after=CURSOR_VALUE"

Expected response:

{
  "data": [
    {
      "id": "message_id_123",
      "created_time": "2026-01-20T10:25:00+0000",
      "from": {...},
      "to": {...},
      "message": "Hello, I have a question"
    }
  ],
  "paging": {...}
}

4. Send a Message

Send a DM reply to a specific Instagram user:

export RECIPIENT_ID="instagram_scoped_user_id"

http POST "$BASE_URL/api/dm/messages/send?userId=$USER_EMAIL" \
  recipientId="$RECIPIENT_ID" \
  message="Thank you for reaching out! How can I help you today?"

Expected response:

{
  "recipient_id": "instagram_scoped_user_id",
  "message_id": "mid.message_id_123"
}

5. Mark Conversation as Read

Mark a conversation as read:

http POST "$BASE_URL/api/dm/messages/conversations/$CONVERSATION_ID/read?userId=$USER_EMAIL"

Expected response:

{
  "success": true
}

Webhook Setup (For Auto-Reply Automation)

Step 1: Verify Webhook (Facebook will call this during setup)

# Facebook will make this GET request:
# GET /api/dm/webhook?hub.mode=subscribe&hub.verify_token=your_verify_token_123&hub.challenge=CHALLENGE_STRING

Step 2: Test Webhook Locally with ngrok

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 7002

# Set webhook URL in Meta App Dashboard:
# https://your-ngrok-url.ngrok.io/api/dm/webhook

Step 3: Simulate Incoming Message (Testing)

http POST http://localhost:7002/api/dm/webhook \
  'X-Hub-Signature-256:sha256=YOUR_SIGNATURE_HERE' \
  object="instagram" \
  entry:='[{
    "id": "page_id",
    "time": 1234567890,
    "messaging": [{
      "sender": {"id": "sender_instagram_id"},
      "recipient": {"id": "page_instagram_id"},
      "timestamp": 1234567890,
      "message": {
        "mid": "message_id",
        "text": "Hello, I need help"
      }
    }]
  }]'

Error Handling Examples

Missing userId

http GET "$BASE_URL/api/dm/messages/conversations"

# Response: 500
# {"error": "userId is required as query parameter"}

No Channel Connected

http GET "$BASE_URL/api/dm/messages/conversations?userId=nonexistent@example.com"

# Response: 500
# {"error": "Connect a channel first"}

Invalid Conversation ID

http GET "$BASE_URL/api/dm/messages/conversations/invalid_id/messages?userId=$USER_EMAIL"

# Response: 500
# {"error": "Unsupported get request..."}

Testing Workflow (End-to-End)

# 1. First, ensure user has connected their Instagram account
# (Use the social OAuth flow first)

# 2. Verify connection
http GET "$BASE_URL/api/social/auth/status?userId=$USER_EMAIL"

# 3. Get conversations
http GET "$BASE_URL/api/dm/messages/conversations?userId=$USER_EMAIL"

# 4. Pick a conversation ID from response
export CONVO_ID="123456789"

# 5. Get messages in that conversation
http GET "$BASE_URL/api/dm/messages/conversations/$CONVO_ID/messages?userId=$USER_EMAIL"

# 6. Send a reply (get recipient ID from conversation data)
export RECIPIENT="recipient_instagram_scoped_id"
http POST "$BASE_URL/api/dm/messages/send?userId=$USER_EMAIL" \
  recipientId="$RECIPIENT" \
  message="Thanks for your message!"

# 7. Mark conversation as read
http POST "$BASE_URL/api/dm/messages/conversations/$CONVO_ID/read?userId=$USER_EMAIL"

Environment Variables Required

Add these to your .env file:

# Webhook Configuration
WEBHOOK_VERIFY_TOKEN=your_custom_verify_token_123
PAGE_ACCESS_TOKEN=your_page_access_token_here  # Temporary, will be replaced by user-specific tokens

# OAuth (already configured)
OAUTH_APP_ID=your_facebook_app_id
OAUTH_APP_SECRET=your_facebook_app_secret

# Graph API
GRAPH_VER=v21.0

Common Issues & Solutions

Issue: "Connect a channel first"

Solution: User needs to complete the Instagram connection flow:

http GET "$BASE_URL/api/social/auth/login"
# Follow OAuth flow, then connect a channel

Issue: "Invalid signature" on webhook

Solution: Ensure OAUTH_APP_SECRET matches your Meta App settings and raw body middleware is working.

Issue: Empty conversations list

Solution:

1. Verify Instagram Professional/Business account is linked to Facebook Page
2. Check that instagram_manage_messages permission is granted
3. Ensure page has at least one conversation/message

Issue: Cannot send message

Solution:

1. Recipient must have messaged you first (Instagram limitation)
2. Check that recipient ID is the Instagram-scoped ID (IGSID), not username
3. Verify page token has pages_manage_engagement permission

Meta App Configuration Checklist

• App has Instagram Basic Display API enabled
• App has Instagram Graph API enabled
• App has Messenger Platform enabled
• Permissions granted:
  • instagram_manage_messages
  • pages_manage_engagement
  • pages_read_engagement
  • pages_show_list
  • instagram_basic
• Webhook subscribed to messages field
• Webhook verify token matches WEBHOOK_VERIFY_TOKEN in .env
• Page is connected and has Instagram Professional/Business account