数据模型（Model）

Matrix 适配器内部使用 Pydantic 模型表示 API 请求和响应的数据结构。以下列举最重要的类型。

class nonebot.adapters.matrix.api.model.AccountData(**data)[源代码]

基类：MatrixBaseModel

参数:
events: list[RawMatrixEvent]
class nonebot.adapters.matrix.api.model.CreateRoomResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
room_id: RoomId
class nonebot.adapters.matrix.api.model.DeviceLists(**data)[源代码]

基类：MatrixBaseModel

参数:
changed: list[UserId]
left: list[UserId]
nonebot.adapters.matrix.api.model.EncryptedEventContent

MegolmEncryptedEventContent 的别名

class nonebot.adapters.matrix.api.model.EventIdResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
event_id: EventId
class nonebot.adapters.matrix.api.model.File(**data)[源代码]

基类：MatrixBaseModel

参数:

  • filename (str)

  • content (bytes)

  • content_type (str | None)

  • extra_data (Any)

filename: str
content: bytes
content_type: str | None
class nonebot.adapters.matrix.api.model.ForwardedRoomKeyContent(**data)[源代码]

基类：MatrixBaseModel

m.forwarded_room_key to-device 消息的内容。

包含额外的转发链信息。

参数:

  • algorithm (str)

  • room_id (str)

  • session_id (str)

  • session_key (str)

  • sender_key (str)

  • sender_claimed_ed25519_key (str)

  • forwarding_curve25519_chain (list[str])

  • extra_data (Any)

algorithm: str
room_id: str
session_id: str
session_key: str
sender_key: str
sender_claimed_ed25519_key: str
forwarding_curve25519_chain: list[str]
class nonebot.adapters.matrix.api.model.InvitedRoomSync(**data)[源代码]

基类：MatrixBaseModel

参数:
invite_state: State
class nonebot.adapters.matrix.api.model.JoinRoomResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
room_id: RoomId
class nonebot.adapters.matrix.api.model.JoinedRoomSync(**data)[源代码]

基类：MatrixBaseModel

参数:
timeline: Timeline
state: State
ephemeral: Ephemeral
account_data: AccountData
summary: dict[str, Any] | None
unread_notifications: dict[str, Any] | None
class nonebot.adapters.matrix.api.model.LeaveRoomResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
room_id: RoomId | None
class nonebot.adapters.matrix.api.model.LeftRoomSync(**data)[源代码]

基类：MatrixBaseModel

参数:
timeline: Timeline
state: State
account_data: AccountData
class nonebot.adapters.matrix.api.model.LoginFlow(**data)[源代码]

基类：MatrixBaseModel

参数:
type: str
class nonebot.adapters.matrix.api.model.LoginFlowsResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
flows: list[LoginFlow]
class nonebot.adapters.matrix.api.model.LoginIdentifier(**data)[源代码]

基类：MatrixBaseModel

参数:

  • type (str)

  • user (str | None)

  • medium (str | None)

  • address (str | None)

  • country (str | None)

  • phone (str | None)

  • extra_data (Any)

type: str
user: str | None
medium: str | None
address: str | None
country: str | None
phone: str | None
class nonebot.adapters.matrix.api.model.LoginResponse(**data)[源代码]

基类：MatrixBaseModel

参数:

  • user_id (UserId)

  • access_token (str | None)

  • device_id (str | None)

  • well_known (dict[str, Any] | None)

  • expires_in_ms (int | None)

  • refresh_token (str | None)

  • extra_data (Any)

user_id: UserId
access_token: str | None
device_id: DeviceId | None
well_known: dict[str, Any] | None
expires_in_ms: int | None
refresh_token: str | None
class nonebot.adapters.matrix.api.model.MatrixBaseModel(**data)[源代码]

基类：BaseModel

参数:

extra_data (Any)

class nonebot.adapters.matrix.api.model.MatrixError(**data)[源代码]

基类：MatrixBaseModel

参数:

  • errcode (str | None)

  • error (str | None)

  • retry_after_ms (int | None)

  • extra_data (Any)

errcode: str | None
error: str | None
retry_after_ms: int | None
class nonebot.adapters.matrix.api.model.MediaConfigResponse(**data)[源代码]

基类：MatrixBaseModel

