274 lines
6.6 KiB
Markdown
274 lines
6.6 KiB
Markdown
# 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
|