Intents

class mautrix.appservice.IntentAPI

Bases: mautrix.client.StoreUpdatingAPI

IntentAPI is a high-level wrapper around the AppServiceAPI that provides many easy-to-use functions for accessing the client-server API. It is designed for appservices and will automatically handle many things like missing invites using the appservice bot.

__init__(mxid, api, bot=None, state_store=None)

Initialize a ClientAPI. You must either provide the api parameter with an existing mautrix.api.HTTPAPI instance, or provide the base_url and other arguments for creating it as kwargs.

Parameters

  • mxid (mautrix.types.UserID) – The Matrix ID of the user. This is used for things like setting profile metadata. Additionally, the homeserver domain is extracted from this string and used for setting aliases and such. This can be changed later using set_mxid.

  • device_id – The device ID corresponding to the access token used.

  • api (mautrix.appservice.AppServiceAPI) – The mautrix.api.HTTPAPI instance to use. You can also pass the kwargs to create a HTTPAPI instance rather than creating the instance yourself.

  • kwargs – If api is not specified, then the arguments to pass when creating a HTTPAPI.

  • bot (Optional[mautrix.appservice.IntentAPI]) –

  • state_store (Optional[mautrix.appservice.ASStateStore]) –

Return type

None

async appservice_ping(appservice_id, txn_id=None)
Parameters

  • appservice_id (str) –

  • txn_id (Optional[str]) –

Return type

int

async ban_user(room_id, user_id, reason='', extra_content=None)

Ban a user in the room. If the user is currently in the room, also kick them. When a user is banned from a room, they may not join it or be invited to it until they are unbanned. The caller must have the required power level in order to perform this operation.

See also: API reference

Parameters

  • room_id (mautrix.types.RoomID) – The ID of the room from which the user should be banned.

  • user_id (mautrix.types.UserID) – The fully qualified user ID of the user being banned.

  • reason (str) – The reason the user has been kicked. This will be supplied as the reason on the target’s updated m.room.member event.

  • extra_content (Optional[dict[str, mautrix.types.JSON]]) – Additional properties for the ban event content. If a non-empty dict is passed, the ban will be created using the PUT /state/m.room.member/... endpoint instead of POST /ban.

Return type

None

async batch_send(room_id, prev_event_id, *, batch_id=None, events, state_events_at_start=(), beeper_new_messages=False, beeper_mark_read_by=None)

Send a batch of historical events into a room. See MSC2716 for more info.

New in version v0.12.5.

Deprecated since version v0.20.3: MSC2716 was abandoned by upstream and Beeper has forked the endpoint.

Parameters

  • room_id (mautrix.types.RoomID) – The room ID to send the events to.

  • prev_event_id (mautrix.types.EventID) – The anchor event. The batch will be inserted immediately after this event.

  • batch_id (Optional[mautrix.types.BatchID]) – The batch ID for sending a continuation of an earlier batch. If provided, the new batch will be inserted between the prev event and the previous batch.

  • events (Iterable[mautrix.types.BatchSendEvent]) – The events to send.

  • state_events_at_start (Iterable[mautrix.types.BatchSendStateEvent]) – The state events to send at the start of the batch. These will be sent as outlier events, which means they won’t be a part of the actual room state.

  • beeper_new_messages (bool) – Custom flag to tell the server that the messages can be sent to the end of the room as normal messages instead of history.

  • beeper_mark_read_by (Optional[mautrix.types.UserID]) –

Returns

All the event IDs generated, plus a batch ID that can be passed back to this method.

Return type

mautrix.types.BatchSendResponse

async beeper_batch_send(room_id, events, *, forward=False, forward_if_no_messages=False, send_notification=False, mark_read_by=None)

Send a batch of events into a room. Only for Beeper/hungryserv.

New in version v0.20.3.

Parameters

  • room_id (mautrix.types.RoomID) – The room ID to send the events to.

  • events (Iterable[mautrix.types.BatchSendEvent]) – The events to send.

  • forward (bool) – Send events to the end of the room instead of the beginning

  • forward_if_no_messages (bool) – Send events to the end of the room, but only if there are no messages in the room. If there are messages, send the new messages to the beginning.

  • send_notification (bool) – Send a push notification for the new messages. Only applies when sending to the end of the room.

  • mark_read_by (Optional[mautrix.types.UserID]) – Send a read receipt from the given user ID atomically.

Returns

All the event IDs generated.

Return type

mautrix.types.misc.BeeperBatchSendResponse

async beeper_delete_room(room_id)
Parameters

room_id (mautrix.types.RoomID) –

Return type

None

async ensure_joined(room_id, ignore_cache=False, bot=<object object>)

Ensure the user controlled by this intent is joined to the given room.

If the user is not in the room and the room is invite-only or the user is banned, this will first invite and/or unban the user using the bridge bot account.

