List messages (history)

curl --request GET \
  --url https://api.example.com/api/v1/chat/conversations/:id/messages

import requests

url = "https://api.example.com/api/v1/chat/conversations/:id/messages"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.example.com/api/v1/chat/conversations/:id/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/chat/conversations/:id/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/chat/conversations/:id/messages"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/chat/conversations/:id/messages")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/chat/conversations/:id/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

GET

api

chat

conversations

:id

messages

List messages (history)

curl --request GET \
  --url https://api.example.com/api/v1/chat/conversations/:id/messages

import requests

url = "https://api.example.com/api/v1/chat/conversations/:id/messages"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.example.com/api/v1/chat/conversations/:id/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/chat/conversations/:id/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/chat/conversations/:id/messages"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/chat/conversations/:id/messages")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/chat/conversations/:id/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

Overview

Returns messages for a conversation, newest first (createdAt desc). Pagination is cursor-based on createdAt: pass the oldest createdAt you’ve already seen as ?before=... to fetch the next older page. This is the standard “infinite scroll up” mobile pattern. The endpoint reuses the participant gate from Get conversation, so the same 403 FORBIDDEN / 404 NOT_FOUND semantics apply.

Authentication

Bearer <accessToken> required. requireOnboarded middleware applied.

Path parameters

Name	Type	Required	Notes	Example
`id`	string	yes	24-char hex ObjectId of the conversation.	`66400a8f1c2b4d5e6f7a9000`

Query parameters

Name	Type	Required	Default	Notes	Example
`before`	string	no	(none)	ISO 8601 UTC datetime. Returns messages with `createdAt < before`. Use the oldest `createdAt` from the previous page.	`2026-05-22T14:35:12.001Z`
`limit`	integer	no	`50`	1..200 inclusive. The client typically fetches 50 per page.	`50`

Request body

None.

Response — 200 OK

Field	Type	Notes	Example
`messages`	object[]	Array of message rows sorted by `createdAt desc`. Empty array (`[]`) when the cursor has reached the start of history.

Message object

Field	Type	Allowed values / Notes	Example
`id`	string	24-char hex ObjectId. Use as `upToMessageId` for mark-read.	`66400a8f1c2b4d5e6f7aa000`
`conversationId`	string	24-char hex ObjectId. Always matches the path `:id`.	`66400a8f1c2b4d5e6f7a9000`
`senderId`	string	24-char hex ObjectId of the sender. One of the conversation’s `participantIds`.	`66400a8f1c2b4d5e6f7a8b01`
`clientMessageId`	string	1..64 chars. The token the sender’s client used to dedup at send time. Useful for matching local optimistic UI rows to server rows.	`cm_01HZQ7K3M4N5P6Q7R8S9T0V1W2`
`messageType`	enum	`text`, `image`, `video`, or `file`.	`image`
`text`	string	Body for `text` messages (non-empty); caption for media (may be empty). 0..4000 chars.	`Hi! Loved your kitchen.`
`media`	object \| null	Present iff `messageType` is `image`/`video`/`file`; `null` for `text`. Fields: `url`, `thumbnailUrl`, `fileName`, `mimeType`, `sizeBytes`, `width`, `height`, `durationSec` (see send-message → Media object).
`deliveredTo`	object[]	One Receipt per recipient that has received the message. Phase 4 returns `[]` — delivery receipts are wired up but not yet emitted by the worker.	`[]`
`readBy`	object[]	One Receipt per recipient that has marked the message read. Excludes the sender (you don’t “read” your own messages).	`[]`
`editedAt`	string \| null	ISO 8601 UTC if this message has been edited. `null` in Phase 4 — edit is not exposed yet.	`null`
`deletedAt`	string \| null	ISO 8601 UTC if this message has been soft-deleted. `null` in Phase 4 — delete is not exposed yet.	`null`
`createdAt`	string	ISO 8601 UTC with millisecond precision. Used as the pagination cursor.	`2026-05-22T14:35:12.001Z`
`updatedAt`	string	ISO 8601 UTC. Equal to `createdAt` until edits/receipts mutate the row.	`2026-05-22T14:35:12.001Z`

Receipt object

Field	Type	Notes	Example
`userId`	string	24-char hex ObjectId of the recipient that issued the receipt.	`66400a8f1c2b4d5e6f7a8b00`
`at`	string	ISO 8601 UTC when the receipt was recorded server-side.	`2026-05-22T14:35:18.420Z`

Example response

{
  "messages": [
    {
      "id": "66400a8f1c2b4d5e6f7aa001",
      "conversationId": "66400a8f1c2b4d5e6f7a9000",
      "senderId": "66400a8f1c2b4d5e6f7a8b00",
      "clientMessageId": "cm_01HZQ7K3M4N5P6Q7R8S9T0V1W3",
      "text": "Whereabouts in Camden are you?",
      "deliveredTo": [],
      "readBy": [
        { "userId": "66400a8f1c2b4d5e6f7a8b01", "at": "2026-05-22T14:36:01.022Z" }
      ],
      "editedAt": null,
      "deletedAt": null,
      "createdAt": "2026-05-22T14:35:45.612Z",
      "updatedAt": "2026-05-22T14:36:01.022Z"
    },
    {
      "id": "66400a8f1c2b4d5e6f7aa000",
      "conversationId": "66400a8f1c2b4d5e6f7a9000",
      "senderId": "66400a8f1c2b4d5e6f7a8b01",
      "clientMessageId": "cm_01HZQ7K3M4N5P6Q7R8S9T0V1W2",
      "text": "Hi! Loved your kitchen.",
      "deliveredTo": [],
      "readBy": [
        { "userId": "66400a8f1c2b4d5e6f7a8b00", "at": "2026-05-22T14:35:18.420Z" }
      ],
      "editedAt": null,
      "deletedAt": null,
      "createdAt": "2026-05-22T14:35:12.001Z",
      "updatedAt": "2026-05-22T14:35:18.420Z"
    }
  ]
}

Paging sequence

GET /chat/conversations/<id>/messages
→ 50 newest messages
GET /chat/conversations/<id>/messages?before=<oldest createdAt from prev page>
→ next 50 older messages
...
→ eventually `messages: []` (start of history)

The cursor is exclusive: createdAt < before, never <=. Use the previous page’s oldest createdAt verbatim — you will not get duplicate rows.

Error responses

Status	Code	Meaning
400	`VALIDATION_FAILED`	`before` is not an ISO 8601 datetime, or `limit` is outside 1..200.
401	`UNAUTHENTICATED`	Missing, malformed, or expired access token.
403	`ONBOARDING_INCOMPLETE`	Caller has not finished onboarding.
403	`FORBIDDEN`	Caller is not a participant of this conversation.
404	`NOT_FOUND`	No conversation with that id.

Side effects

None — pure read. Reading a message does not add a readBy receipt; that requires an explicit mark-read call.

curl

# first page
curl -X GET "https://api.swappr.co.uk/api/v1/chat/conversations/66400a8f1c2b4d5e6f7a9000/messages?limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# older page (use oldest createdAt from previous response)
curl -X GET "https://api.swappr.co.uk/api/v1/chat/conversations/66400a8f1c2b4d5e6f7a9000/messages?before=2026-05-22T14:35:12.001Z&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Delete a conversation (delete-for-me)Send a message

​Overview

​Authentication

​Path parameters

​Query parameters

​Request body

​Response — 200 OK

​Message object

​Receipt object

​Example response

​Paging sequence

​Error responses

​Side effects

​See also

​curl