Overview

The Inbox API provides endpoints for managing unified social media inbox items including comments, mentions, and direct messages across all connected platforms.

Base URL: /api/inbox

Authentication: All endpoints require Bearer token authentication.

---

Endpoints

GET /api/inbox

List inbox items with filtering and pagination.

Query Parameters:

• platform (optional): Filter by platform (FACEBOOK, INSTAGRAM, TWITTER, etc.)
• type (optional): Filter by type (COMMENT, DM, MENTION, QUOTE, REVIEW)
• status (optional): Filter by status (UNREAD, READ, REPLIED, ARCHIVED, DELETED)
• assignedToId (optional): Filter by assigned user ID
• requiresAction (optional): Filter items requiring action (boolean)
• search (optional): Search in content
• cursor (optional): Pagination cursor
• limit (optional): Items per page (default: 50, max: 100)

Response:

{
  "items": [
    {
      "id": "uuid",
      "type": "COMMENT",
      "status": "UNREAD",
      "content": "Great post!",
      "authorName": "John Doe",
      "authorHandle": "johndoe",
      "authorAvatarUrl": "https://...",
      "platformCreatedAt": "2024-01-01T00:00:00Z",
      "sentiment": "positive",
      "sentimentScore": 0.85,
      "requiresAction": false,
      "priority": 0,
      "socialAccount": {
        "id": "uuid",
        "platform": "FACEBOOK",
        "displayName": "My Page"
      }
    }
  ],
  "total": 150,
  "cursor": "next_page_cursor"
}

---

GET /api/inbox/stats

Get unread counts by platform and type.

Response:

{
  "total": 42,
  "byPlatform": {
    "FACEBOOK": 15,
    "INSTAGRAM": 12,
    "TWITTER": 10,
    "LINKEDIN": 5
  },
  "byType": {
    "COMMENT": 25,
    "DM": 10,
    "MENTION": 7
  },
  "requiresAction": 15
}

---

GET /api/inbox/:id

Get a single inbox item with full thread context.

Parameters:

• id: Inbox item UUID

Response:

{
  "id": "uuid",
  "type": "COMMENT",
  "content": "Reply to another comment",
  "parentItem": {
    "id": "parent_uuid",
    "content": "Original comment"
  },
  "replies": [
    {
      "id": "reply_uuid",
      "content": "Our response",
      "userId": "user_uuid",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

---

PUT /api/inbox/:id

Update inbox item status, assignment, or tags.

Parameters:

• id: Inbox item UUID

Request Body:

{
  "status": "READ",
  "assignedToId": "user_uuid",
  "tags": ["customer_support", "urgent"],
  "internalNotes": "Customer needs follow-up"
}

Response:

{
  "success": true
}

---

DELETE /api/inbox/:id

Delete an inbox item (soft or hard delete).

Parameters:

• id: Inbox item UUID

Query Parameters:

• permanent (optional): Boolean for hard delete (default: false)

Response:

{
  "success": true
}

---

POST /api/inbox/:id/reply

Reply to a comment or DM via the platform.

Parameters:

• id: Inbox item UUID

Request Body:

{
  "content": "Thank you for your feedback!"
}

Response:

{
  "success": true,
  "replyId": "uuid",
  "platformReplyId": "platform_post_id"
}

Errors:

• 400: Invalid content or missing required fields
• 404: Inbox item not found
• 500: Platform API error

---

POST /api/inbox/bulk

Perform bulk actions on multiple items.

Request Body:

{
  "itemIds": ["uuid1", "uuid2", "uuid3"],
  "action": "mark_read",
  "assignedToId": "user_uuid",
  "permanent": false
}

Actions:

• mark_read: Mark items as READ
• archive: Mark items as ARCHIVED
• assign: Assign to user
• add_tag: Add tag to items
• delete: Delete items (soft or hard based on permanent flag)

Response:

{
  "success": true,
  "updated": 3
}

---

POST /api/inbox/sync

Manually trigger inbox sync for all accounts.

Query Parameters:

• platform (optional): Sync specific platform only

Response:

{
  "success": true,
  "synced": 5,
  "errors": 0
}

---

Error Responses

All endpoints may return standard error responses:

401 Unauthorized:

{
  "error": "Invalid or missing authentication token"
}

403 Forbidden:

{
  "error": "Access denied to this resource"
}

404 Not Found:

{
  "error": "Inbox item not found"
}

500 Internal Server Error:

{
  "error": "Internal server error",
  "message": "Detailed error message"
}

---

Rate Limiting

API endpoints are rate-limited per company:

• Standard: 100 requests/minute
• Bulk operations: 20 requests/minute

Rate limit headers:

• X-RateLimit-Limit: Maximum requests
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Reset timestamp

---

Webhooks

The inbox automatically receives updates via platform webhooks:

• Facebook/Instagram: Comment and DM notifications
• Twitter: Account Activity API
• YouTube: PubSubHubbub notifications

No manual configuration required - webhooks are registered automatically when accounts are connected.