Retrieve Customer Support Conversations

Retrieves a list of customer support conversations filtered by lead ID, visitor ID, user ID, or site ID.

Endpoint


GET /api/agents/customerSupport/conversations

Query Parameters

Parameter	Type	Required	Description
`lead_id`	string	No*	ID of the lead associated with the conversations
`visitor_id`	string	No*	ID of the visitor associated with the conversations
`user_id`	string	No*	ID of the user associated with the conversations
`site_id`	string	No*	ID of the site associated with the conversations
`limit`	number	No	Maximum number of conversations to return (default: 10)
`offset`	number	No	Number of conversations to skip (for pagination, default: 0)

*At least one of lead_id, visitor_id, user_id, or site_id is required.

Example Request


GET /api/agents/customerSupport/conversations?lead_id=f41bb290-0404-44d7-a969-b21a7ec65b77&limit=5

Or filter by site ID:


GET /api/agents/customerSupport/conversations?site_id=9be0a6a2-5567-41bf-ad06-cb4014f0faf2&limit=10

Try It

API Tester

Este componente te permite probar diferentes endpoints de API.

Response

Success Response


{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "8e7d5b3a-2c19-4f5e-9d08-87e31b409e26",
        "title": "Order Status Inquiry",
        "created_at": "2023-10-15T18:22:45Z",
        "updated_at": "2023-10-15T18:30:12Z",
        "lead_id": "f41bb290-0404-44d7-a969-b21a7ec65b77",
        "visitor_id": null,
        "user_id": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
        "agent_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "message_count": 5,
        "last_message": {
          "content": "Your order #12345 has been shipped and should arrive within 2-3 business days. You can track it using the link I just sent to your email.",
          "role": "assistant",
          "created_at": "2023-10-15T18:30:12Z"
        }
      },
      {
        "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
        "title": "Return Request",
        "created_at": "2023-10-12T14:05:32Z",
        "updated_at": "2023-10-12T14:15:23Z",
        "lead_id": "f41bb290-0404-44d7-a969-b21a7ec65b77",
        "visitor_id": null,
        "user_id": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
        "agent_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "message_count": 3,
        "last_message": {
          "content": "I've processed your return request. Please use the prepaid shipping label I've sent to your email. Once we receive the item, your refund will be processed within 5 business days.",
          "role": "assistant",
          "created_at": "2023-10-12T14:15:23Z"
        }
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 2
    }
  }
}

Error Response


{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "At least one of lead_id, visitor_id, user_id, or site_id is required"
  }
}

Error Codes

Code	Description
`INVALID_REQUEST`	The request parameters are invalid (missing required fields or invalid UUID format)
`DATABASE_ERROR`	Error occurred when querying the database
`INTERNAL_SERVER_ERROR`	Internal system error occurred

Notes

This endpoint provides a paginated list of conversations with summary information
Each conversation includes a count of messages and the most recent message
You must provide at least one identifier (lead_id, visitor_id, user_id, or site_id) to filter the results
The conversations are ordered by last activity (updated_at) in descending order
Use the pagination parameters (limit and offset) to navigate through large result sets

Code Examples

JavaScript/Node.js


const fetchConversations = async (leadId) => {
  const response = await fetch(`/api/agents/customerSupport/conversations?lead_id=${leadId}`, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    }
  });
  
  return await response.json();
};

Python


import requests
 
def fetch_conversations(lead_id=None, visitor_id=None, user_id=None, site_id=None, limit=10, offset=0):
    params = {}
    if lead_id:
        params['lead_id'] = lead_id
    if visitor_id:
        params['visitor_id'] = visitor_id
    if user_id:
        params['user_id'] = user_id
    if site_id:
        params['site_id'] = site_id
    
    params['limit'] = limit
    params['offset'] = offset
    
    response = requests.get(
        'https://your-api-base-url/api/agents/customerSupport/conversations',
        params=params
    )
    
    return response.json()