Parameters

  • room_id (mautrix.types.RoomID) – The room to join.

  • ignore_cache (bool) – Should the Matrix state store be checked first? If False and the store says the user is in the room, no requests will be made.

  • bot (mautrix.appservice.IntentAPI | None) – An optional override account to use as the bridge bot. This is useful if you know the bridge bot is not an admin in the room, but some other ghost user is.

Returns

False if the cache said the user is already in the room, True if the user was successfully added to the room just now.

Return type

bool

async ensure_registered()

Ensure the user controlled by this intent has been registered on the homeserver.

This will always check the state store first, but the M_USER_IN_USE error will also be silently ignored, so it’s fine if the state store isn’t accurate. However, if using double puppeting, the state store should always return True for those users.

Return type

None

async error_and_leave(room_id, text=None, html=None)
Parameters
Return type

None

async get_pinned_messages(room_id)
Parameters

room_id (mautrix.types.RoomID) –

Return type

list[mautrix.types.EventID]

async get_power_levels(room_id, ignore_cache=False, ensure_joined=True)
Parameters
Return type

mautrix.types.PowerLevelStateEventContent

async get_room_avatar_url(room_id, user_id, ignore_cache=False)
Parameters
Return type

str

async get_room_displayname(room_id, user_id, ignore_cache=False)
Parameters
Return type

str

async get_room_member_info(room_id, user_id, ignore_cache=False)
Parameters
Return type

mautrix.types.Member

async get_room_members(room_id, allowed_memberships=(Membership.JOIN,))
Parameters
Return type

list[mautrix.types.UserID]

async invite_user(room_id, user_id, reason=None, check_cache=False, extra_content=None)

Invite a user to participate in a particular room. They do not start participating in the room until they actually join the room.

Only users currently in the room can invite other users to join that room.

If the user was invited to the room, the homeserver will add a m.room.member event to the room.

See also: API reference

Parameters

  • room_id (mautrix.types.RoomID) – The ID of the room to which to invite the user.

  • user_id (mautrix.types.UserID) – The fully qualified user ID of the invitee.

  • reason (Optional[str]) – The reason the user was invited. This will be supplied as the reason on the m.room.member event.

  • check_cache (bool) – If True, the function will first check the state store, and not do anything if the state store says the user is already invited or joined.

  • extra_content (Optional[dict[str, typing.Any]]) – Additional properties for the invite event content. If a non-empty dict is passed, the invite event will be created using the PUT /state/m.room.member/... endpoint instead of POST /invite.

Return type

None

async join_room_by_id(room_id, third_party_signed=None, extra_content=None)

Start participating in a room, i.e. join it by its ID.

See also: API reference

Parameters

  • room_id (mautrix.types.RoomID) – The ID of the room to join.

  • third_party_signed (Optional[mautrix.types.JSON]) – A signature of an m.third_party_invite token to prove that this user owns a third party identity which has been invited to the room.

  • extra_content (Optional[dict[str, mautrix.types.JSON]]) – Additional properties for the join event content. If a non-empty dict is passed, the join event will be created using the PUT /state/m.room.member/... endpoint instead of POST /join.

Returns

The ID of the room the user joined.

Return type

mautrix.types.RoomID

async kick_user(room_id, user_id, reason='', extra_content=None)

Kick a user from the room.

The caller must have the required power level in order to perform this operation.

Kicking a user adjusts the target member’s membership state to be leave with an optional reason. Like with other membership changes, a user can directly adjust the target member’s state by calling EventMethods.send_state_event() with EventType.ROOM_MEMBER as the event type and the user_id as the state key.

See also: API reference

Parameters

  • room_id (mautrix.types.RoomID) – The ID of the room from which the user should be kicked.

  • user_id (mautrix.types.UserID) – The fully qualified user ID of the user being kicked.

  • reason (str) – The reason the user has been kicked. This will be supplied as the reason on the target’s updated m.room.member event.

  • extra_content (Optional[dict[str, mautrix.types.JSON]]) – Additional properties for the kick event content. If a non-empty dict is passed, the kick event will be created using the PUT /state/m.room.member/... endpoint instead of POST /kick.

Return type

None

async leave_room(room_id, reason=None, extra_content=None, raise_not_in_room=False)

Stop participating in a particular room, i.e. leave the room.

If the user was already in the room, they will no longer be able to see new events in the room. If the room requires an invite to join, they will need to be re-invited before they can re-join.

If the user was invited to the room, but had not joined, this call serves to reject the invite.

The user will still be allowed to retrieve history from the room which they were previously allowed to see.

See also: API reference

Parameters

  • room_id (mautrix.types.RoomID) – The ID of the room to leave.

  • reason (Optional[str]) – The reason for leaving the room. This will be supplied as the reason on the updated m.room.member event.

  • extra_content (Optional[dict[str, mautrix.types.JSON]]) – Additional properties for the leave event content. If a non-empty dict is passed, the leave event will be created using the PUT /state/m.room.member/... endpoint instead of POST /leave.

  • raise_not_in_room (bool) – Should errors about the user not being in the room be raised?

Return type

None

