List messages

Returns a conversation’s messages, ordered by createdAt ascending (oldest first) with cursor pagination. There is no cap on thread length — keep following nextCursor until hasMore is false.

GET /v1/conversations/{id}/messages

Authentication

Bearer token in the Authorization header. See Authentication.

Authorization: Bearer rfl_live_...

Path parameters

string

required

Conversation ID prefixed with conv_.

Query parameters

integer

default:"20"

Number of messages per page. Range 1–100.

string

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

Response

Returns a list envelope containing Message objects.

The Message object

string

Unique identifier prefixed with msg_.

string

Always "message".

string

The owning conversation’s ID.

string

Message medium. One of chat, email.

string

Who sent the message. One of user (a contact), assistant (Replyful AI), human (a teammate), system.

object | null

The resolved sender. null for system messages.

Show properties

string

One of contact, user (a teammate), ai_agent.

string

The author’s ID (con_…, user_…, or agent_…).

string | null

Display name.

string | null

Email address. Always null for ai_agent.

string | null

Plain-text body. null if the message has no text content.

array

Non-inline files attached to the message.

Show properties

string

Attachment ID.

string

Original filename uploaded by the sender.

string

ISO 8601 UTC timestamp of when the message was recorded.

Examples

Page through a thread

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

const res = await fetch(
  "https://api.replyful.com/v1/conversations/conv_x7Kw2mQb9tRfN4c/messages?limit=50",
  { headers: { Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}` } },
);
const { data, hasMore, nextCursor } = await res.json();

import os, requests

res = requests.get(
    "https://api.replyful.com/v1/conversations/conv_x7Kw2mQb9tRfN4c/messages",
    headers={"Authorization": f"Bearer {os.environ['REPLYFUL_API_KEY']}"},
    params={"limit": 50},
)
res.raise_for_status()
body = res.json()

Response

{
  "object": "list",
  "data": [
    {
      "id": "msg_k2Wq7xTb9mRf4cN8jP",
      "object": "message",
      "conversationId": "conv_x7Kw2mQb9tRfN4c",
      "type": "email",
      "role": "user",
      "author": {
        "type": "contact",
        "id": "con_9dKmT3xWq6bYrN8cJfA2eH4gp",
        "name": "Ada Lovelace",
        "email": "[email protected]"
      },
      "content": "Hi, I'd like a refund on my last order. Order #4821.",
      "attachments": [
        { "id": "ea_6tXw2qKb8mRf3cN", "filename": "receipt.pdf" }
      ],
      "createdAt": "2026-04-29T14:30:00Z"
    },
    {
      "id": "msg_q8Tb3xWk2mRf7cN4jD",
      "object": "message",
      "conversationId": "conv_x7Kw2mQb9tRfN4c",
      "type": "email",
      "role": "assistant",
      "author": {
        "type": "ai_agent",
        "id": "agent_w2Kq7xTb9mRf4",
        "name": "Support Bot",
        "email": null
      },
      "content": "Thanks Ada — I can see order #4821 here. Could you confirm the email used at checkout so I can look up the payment?",
      "attachments": [],
      "createdAt": "2026-04-29T14:32:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "url": "/v1/conversations/conv_x7Kw2mQb9tRfN4c/messages"
}

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.
`404`	`conversation_not_found`	The conversation does not exist or belongs to another organization.
`422`	`invalid_path_parameter`	The `id` path parameter is not a valid `conv_…` ID.
`422`	`invalid_query_parameter`	A query parameter failed validation.
`422`	`invalid_cursor`	The `startingAfter` cursor could not be decoded.
`429`	`too_many_requests`	Rate limit exceeded. Honor `Retry-After`.

See Errors for the full error envelope reference.

Documentation

Tickets

Conversations

Knowledge

Authentication

Path parameters

Query parameters

Response

The Message object

Examples

Page through a thread

Error responses

​Authentication

​Path parameters

​Query parameters

​Response

​The Message object

​Examples

​Page through a thread

​Error responses

Authentication

Path parameters

Query parameters

Response

The Message object

Examples

Page through a thread

Error responses