参数:

  • upload_size (int | None)

  • extra_data (Any)

upload_size: int | None
class nonebot.adapters.matrix.api.model.MegolmEncryptedEventContent(**data)[源代码]

基类：MatrixBaseModel

Room m.megolm.v1.aes-sha2 event content.

参数:

  • algorithm (str)

  • ciphertext (str)

  • sender_key (str)

  • session_id (str)

  • device_id (str | None)

  • extra_data (Any)

algorithm: str
ciphertext: str
sender_key: str
session_id: str
device_id: str | None
class nonebot.adapters.matrix.api.model.MembersChunkResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
chunk: list[RawMatrixEvent]
class nonebot.adapters.matrix.api.model.MessagesResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
chunk: list[RawMatrixEvent]
start: str | None
end: str | None
state: list[RawMatrixEvent]
class nonebot.adapters.matrix.api.model.OlmEncryptedEventContent(**data)[源代码]

基类：MatrixBaseModel

To-device m.olm.v1.curve25519-aes-sha2 event content.

参数:
algorithm: str
sender_key: str
ciphertext: dict[str, dict[str, Any]]
class nonebot.adapters.matrix.api.model.PasswordLoginRequest(**data)[源代码]

基类：MatrixBaseModel

参数:

  • type (str)

  • identifier (LoginIdentifier | None)

  • user (str | None)

  • password (str)

  • device_id (str | None)

  • initial_device_display_name (str | None)

  • refresh_token (bool | None)

  • extra_data (Any)

type: str
identifier: LoginIdentifier | None
user: str | None
password: str
device_id: DeviceId | None
initial_device_display_name: str | None
refresh_token: bool | None
class nonebot.adapters.matrix.api.model.PresenceSync(**data)[源代码]

基类：MatrixBaseModel

参数:
events: list[RawMatrixEvent]
class nonebot.adapters.matrix.api.model.RawMatrixEvent(**data)[源代码]

基类：MatrixBaseModel

参数:
type: str
content: dict[str, Any]
event_id: EventId | None
sender: UserId | None
room_id: RoomId | None
origin_server_ts: int | None
state_key: str | None
redacts: EventId | None
unsigned: UnsignedData | dict[str, Any] | None
class nonebot.adapters.matrix.api.model.ReactionContent(**data)[源代码]

基类：MatrixBaseModel

参数:
relates_to: ReactionRelation
class nonebot.adapters.matrix.api.model.ReactionRelation(**data)[源代码]

基类：MatrixBaseModel

参数:
rel_type: str
event_id: EventId
key: str
nonebot.adapters.matrix.api.model.ReceiptContent

dict[str, dict[str, dict[UserId, ReceiptThread | dict[str, Any]]]] 的别名

class nonebot.adapters.matrix.api.model.ReceiptThread(**data)[源代码]

基类：MatrixBaseModel

参数:

  • ts (int | None)

  • thread_id (str | None)

  • extra_data (Any)

ts: int | None
thread_id: str | None
class nonebot.adapters.matrix.api.model.RedactionContent(**data)[源代码]

基类：MatrixBaseModel

参数:

  • reason (str | None)

  • extra_data (Any)

reason: str | None
class nonebot.adapters.matrix.api.model.RefreshTokenRequest(**data)[源代码]

基类：MatrixBaseModel

参数:

  • refresh_token (str)

  • extra_data (Any)

refresh_token: str
class nonebot.adapters.matrix.api.model.RefreshTokenResponse(**data)[源代码]

基类：MatrixBaseModel

参数:

  • access_token (str | None)

  • refresh_token (str | None)

  • expires_in_ms (int | None)

  • extra_data (Any)

access_token: str | None
refresh_token: str | None
expires_in_ms: int | None
class nonebot.adapters.matrix.api.model.RelationsResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
chunk: list[RawMatrixEvent]
next_batch: str | None
prev_batch: str | None
class nonebot.adapters.matrix.api.model.RoomKeyContent(**data)[源代码]

基类：MatrixBaseModel

m.room_key to-device 消息的内容。

用于在设备间共享 Megolm 会话密钥。