async mark_read(room_id, event_id, extra_content=None)
Parameters
Return type

None

async pin_message(room_id, event_id)
Parameters
Return type

None

async redact(room_id, event_id, reason=None, extra_content=None, **kwargs)

Send an event to redact a previous event.

Redacting an event strips all information out of an event which isn’t critical to the integrity of the server-side representation of the room.

This cannot be undone.

Users may redact their own events, and any user with a power level greater than or equal to the redact power level of the room may redact events there.

See also: API reference

Parameters
Returns

The ID of the event that was sent to redact the other event.

Return type

mautrix.types.EventID

async send_message_event(room_id, event_type, content, **kwargs)

Send a message event to a room. Message events allow access to historical events and pagination, making them suited for “once-off” activity in a room.

See also: API reference

Parameters

  • room_id (mautrix.types.RoomID) – The ID of the room to send the message to.

  • event_type (mautrix.types.EventType) – The type of message to send.

  • content (mautrix.types.EventContent) – The content to send.

  • txn_id – The transaction ID to use. If not provided, a random ID will be generated.

  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method. Used by IntentAPI to pass the timestamp massaging field to AppServiceAPI.request().

Returns

The ID of the event that was sent.

Return type

mautrix.types.EventID

async send_state_event(room_id, event_type, content, state_key='', **kwargs)

Send a state event to a room. State events with the same room_id, event_type and state_key will be overridden.

See also: API reference

Parameters

  • room_id (RoomID) – The ID of the room to set the state in.

  • event_type (EventType) – The type of state to send.

  • content (StateEventContent | dict[str, JSON]) – The content to send.

  • state_key (str) – The key for the state to send. Defaults to empty string.

  • ensure_joined – Used by IntentAPI to determine if it should ensure the user is joined before sending the event.

  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method. Used by IntentAPI to pass the timestamp massaging field to AppServiceAPI.request().

Returns

The ID of the event that was sent.

Return type

EventID

async set_join_rule(room_id, join_rule, **kwargs)
Parameters
set_pinned_messages(room_id, events, **kwargs)
Parameters
Return type

Awaitable[mautrix.types.EventID]

async set_power_levels(room_id, content, **kwargs)
Parameters
Return type

mautrix.types.EventID

async set_presence(presence=PresenceState.ONLINE, status=None, ignore_cache=False)

Set the online status of the user.

See also: API reference

Parameters

  • presence (mautrix.types.PresenceState) – The online status of the user.

  • status (Optional[str]) – The status message.

  • ignore_cache (bool) – Whether to set presence even if the cache says the presence is already set to that value.

set_room_avatar(room_id, avatar_url, **kwargs)
Parameters
Return type

Awaitable[mautrix.types.EventID]

set_room_name(room_id, name, **kwargs)
Parameters
Return type

Awaitable[mautrix.types.EventID]

set_room_topic(room_id, topic, **kwargs)
Parameters
Return type

Awaitable[mautrix.types.EventID]

async set_typing(room_id, timeout=0)

This tells the server that the user is typing for the next N milliseconds where N is the value specified in the timeout key. If the timeout is equal to or less than zero, it tells the server that the user has stopped typing.

See also: API reference

Parameters

  • room_id (mautrix.types.RoomID) – The ID of the room in which the user is typing.

  • timeout (int) – The length of time in milliseconds to mark this user as typing.

Return type

None

async unban_user(room_id, user_id, reason='', extra_content=None)

Unban a user from the room. This allows them to be invited to the room, and join if they would otherwise be allowed to join according to its join rules. The caller must have the required power level in order to perform this operation.

See also: API reference

Parameters

  • room_id (mautrix.types.RoomID) – The ID of the room from which the user should be unbanned.

  • user_id (mautrix.types.UserID) – The fully qualified user ID of the user being banned.

  • reason (str) – The reason the user has been unbanned. This will be supplied as the reason on the target’s updated m.room.member event.

  • extra_content (Optional[dict[str, mautrix.types.JSON]]) – Additional properties for the unban (leave) event content. If a non-empty dict is passed, the unban will be created using the PUT /state/m.room.member/... endpoint instead of POST /unban.

Return type

None

async unpin_message(room_id, event_id)
Parameters
user(user_id, token=None, base_url=None, as_token=False)

Get the intent API for a specific user. This is just a proxy to AppServiceAPI.intent().

You should only call this method for the bot user. Calling it with child intent APIs will result in a warning log.

Parameters

  • user_id (mautrix.types.UserID) – The Matrix ID of the user whose intent API to get.

  • token (Optional[str]) – The access token to use for the Matrix ID.

  • base_url (Optional[str]) – An optional URL to use for API requests.

  • as_token (bool) – Whether the provided token is actually another as_token (meaning the user_id query parameter needs to be used).

Returns

The IntentAPI for the given user.

Return type

mautrix.appservice.IntentAPI

api: as_api.AppServiceAPI
state_store: ss.ASStateStore
bot: IntentAPI
log: TraceLogger