Skip to main content

​
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

HeaderValue
AuthorizationBearer

​
Query parameters

​
status
string
Filter conversations by status. One of "open", "pending", "resolved", or "closed". Omit to return all statuses.
​
assignee_id
integer
Filter conversations assigned to a specific agent by their user ID.
​
page
integer
Page number for pagination. Defaults to 1.
​
limit
integer
Number of results per page. Defaults to 50.

​
Response

Returns an array of conversation objects.
​
id
string (UUID)
Unique identifier for the conversation.
​
business_id
string (UUID)
The business this conversation belongs to.
​
customer_id
string (UUID) | null
The customer associated with this conversation.
​
assignee_id
string (UUID) | null
The agent this conversation is assigned to, or null if unassigned.
​
status
string
Current status of the conversation. One of "open", "pending", "resolved", or "closed".
​
channel_type
string
The channel this conversation came through (e.g. "widget", "email", "whatsapp").
​
channel_id
string (UUID) | null
The channel record this conversation is linked to.
​
created_at
string (ISO 8601)
Timestamp when the conversation was created.
​
updated_at
string (ISO 8601)
Timestamp when the conversation was last updated.
​
first_response_at
string (ISO 8601) | null
Timestamp of the first agent response, used for SLA tracking.
​
customer
object | null
Embedded customer object if available.
​
messages
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"

​
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

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