参数:

  • algorithm (str)

  • room_id (str)

  • session_id (str)

  • session_key (str)

  • sender_key (str | None)

  • sender_claimed_ed25519_key (str | None)

  • forwarding_curve25519_key_chain (list[str])

  • extra_data (Any)

algorithm: str
room_id: str
session_id: str
session_key: str
sender_key: str | None
sender_claimed_ed25519_key: str | None
forwarding_curve25519_key_chain: list[str]
class nonebot.adapters.matrix.api.model.RoomMemberContent(**data)[源代码]

基类：MatrixBaseModel

参数:

  • membership (str)

  • displayname (str | None)

  • avatar_url (MxcUri | str | None)

  • reason (str | None)

  • is_direct (bool | None)

  • extra_data (Any)

membership: str
displayname: str | None
avatar_url: MxcUri | str | None
reason: str | None
is_direct: bool | None
class nonebot.adapters.matrix.api.model.RoomMessageContent(**data)[源代码]

基类：MatrixBaseModel

参数:
msgtype: str
body: str
format: str | None
formatted_body: str | None
url: MxcUri | str | None
info: dict[str, Any] | None
relates_to: dict[str, Any] | None
mentions: dict[str, Any] | None
class nonebot.adapters.matrix.api.model.RoomStateResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
events: list[RawMatrixEvent]
class nonebot.adapters.matrix.api.model.RoomsSync(**data)[源代码]

基类：MatrixBaseModel

参数:
join: dict[RoomId, JoinedRoomSync]
invite: dict[RoomId, InvitedRoomSync]
leave: dict[RoomId, LeftRoomSync]
class nonebot.adapters.matrix.api.model.State(**data)[源代码]

基类：MatrixBaseModel

参数:
events: list[RawMatrixEvent]
class nonebot.adapters.matrix.api.model.SyncResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
next_batch: str
rooms: RoomsSync
presence: PresenceSync
account_data: AccountData
device_lists: DeviceLists | None
to_device: AccountData | None
device_one_time_keys_count: dict[str, int]
device_unused_fallback_key_types: list[str] | None
class nonebot.adapters.matrix.api.model.Timeline(**data)[源代码]

基类：MatrixBaseModel

参数:
events: list[RawMatrixEvent]
limited: bool | None
prev_batch: str | None
class nonebot.adapters.matrix.api.model.TypingContent(**data)[源代码]

基类：MatrixBaseModel

参数:
user_ids: list[UserId]
typing: bool | None
timeout: int | None
class nonebot.adapters.matrix.api.model.UnsignedData(**data)[源代码]

基类：MatrixBaseModel

参数:
age: int | None
membership: str | None
prev_content: dict[str, Any] | None
redacted_because: dict[str, Any] | None
transaction_id: str | None
relations: dict[str, Any] | None
class nonebot.adapters.matrix.api.model.UploadResponse(**data)[源代码]

基类：MatrixBaseModel

参数:
content_uri: MxcUri
class nonebot.adapters.matrix.api.model.WhoamiResponse(**data)[源代码]

基类：MatrixBaseModel

参数:

  • user_id (UserId)

  • device_id (str | None)

  • is_guest (bool | None)

  • extra_data (Any)

user_id: UserId
device_id: DeviceId | None
is_guest: bool | None

类型工具

nonebot.adapters.matrix.api.types.DeviceId

str 的别名

class nonebot.adapters.matrix.api.types.EventId(value)[源代码]

基类：MatrixId

参数:

value (str)

返回类型:

Self

sigil: str = '$'
nonebot.adapters.matrix.api.types.EventType

str 的别名

class nonebot.adapters.matrix.api.types.MatrixId(value)[源代码]

基类：str

参数:

value (str)

返回类型:

Self

sigil: str = ''
nonebot.adapters.matrix.api.types.MessageType

str 的别名

class nonebot.adapters.matrix.api.types.MxcUri(value)[源代码]

基类：str

参数:

value (str)

返回类型:

Self

nonebot.adapters.matrix.api.types.PresenceState

str 的别名

nonebot.adapters.matrix.api.types.ReceiptType

str 的别名

class nonebot.adapters.matrix.api.types.RoomAlias(value)[源代码]

基类：MatrixId

参数:

value (str)

返回类型:

Self

sigil: str = '#'
class nonebot.adapters.matrix.api.types.RoomId(value)[源代码]

