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.

string | null

The language the message is written in, as a short code such as sv. null when unknown, for example on replies from teammates; the conversation’s language applies then.

array

Files attached to the message. Inline images in an email body are not listed. Fetch a file with Download an attachment.

Show properties

string

Attachment ID prefixed with ea_.

string

Original filename uploaded by the sender.

string

The file’s media type, such as application/pdf.

integer

File size in bytes.

string

ISO 8601 UTC timestamp of when the message was recorded.

string

ISO 8601 UTC timestamp of when the message last changed. Equals createdAt for a message that never changed. An AI chat message grows when the visitor answers a prompt in the widget (for example confirming a handover) and the AI replies: the reply is added to the same message.

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.",
      "language": "en",
      "attachments": [
        {
          "id": "ea_6tXw2qKb8mRf3cN7p",
          "filename": "receipt.pdf",
          "contentType": "application/pdf",
          "size": 48213
        }
      ],
      "createdAt": "2026-04-29T14:30:00Z",
      "updatedAt": "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?",
      "language": "en",
      "attachments": [],
      "createdAt": "2026-04-29T14:32:00Z",
      "updatedAt": "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

Channels

Conversations

Contacts

Attachments

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