SparrowDesk
Conversations

List all conversations

GET
/conversations

Authorization

AuthorizationBearer <token>

In: header

Query Parameters

starting_after?string|null

Cursor for pagination (only needed for subsequent pages)

per_page?integer|null

Number of items per page (1-100, default 25)

Range1 <= value <= 100
status?|null

Filter by conversation status

priority?|null

Filter by priority level

assigned_to_member_id?|null

Filter by assigned agent IDs

assigned_to_team_id?|null

Filter by assigned team IDs

brand_id?|null

Filter by brand IDs

requested_by_id?integer|null

Filter by requester contact id(s). Omit (with no requested_by_company) to list all conversations. With requested_by_company, only requesters in both filters are returned (intersection).

requested_by_company?integer|null

Filter by requester contact company id. Omit (with no requested_by_id) to list all conversations. With requested_by_id, only requesters matching both filters are returned (intersection).

handled_by_ai_agent?string|null

When omitted, no filter by AI handling. true — only conversations assigned to an AI agent. false — conversations handed off for human help, or where the assignee is not an AI agent.

Value intrue | false
search?string|null

Search by subject, description, replies, or conversation ID. Use quotes for exact phrases.

Lengthlength <= 250
sort_by?string|null

Field to sort by (default created_at)

Value in"created_at" | "updated_at"
sort_order?string|null

Sort order (default desc)

Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

curl -X GET "https://app.sparrowdesk.com/v1/conversations"
{
  "data": [
    {
      "id": 12345,
      "brand": "Support Brand",
      "brand_id": 12345,
      "source": "Mail",
      "status": "Open",
      "priority": "High",
      "created_at": 1672531200,
      "first_response_time": 1672534800,
      "resolution_time": null,
      "due": 1672617600,
      "first_response_due": 1672538400,
      "requested_by_email": "[email protected]",
      "requested_by_phone": "+1415555267",
      "requested_by_id": 67890,
      "assigned_to_member_id": 123,
      "assigned_to_team_id": 456,
      "last_updated_at": 1672535400,
      "subject": "Payment issue with order #12345",
      "description_html": "<p>I'm having trouble with my payment...</p>",
      "description_text": "I'm having trouble with my payment...",
      "attachments": [
        "https://cdn.example.com/receipt.pdf"
      ],
      "tags": [
        {
          "id": 1,
          "label": "billing"
        }
      ],
      "custom_fields": [
        {
          "id": 9250,
          "value": "ORD-12345",
          "option_ids": [
            7790,
            7791
          ]
        }
      ],
      "csat": {
        "score": 4,
        "sentiment": "positive",
        "feedback": "Great support experience!",
        "scale": 5
      },
      "properties": {
        "request_language": "English",
        "browser_timezone": "Asia/Calcutta",
        "browser": "Chrome",
        "device": "mac OS 10.15.7",
        "ip_address": "192.168.1.1",
        "country": "India",
        "region": "Tamil Nadu > Chennai"
      }
    }
  ],
  "pages": {
    "per_page": 20,
    "next_cursor": "eyJpZCI6MTIzNDUsImNyZWF0ZWRfYXQiOjE2NzI1MzEyMDB9",
    "next_url": "https://app.sparrowdesk.com/conversations?per_page=20&starting_after=eyJpZCI6MTIzNDUsImNyZWF0ZWRfYXQiOjE2NzI1MzEyMDB9"
  },
  "total_count": 100
}
{
  "error": {
    "message": "Invalid query parameters"
  }
}
{
  "error": {
    "message": "Error retrieving conversations"
  }
}