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 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 (Optional[mautrix.appservice.IntentAPI]) – 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)
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, 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.

  • check_cache (bool) – Whether or not the function should be a no-op if the state store says the user is already invited.

  • extra_content (Optional[Dict[str, Any]]) – Additional properties for the invite event content.

Return type

None

async leave_room(room_id, extra_content=None)

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.

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

Return type

None

async mark_read(room_id, event_id)
Parameters
Return type

None

async pin_message(room_id, event_id)
Parameters
Return type

None

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: /send 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.

  • **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: PUT /state/{eventType}/{stateKey} 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 (Union[StateEventContent, Dict]) – The content to send.

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

  • **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 or not 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, is_typing=True, timeout=5000, ignore_cache=False)

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 seconds to mark this user as typing.

  • is_typing (bool) –

  • ignore_cache (bool) –

Return type

None

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

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.

Returns

The IntentAPI for the given user.

Return type

mautrix.appservice.IntentAPI

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