# DM Automation API - HTTPie Test Examples

## Prerequisites
```bash
# 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:

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

Expected response:
```json
{
  "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:

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

With pagination:
```bash
http GET "$BASE_URL/api/dm/messages/conversations?userId=$USER_EMAIL&after=CURSOR_VALUE"
```

Expected response:
```json
{
  "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:

```bash
export CONVERSATION_ID="your_conversation_id_here"

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

With pagination:
```bash
http GET "$BASE_URL/api/dm/messages/conversations/$CONVERSATION_ID/messages?userId=$USER_EMAIL&after=CURSOR_VALUE"
```

Expected response:
```json
{
  "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:

```bash
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:
```json
{
  "recipient_id": "instagram_scoped_user_id",
  "message_id": "mid.message_id_123"
}
```

## 5. Mark Conversation as Read
Mark a conversation as read:

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

Expected response:
```json
{
  "success": true
}
```

## Webhook Setup (For Auto-Reply Automation)

### Step 1: Verify Webhook (Facebook will call this during setup)
```bash
# 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
```bash
# 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)
```bash
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
```bash
http GET "$BASE_URL/api/dm/messages/conversations"

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

### No Channel Connected
```bash
http GET "$BASE_URL/api/dm/messages/conversations?userId=nonexistent@example.com"

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

### Invalid Conversation ID
```bash
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)

```bash
# 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:

```bash
# 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:
```bash
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