List conversations

Returns a paginated list of conversations in your organization, ordered by the sort field. Supports filtering by status, channel, assignee, support level, topic, tag, and date range, plus full-text search via q.

GET /v1/conversations

Authentication

Bearer token in the Authorization header. See Authentication.

Authorization: Bearer rfl_live_...

Query parameters

Pagination

limit

integer

default:"20"

Number of conversations per page. Range 1–100.

startingAfter

string

Opaque cursor from the previous response’s nextCursor. See Pagination.

Sorting

sort

string

default:"-updatedAt"

Field and direction. Prefix with - for descending. One of:

createdAt
-createdAt
updatedAt
-updatedAt

Filters

status

string | string[]

Filter by conversation status. Repeat the parameter to match multiple values (e.g. ?status=needs_first_response&status=needs_follow_up). One of:

waiting_for_user
needs_first_response
needs_follow_up
scheduled_ai_response
assumed_resolved
resolved
spam
paused
investigating
archived

channelId

string | string[]

Filter by channel ID. Repeat to match multiple channels.

assignedToUserId

string

Filter by the user a conversation is assigned to. Pass the literal string unassigned to match conversations with no assignee.

supportLevel

string

Filter by who is currently handling the conversation. One of ai, human.

topicId

string | string[]

Filter by topic ID. Repeat to match multiple topics.

tagId

string | string[]

Filter by tag ID. Repeat to match multiple tags.

string

Full-text search query. Matches conversation title and message content.

Date range

Use either createdAt or updatedAt ranges — not both. Mixing them returns 422 conflicting_date_range.

createdAt[gte]

string (ISO 8601)

Only return conversations created on or after this timestamp.

createdAt[lte]

string (ISO 8601)

Only return conversations created on or before this timestamp.

updatedAt[gte]

string (ISO 8601)

Only return conversations updated on or after this timestamp.

updatedAt[lte]

string (ISO 8601)

Only return conversations updated on or before this timestamp.

Response

Returns a list envelope containing Conversation objects.

The Conversation object

string

Unique identifier prefixed with conv_.

object

string

Always "conversation".

title

string

Conversation subject or summary.

status

string

Current status. One of the values listed under the status query parameter.

supportLevel

string

Who is currently handling the conversation. One of ai, human.

channel

object

The channel the conversation belongs to.

Show properties

string

Channel ID prefixed with chan_.

name

string

Channel display name.

type

string

Channel type (e.g. email, widget).

contact

object

The contact who started the conversation.

Show properties

string

Contact ID prefixed with ct_.

name

string | null

Contact display name.

string | null

Contact email address.

lastMessagePreview

string | null

First 200 characters of the most recent message. Truncated with … when longer. null if the conversation has no messages.

topics

array

Topics tagged on the conversation.

Show properties

string

Topic ID.

name

string

Topic name.

color

string | null

Topic color (hex string), if set.

createdAt

string

ISO 8601 UTC timestamp of conversation creation.

updatedAt

string

ISO 8601 UTC timestamp of the most recent update.

waitingSince

string | null

ISO 8601 UTC timestamp of when the conversation started waiting for a response. null if not waiting.

Examples

List the most recently updated conversations

curl "https://api.replyful.com/v1/conversations?limit=5" \
  -H "Authorization: Bearer rfl_live_..."

Response

{
  "object": "list",
  "data": [
    {
      "id": "conv_01HK7G3M8YPQ1A0R3N2X9Y4ZBC",
      "object": "conversation",
      "title": "Refund request",
      "status": "needs_first_response",
      "supportLevel": "ai",
      "channel": {
        "id": "chan_01HK6P9X2D3R5T7V9W1Y3Z5BCE",
        "name": "Support inbox",
        "type": "email"
      },
      "contact": {
        "id": "ct_01HK6QFE7T2N4P6S8U0W2Y4ABD",
        "name": "Ada Lovelace",
        "email": "[email protected]"
      },
      "lastMessagePreview": "Hi, I'd like a refund on my last order...",
      "topics": [
        { "id": "tpc_01HK6RB...", "name": "Billing", "color": "#0098da" }
      ],
      "createdAt": "2026-04-29T14:30:00Z",
      "updatedAt": "2026-04-29T14:32:00Z",
      "waitingSince": "2026-04-29T14:32:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJzIjoiMjAyNi0wNC0yOVQxNDozMjowMC4wMDBaIiwiaSI6ImNvbnZfMDFISzdHM004WVBRMUEwUjNOMlg5WTRaQkMifQ",
  "url": "/v1/conversations"
}

Filter and sort

Conversations awaiting a first response or follow-up, oldest first:

curl "https://api.replyful.com/v1/conversations?status=needs_first_response&status=needs_follow_up&sort=createdAt&limit=20" \
  -H "Authorization: Bearer rfl_live_..."

Find unassigned conversations from a date range

curl --get "https://api.replyful.com/v1/conversations" \
  -H "Authorization: Bearer rfl_live_..." \
  --data-urlencode "assignedToUserId=unassigned" \
  --data-urlencode "createdAt[gte]=2026-04-01T00:00:00Z" \
  --data-urlencode "createdAt[lte]=2026-04-30T23:59:59Z" \
  --data-urlencode "limit=100"

Walk every page

See the pagination guide for a copy-paste loop in Node and Python.

Error responses

Status	`error.code`	When
`401`	`missing_api_key`	The `Authorization` header is absent.
`401`	`invalid_api_key`	The token is malformed, unknown, or archived.
`422`	`invalid_query_parameter`	A query parameter failed validation. The `param` field names the offender.
`422`	`invalid_cursor`	The `startingAfter` cursor could not be decoded.
`422`	`conflicting_date_range`	Both `createdAt[...]` and `updatedAt[...]` were provided.
`429`	`too_many_requests`	Rate limit exceeded. Honor `Retry-After`.

See Errors for the full error envelope reference.

Documentation

Conversations

Documentation Index

​Authentication

​Query parameters

​Pagination

​Sorting

​Filters

​Date range

​Response

​The Conversation object

​Examples

​List the most recently updated conversations

​Filter and sort

​Find unassigned conversations from a date range

​Walk every page

​Error responses

Authentication

Query parameters

Pagination

Sorting

Filters

Date range

Response

The Conversation object

Examples

List the most recently updated conversations

Filter and sort

Find unassigned conversations from a date range

Walk every page

Error responses