List Conversations

Overview

Returns a list of conversations for your business, ordered by most recently updated. You can filter by status or assignee, and paginate through results.

Request

Method: GET URL: /api/v1/conversations/

Headers

Header	Value
Authorization	Bearer

Query parameters

string

Filter conversations by status. One of "open", "pending", "resolved", or "closed". Omit to return all statuses.

integer

Filter conversations assigned to a specific agent by their user ID.

integer

Page number for pagination. Defaults to 1.

integer

Number of results per page. Defaults to 50.

Response

Returns an array of conversation objects.

string (UUID)

Unique identifier for the conversation.

string (UUID)

The business this conversation belongs to.

string (UUID) | null

The customer associated with this conversation.

string (UUID) | null

The agent this conversation is assigned to, or null if unassigned.

string

Current status of the conversation. One of "open", "pending", "resolved", or "closed".

string

The channel this conversation came through (e.g. "widget", "email", "whatsapp").

string (UUID) | null

The channel record this conversation is linked to.

string (ISO 8601)

Timestamp when the conversation was created.

string (ISO 8601)

Timestamp when the conversation was last updated.

string (ISO 8601) | null

Timestamp of the first agent response, used for SLA tracking.

object | null

Embedded customer object if available.

array

Array of messages. May be empty in list responses for performance.

Example

curl "https://api.pingback.live/api/v1/conversations/?status=open&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

const params = new URLSearchParams({ status: 'open', page: 1, limit: 20 });
const response = await fetch(`https://api.pingback.live/api/v1/conversations/?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});
const conversations = await response.json();

Response example

[
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "business_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "customer_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "assignee_id": null,
    "status": "open",
    "channel_type": "widget",
    "channel_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "created_at": "2024-03-01T09:00:00Z",
    "updated_at": "2024-03-01T09:15:00Z",
    "first_response_at": null,
    "customer": {
      "id": 42,
      "business_id": 7,
      "name": "Alex Johnson",
      "email": "alex@example.com",
      "phone": null,
      "external_id": null,
      "created_at": "2024-02-20T08:00:00Z"
    },
    "messages": []
  }
]

Errors

Status	Meaning
401	Unauthorized — missing or invalid Bearer token
422	Validation error — invalid query parameter value

Authentication

Conversations

Channels & Widget

Team

Knowledge Base

Analytics

List Conversations

Overview

Request

Headers

Query parameters

Response

Example

Response example

Errors

​Overview

​Request

​Headers

​Query parameters

​Response

​Example

​Response example

​Errors

Overview

Request

Headers

Query parameters

Response

Example

Response example

Errors