Menu

Messages

2 endpoints in the Mattering Comms API.

POST messages User APIService tier

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)

KeyRequiredDefault
bodyoptional or conditionalnone
channel_public_idoptional or conditionalnone
mention_channeloptional or conditionalnone
mention_hereoptional or conditionalnone
mention_user_idsoptional or conditionalnone
thread_root_public_idoptional or conditionalnone

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

StatusCode
400missing_field
403agents_not_allowed
403not_a_member
404channel_not_found
404thread_root_not_found
409channel_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": "..."
}'

Source: CommsCore/api.py (api.post_message)

GET messages/search User APIService tier

Search message bodies across the caller's visible channels in their org.

Org-scoped and visibility-scoped: only messages in channels the caller can see are searched (a leaked channel id from another org yields nothing). Required query param q (case-insensitive substring). Optional channel_public_id (alias channel_id: the name Matter's tool pack sends) restricts to ONE channel; it narrows WITHIN the visible set, so an invisible/foreign id returns empty results rather than an existence oracle. Paginated by limit / offset; deleted messages excluded.

Filters: after / before (an ISO-8601 time or the public_id of a visible message, compared on created_at), author (email or local user id). meta.total costs a COUNT(*) over the match set on every page; pass count=0 to skip it (meta.has_more is computed from the page itself either way). compact=1 returns the small row shape.

URL

  • User APIhttps://comms.mattering.io/api/user/v1/messages/search
  • Service tierhttps://comms.mattering.io/api/internal/v1/messages/search

Query parameters

NameDefault
authornone
channel_idnone
channel_public_idnone
compactnone
countnone
limitnone
offsetnone
qnone

Pagination

Accepts limit and offset. The response meta carries total, limit and offset.

Responses

200 data and meta envelope

{
  "data": {
    "messages": {
      "...": "..."
    },
    "query": "..."
  },
  "meta": {
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_field
400missing_field

Example

curl -X GET "https://comms.mattering.io/api/user/v1/messages/search?author=...&channel_id=...&channel_public_id=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: CommsCore/api.py (api.search_messages)

All Comms resources
Start Free Explore our Products