Matrix state bot API

This is a service API for IXO Matrix workflows. It is separate from IXO Protocol gateway APIs.

Overview

• Use this API to read and manage application state events in Matrix rooms.
• Use this API to manage ACL event content for room-level permissions.
• Do not use this page as a source for protocol transaction behavior.

Event shapes

{
  "type": "ixo.room.state",
  "state_key": "unique_identifier",
  "content": {}
}

{
  "type": "ixo.room.state.acl",
  "state_key": "state_event_key",
  "content": {
    "read": ["@user:domain.com"],
    "write": ["@admin:domain.com"]
  }
}

Authentication and endpoints

Troubleshooting

• 403 / ACL denied — Bot token lacks power level or room membership; verify room ID, bot user ID, and ACL event content.
• State event rejected — Invalid state_key, oversized content, or conflicting types; compare with working examples in IXO Matrix.
• Wrong homeserver — Matrix is federation-aware; confirm baseUrl and user IDs match the deployment in Networks and endpoints.
• Rate limits — Back off and batch state updates; see Error handling for generic HTTP retry guidance.

Related references