List my conversations (inbox)
curl --request GET \
--url https://api.example.com/api/v1/chat/conversationsimport requests
url = "https://api.example.com/api/v1/chat/conversations"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/chat/conversations', 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",
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"
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")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/chat/conversations")
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_bodyChat
List my conversations (inbox)
Returns the authenticated user’s conversations sorted by recent activity.
GET
/
api
/
v1
/
chat
/
conversations
List my conversations (inbox)
curl --request GET \
--url https://api.example.com/api/v1/chat/conversationsimport requests
url = "https://api.example.com/api/v1/chat/conversations"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/chat/conversations', 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",
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"
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")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/chat/conversations")
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_bodyOverview
Returns every conversation the caller is a participant of, sorted bylastMessageAt descending (newest activity first), with _id descending as the tie-breaker so the order is stable across pages. This is the inbox feed.
A conversation with lastMessage: null (handshake created but no message yet) sorts at the bottom — the secondary _id sort keeps it at a deterministic position. The mobile client typically renders these as “Say hi — you matched with X” placeholders.
Conversations are returned as full documents (same shape as Get conversation) so the inbox can render last-message previews, unread badges, and timestamps without a follow-up call per row.
Authentication
Bearer <accessToken> required. requireOnboarded middleware applied — half-onboarded users hit 403 ONBOARDING_INCOMPLETE.
Path parameters
None.Query parameters
| Name | Type | Required | Default | Notes | Example |
|---|---|---|---|---|---|
limit | integer | no | 50 | 1..50 inclusive. Phase 4 returns the full inbox at once; cursor paging lands in Phase 5 when inboxes are expected to outgrow the default. | 20 |
The Phase 4 implementation does not yet accept a cursor — the entire inbox is returned in one page up to
limit rows. Adding ?cursor= will be additive in Phase 5 and will not break callers that ignore it.Request body
None.Response — 200 OK
| Field | Type | Notes | Example |
|---|---|---|---|
conversations | object[] | Array of conversation rows, sorted by lastMessageAt desc, _id desc. Empty array ([]) if the caller has no conversations. |
Example response
{
"conversations": [
{
"id": "66400a8f1c2b4d5e6f7a9000",
"matchId": "66400a8f1c2b4d5e6f7a8e00",
"participantIds": [
"66400a8f1c2b4d5e6f7a8b00",
"66400a8f1c2b4d5e6f7a8b01"
],
"lastMessage": {
"text": "Hi! Loved your kitchen.",
"senderId": "66400a8f1c2b4d5e6f7a8b01",
"sentAt": "2026-05-22T14:35:12.001Z"
},
"lastMessageAt": "2026-05-22T14:35:12.001Z",
"participantState": [
{
"userId": "66400a8f1c2b4d5e6f7a8b00",
"unreadCount": 1,
"lastReadMessageId": null,
"mutedAt": null,
"blockedAt": null
},
{
"userId": "66400a8f1c2b4d5e6f7a8b01",
"unreadCount": 0,
"lastReadMessageId": null,
"mutedAt": null,
"blockedAt": null
}
],
"status": "ACTIVE", // enum: "ACTIVE" | "ARCHIVED" | "BLOCKED"
"createdAt": "2026-05-22T14:32:08.412Z",
"updatedAt": "2026-05-22T14:35:12.001Z",
"peer": {
"id": "66400a8f1c2b4d5e6f7a8b01",
"firstName": "Bob",
"avatarUrl": "https://cdn.swappr.co.uk/avatars/bob.jpg"
},
"property": {
"id": "66400a8f1c2b4d5e6f7a8c01",
"address": "12 Camden High St",
"postcode": "NW1 0JH",
"coverUrl": "https://cdn.swappr.co.uk/homes/cover.jpg"
}
},
{
"id": "66400a8f1c2b4d5e6f7a9001",
"matchId": "66400a8f1c2b4d5e6f7a8e01",
"participantIds": [
"66400a8f1c2b4d5e6f7a8b00",
"66400a8f1c2b4d5e6f7a8b02"
],
"lastMessage": null,
"lastMessageAt": null,
"participantState": [
{ "userId": "66400a8f1c2b4d5e6f7a8b00", "unreadCount": 0, "lastReadMessageId": null, "mutedAt": null, "blockedAt": null },
{ "userId": "66400a8f1c2b4d5e6f7a8b02", "unreadCount": 0, "lastReadMessageId": null, "mutedAt": null, "blockedAt": null }
],
"status": "ACTIVE",
"createdAt": "2026-05-22T13:00:00.000Z",
"updatedAt": "2026-05-22T13:00:00.000Z",
"peer": {
"id": "66400a8f1c2b4d5e6f7a8b02",
"firstName": "Carol",
"avatarUrl": null
},
"property": {
"id": "66400a8f1c2b4d5e6f7a8c02",
"address": "5 Hackney Rd",
"postcode": "E2 7NX",
"coverUrl": "https://cdn.swappr.co.uk/homes/cover2.jpg"
}
}
]
}
Each conversation embeds an enriched
peer (firstName + avatar) and property (the peer’s listing — cover photo + address) so the inbox renders a name, avatar, and property thumbnail per row without a follow-up call. See the Conversation object for the full field reference. peer / property may be null if the underlying user / listing has been deleted.Error responses
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED | Missing, malformed, or expired access token. |
| 403 | ONBOARDING_INCOMPLETE | Caller has not finished onboarding. |
Side effects
None — pure read.See also
- Get conversation — single-row variant with the same shape.
- Match → Conversation handshake — how a row gets into this list.
- Socket events — to keep the inbox live the client should listen for
chat:message:newand re-sort.
curl
curl -X GET "https://api.swappr.co.uk/api/v1/chat/conversations" \
-H "Authorization: Bearer $ACCESS_TOKEN"