Messaging

Direct conversations are deduplicated — creating a direct conversation with the same two participants returns the existing row instead of a new one. Participation is enforced on every read / write.

Source: apps/api/src/routes/client/messaging.ts.

Endpoints

Method	Path	Description
POST	`/client/messaging/conversations`	Create or return an existing direct conversation.
GET	`/client/messaging/conversations`	Caller's conversations with participant list.
POST	`/client/messaging/conversations/:conversationId/messages`	Send a message.
GET	`/client/messaging/conversations/:conversationId/messages`	Paginated message list.
POST	`/client/messaging/conversations/:conversationId/read`	Update `last_read_at`.

POST /client/messaging/conversations

Direct conversations with one participant_ids entry are deduplicated.

Request (`CreateConversationInput`)

Field	Type	Required	Default
`type`	`"direct" \| "group"`	no	`"direct"`
`name`	string	no	null
`participant_ids`	uuid[]	yes	—

The caller is auto-added to participant_ids — no need to include yourself.

Response 201 (created) / 200 (existing direct)

{ "data": { "id": "…", "type": "direct", "name": null, "created_at": "…" } }

Errors

500 CREATE_FAILED.

Try it:

POST/client/messaging/conversations

client auth

curl -X POST 'https://api.amba.dev/client/messaging/conversations'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/messaging/conversations' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /client/messaging/conversations

Caller's conversations, ordered by updated_at DESC, with a conversation_participants array that includes each participant's display info.

Query

Param	Default
`limit`	20
`offset`	0

Response 200

{
  "data": [
    {
      "id": "…",
      "type": "direct",
      "conversation_participants": [
        { "app_user_id": "…", "app_users": { "id": "…", "display_name": "…", "avatar_url": "…" } }
      ]
    }
  ],
  "total": 10,
  "offset": 0,
  "limit": 20
}

Try it:

GET/client/messaging/conversations

client auth

curl -X GET 'https://api.amba.dev/client/messaging/conversations'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/messaging/conversations' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

POST /client/messaging/conversations/:conversationId/messages

Request (`SendMessageInput`)

Field	Type	Required	Default
`body`	string	yes	—
`message_type`	string	no	`"text"`
`metadata`	object	no	`{}`

Response 201

{
  "data": {
    "id": "…",
    "conversation_id": "…",
    "sender_id": "…",
    "body": "…",
    "message_type": "text",
    "created_at": "…"
  }
}

Errors

403 NOT_A_PARTICIPANT.
500 SEND_FAILED.

Try it:

POST/client/messaging/conversations/%7B%7BconversationId%7D%7D/messages

client auth

curl -X POST 'https://api.amba.dev/client/messaging/conversations/%7B%7BconversationId%7D%7D/messages'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/messaging/conversations/{conversationId}/messages' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /client/messaging/conversations/:conversationId/messages

Messages in the conversation with sender info, newest first.

Query

Param	Default
`limit`	50
`offset`	0

Response 200

{
  "data": [
    {
      "id": "…",
      "body": "…",
      "created_at": "…",
      "sender": { "id": "…", "display_name": "…", "avatar_url": "…" }
    }
  ],
  "total": 100,
  "offset": 0,
  "limit": 50
}

Errors

403 NOT_A_PARTICIPANT.

Try it:

GET/client/messaging/conversations/%7B%7BconversationId%7D%7D/messages

client auth

curl -X GET 'https://api.amba.dev/client/messaging/conversations/%7B%7BconversationId%7D%7D/messages'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/messaging/conversations/{conversationId}/messages' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

POST /client/messaging/conversations/:conversationId/read

Stamp the caller's conversation_participants.last_read_at = now().

Response 200

Updated participant row.

Errors

404 UPDATE_FAILED — caller is not a participant.
500 UPDATE_FAILED.

Try it:

POST/client/messaging/conversations/%7B%7BconversationId%7D%7D/read

client auth

curl -X POST 'https://api.amba.dev/client/messaging/conversations/%7B%7BconversationId%7D%7D/read'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/messaging/conversations/{conversationId}/read' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

On this page