Messaging

Admin-side messaging covers stats, listing conversations + messages, moderating individual messages, and server-side membership management — creating conversations and adding/removing participants without a client session. This is the path a server-side matchmaker uses to grow a conversation's membership over time (e.g. an "anonymous chat with your matches" circle that gains members as they qualify). The user-facing write path lives under /client/messaging/*.

Endpoints

Method	Path	Description
POST	`/admin/projects/:projectId/messaging/conversations`	Create a conversation (zero or more participants).
GET	`/admin/projects/:projectId/messaging/conversations`	Paginated conversations with participant count.
POST	`/admin/projects/:projectId/messaging/conversations/:conversationId/participants`	Add a participant (idempotent).
DELETE	`/admin/projects/:projectId/messaging/conversations/:conversationId/participants/:userId`	Remove a participant (idempotent).
GET	`/admin/projects/:projectId/messaging/stats`	Aggregate conversation and message counts.
GET	`/admin/projects/:projectId/messaging/conversations/:conversationId/messages`	Paginated messages with sender info.
DELETE	`/admin/projects/:projectId/messaging/messages/:messageId`	Hard-delete a message.

POST /admin/projects/:projectId/messaging/conversations

Create a conversation server-side. Unlike the client create path, this allows zero or more initial participants — a matchmaker can create an empty circle and populate it over time via the add-participant endpoint as users qualify.

Request

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

Response 201

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

Errors

400 INVALID_PAYLOAD — bad type / name / participant_ids.
422 USER_NOT_FOUND — a supplied participant id is not a registered user.
500 CREATE_FAILED.

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations

developer auth

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations'

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

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/messaging/conversations' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "group", "name": "Circle" }'

POST /admin/projects/:projectId/messaging/conversations/:conversationId/participants

Add a user to a conversation. Idempotent — re-adding an existing member is a no-op that returns already_member: true. Once added, the user can read, send, and receive messages immediately (membership is the delivery gate). This is the matchmaker primitive: as each user qualifies, the server adds them to the circle's conversation.

Request

Field	Type	Required	Notes
`user_id`	uuid	yes	The user to add. `app_user_id` accepted.

Response 200

{
  "data": { "id": "…", "conversation_id": "…", "app_user_id": "…", "joined_at": "…" },
  "already_member": false
}

Errors

400 INVALID_CONVERSATION_ID / 400 INVALID_PAYLOAD.
404 CONVERSATION_NOT_FOUND — conversation does not exist.
404 USER_NOT_FOUND — user_id is not a registered user.

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations/%7B%7BconversationId%7D%7D/participants

developer auth

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations/%7B%7BconversationId%7D%7D/participants'

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

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/messaging/conversations/{conversationId}/participants' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "user_id": "…" }'

DELETE /admin/projects/:projectId/messaging/conversations/:conversationId/participants/:userId

Remove a user from a conversation. Idempotent — removing a non-member returns removed: false.

Response 200

{ "data": { "removed": true } }

Errors

400 INVALID_CONVERSATION_ID / 400 INVALID_PAYLOAD.
404 CONVERSATION_NOT_FOUND — conversation does not exist.

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations/%7B%7BconversationId%7D%7D/participants/%7B%7BuserId%7D%7D

developer auth

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations/%7B%7BconversationId%7D%7D/participants/%7B%7BuserId%7D%7D'

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

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/messaging/conversations/{conversationId}/participants/{userId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/messaging/stats

Response 200

{
  "data": {
    "total_conversations": 1234,
    "total_messages": 54321,
    "active_conversations_24h": 42
  }
}

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/messaging/stats

developer auth

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/messaging/stats'

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

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/messaging/stats' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/messaging/conversations

Query

Param	Default
`limit`	50
`offset`	0

Response 200

{
  "data": [{ "id": "…", "type": "…", "created_at": "…", "participant_count": 3 }],
  "total": 100,
  "offset": 0,
  "limit": 50
}

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations

developer auth

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations'

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

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/messaging/conversations' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/messaging/conversations/:conversationId/messages

Paginated messages, newest first, with each row carrying inlined sender display info.

Response 200

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

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/messaging/conversations/%7B%7BconversationId%7D%7D/messages

developer auth

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/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}/admin/projects/{projectId}/messaging/conversations/{conversationId}/messages' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

DELETE /admin/projects/:projectId/messaging/messages/:messageId

{ "data": { "deleted": true } }

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/messaging/messages/%7B%7BmessageId%7D%7D

developer auth

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/messaging/messages/%7B%7BmessageId%7D%7D'

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

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/messaging/messages/{messageId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

On this page