基类：MatrixId

参数:

value (str)

返回类型:

Self

sigil: str = '!'
nonebot.adapters.matrix.api.types.TxnId

str 的别名

class nonebot.adapters.matrix.api.types.UserId(value)[源代码]

基类：MatrixId

参数:

value (str)

返回类型:

Self

sigil: str = '@'
nonebot.adapters.matrix.api.types.is_not_unset(value)[源代码]
返回类型:

bool

参数:

value (object)

nonebot.adapters.matrix.api.types.is_unset(value)[源代码]
返回类型:

bool

参数:

value (object)

核心模型

Sync 相关

  • SyncResponse — /sync 的完整响应，包含 next_batch 和 rooms。

  • RoomsSync — 顶层 rooms 分组（join / invite / leave）。

  • JoinedRoomSync — 已加入房间的同步数据（state / timeline / ephemeral）。

  • InvitedRoomSync — 邀请状态房间数据（含 invite_state）。

  • LeftRoomSync — 已离开房间的同步数据。

  • Timeline — 时间线事件列表。

  • State — 状态事件列表。

  • AccountData — 账户数据事件列表。

  • DeviceLists — 设备列表变更。

事件与内容模型

  • RawMatrixEvent — 从 API 响应的原始事件表示。

  • RoomMessageContent — m.room.message 的消息体。

  • RoomMemberContent — m.room.member 的成员信息。

  • ReactionContent / ReactionRelation — m.reaction 的内容和关系。

  • RedactionContent — 消息撤回内容。

  • TypingContent — 输入状态内容。

  • ReceiptContent / ReceiptThread — 已读回执内容。

API 响应

  • EventIdResponse — PUT /send 等端点的返回值，包含 event_id。

  • UploadResponse — 媒体上传的返回值，包含 content_uri。

  • WhoamiResponse — /account/whoami 的响应。

  • LoginResponse — 登录响应。

  • LoginFlowsResponse — 支持的登录流程。

  • RefreshTokenResponse — Token 刷新响应。

  • JoinRoomResponse — 加入房间响应。

  • MembersChunkResponse — 成员列表响应。

  • MessagesResponse — 消息分页响应。

  • RelationsResponse — 关系事件响应。

  • MediaConfigResponse — 媒体仓库配置。

常用类型别名

  • UserId — 用户 ID（如 @alice:example.org）

  • RoomId — 房间 ID（如 !abc123:example.org）

  • RoomAlias — 房间别名（如 #general:example.org）

  • RoomIdentifier — RoomId | RoomAlias

  • EventId — 事件 ID

  • EventType — str，事件类型字符串

  • TxnId — str，事务 ID

  • DeviceId — str，设备 ID

  • MxcUri — str，Matrix Content URI

  • PresenceState — "online" | "offline" | "unavailable"

  • ReceiptType — "m.read" | "m.read.private"

  • UNSET — 哨兵值，表示字段未设置

异常

exception nonebot.adapters.matrix.exception.MatrixAdapterException[源代码]

基类：AdapterException

返回类型:

None

exception nonebot.adapters.matrix.exception.NoLogException[源代码]

基类：NoLogException, MatrixAdapterException

返回类型:

None

exception nonebot.adapters.matrix.exception.ActionFailed(response)[源代码]

基类：ActionFailed, MatrixAdapterException

参数:

response (Response)

返回类型:

None

exception nonebot.adapters.matrix.exception.InteractiveAuthRequired(response)[源代码]

基类：ActionFailed

A resumable UIA or OAuth authorization challenge, not token expiry.

参数:

response (Response)

返回类型:

None

exception nonebot.adapters.matrix.exception.UnauthorizedException(response)[源代码]

基类：ActionFailed

参数:

response (Response)

返回类型:

None

exception nonebot.adapters.matrix.exception.RateLimitException(response)[源代码]

基类：ActionFailed

参数:

response (Response)

返回类型:

None

exception nonebot.adapters.matrix.exception.NetworkError(msg=None)[源代码]

基类：NetworkError, MatrixAdapterException

参数:

msg (str | None)

返回类型:

None

exception nonebot.adapters.matrix.exception.ApiNotAvailable[源代码]

基类：ApiNotAvailable, MatrixAdapterException

返回类型:

None