Post a message to a channel the caller can post to.
Body (JSON): channel_public_id (required), body (required, non-empty unless a reply flag is given), thread_root_public_id (optional: reply into a thread), mention_user_ids (optional list), mention_channel / mention_here (optional bools). The channel is resolved fail-closed; a caller must additionally be a MEMBER to post (public channels are readable but not postable without joining). Reuses the model create_message so the per-channel seq allocation and mention materialization are identical to the websocket path. Returns the created message.
URL
- User APIhttps://comms.mattering.io/api/user/v1/messages
- Service tierhttps://comms.mattering.io/api/internal/v1/messages
Body keys (JSON)
| Key | Required | Default |
|---|---|---|
body | optional or conditional | none |
channel_public_id | optional or conditional | none |
mention_channel | optional or conditional | none |
mention_here | optional or conditional | none |
mention_user_ids | optional or conditional | none |
thread_root_public_id | optional or conditional | none |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
201 data and meta envelope
{
"data": {
"message": {
"public_id": "...",
"channel_public_id": "...",
"seq": 0,
"body": "...",
"author": {
"id": "...",
"name": "..."
},
"thread_root_public_id": "...",
"reply_count": 0,
"mentions": [
"..."
],
"mention_channel": "...",
"mention_here": "...",
"created_at": "2026-01-01T00:00:00Z",
"edited_at": "2026-01-01T00:00:00Z",
"deleted_at": "2026-01-01T00:00:00Z"
}
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
|---|---|
| 400 | missing_field |
| 403 | agents_not_allowed |
| 403 | not_a_member |
| 404 | channel_not_found |
| 404 | thread_root_not_found |
| 409 | channel_archived |
Example
curl -X POST "https://comms.mattering.io/api/user/v1/messages" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"body": "...",
"channel_public_id": "...",
"mention_channel": "...",
"mention_here": "...",
"mention_user_ids": "...",
"thread_root_public_id": "..."
}'curl -X POST "https://comms.mattering.io/api/internal/v1/messages" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"body": "...",
"channel_public_id": "...",
"mention_channel": "...",
"mention_here": "...",
"mention_user_ids": "...",
"thread_root_public_id": "..."
}'
Source: CommsCore/api.py (api.post_message)