mautrix.appservice.api package

Submodules

mautrix.appservice.api.appservice module

class mautrix.appservice.api.appservice.AppServiceAPI(base_url: str, bot_mxid: NewType.<locals>.new_type = None, token: str = None, identity: Optional[NewType.<locals>.new_type] = None, log: Logger = None, state_store: StateStore = None, client_session: ClientSession = None, child: bool = False, real_user: bool = False, real_user_content_key: Optional[str] = None, loop: Optional[asyncio.events.AbstractEventLoop] = None)[source]

Bases: mautrix.api.http.HTTPAPI

AppServiceAPI is an extension to HTTPAPI that provides appservice-specific features, such as child instances and easy access to IntentAPIs.

bot_intent() → mautrix.appservice.api.intent.IntentAPI[source]

Get the intent API for the appservice bot.

Return type:IntentAPI
Returns:The IntentAPI object for the appservice bot
intent(user: NewType.<locals>.new_type = None, token: Optional[str] = None, base_url: Optional[str] = None) → mautrix.appservice.api.intent.IntentAPI[source]

Get the intent API of a child user.

Parameters:
  • user (Optional[UserID[str]]) – The Matrix user ID whose intent API to get.
  • token (Optional[str]) – The access token to use. Only applicable for non-appservice-managed users.
  • base_url (Optional[str]) – The base URL of the homeserver client-server API to use. Only applicable for non-appservice users. Defaults to the appservice homeserver URL.
Return type:

IntentAPI
Returns:

The IntentAPI object for the given user.
Raises:

ValueError – When this AppServiceAPI instance is a real user.
real_user(mxid: str, token: str, base_url: Optional[str] = None) → mautrix.appservice.api.appservice.AppServiceAPI[source]

Get the AppServiceAPI for a real (non-appservice-managed) Matrix user.

Parameters:
  • mxid (str) – The Matrix user ID of the user whose AppServiceAPI to get.
  • token (str) – The access token for the user.
  • base_url (Optional[str]) – The base URL of the homeserver client-server API to use. Defaults to the appservice homeserver URL.
Return type:

AppServiceAPI
Returns:

The AppServiceAPI object for the user.
Raises:

ValueError – When this AppServiceAPI instance is a real user.
request(method: mautrix.api.http.Method, path: mautrix.api.http.PathBuilder, content: Union[Dict, bytes, str, None] = None, timestamp: Optional[int] = None, external_url: Optional[str] = None, headers: Optional[Dict[str, str]] = None, query_params: Optional[Dict[str, Any]] = None) → Awaitable[Dict][source]

Make a raw HTTP request, with optional AppService timestamp massaging and external_url setting.

Parameters:
  • method (Method) – The HTTP method to use.
  • path (PathBuilder) – The API endpoint to call. Does not include the base path (e.g. /_matrix/client/r0).
  • content (Union[Dict[~KT, ~VT], bytes, str, None]) – The content to post as a dict (json) or bytes/str (raw).
  • timestamp (Optional[int]) – The timestamp query param used for timestamp massaging.
  • external_url (Optional[str]) – The external_url field to send in the content (only applicable if content is dict).
  • headers (Optional[Dict[str, str]]) – The dict of HTTP headers to send.
  • query_params (Optional[Dict[str, Any]]) – The dict of query parameters to send.
  • api_path – The base API path.
Return type:

Awaitable[Dict[~KT, ~VT]]
Returns:

The response as a dict.
user(user: NewType.<locals>.new_type) → mautrix.appservice.api.appservice.ChildAppServiceAPI[source]

Get the AppServiceAPI for an appservice-managed user.

Parameters:user (UserID[str]) – The Matrix user ID of the user whose AppServiceAPI to get.
Return type:ChildAppServiceAPI
Returns:The ChildAppServiceAPI object for the user.
class mautrix.appservice.api.appservice.ChildAppServiceAPI(user: NewType.<locals>.new_type, parent: mautrix.appservice.api.appservice.AppServiceAPI)[source]

Bases: mautrix.appservice.api.appservice.AppServiceAPI

ChildAppServiceAPI is a simple way to copy AppServiceAPIs while maintaining a shared txn_id.

txn_id
Return type:int

mautrix.appservice.api.intent module

class mautrix.appservice.api.intent.IntentAPI(mxid: NewType.<locals>.new_type, api: AppServiceAPI, bot: IntentAPI = None, state_store: mautrix.appservice.state_store.abstract.StateStore = None, log: logging.Logger = None)[source]

Bases: mautrix.client.api.client.ClientAPI

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.

ensure_joined(room_id: NewType.<locals>.new_type, ignore_cache: bool = False) → None[source]
Return type:None
ensure_registered() → None[source]
Return type:None
error_and_leave(room_id: NewType.<locals>.new_type, text: Optional[str] = None, html: Optional[str] = None) → None[source]
Return type:None
get_membership(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type) → Awaitable[str][source]
Return type:Awaitable[str]
get_pinned_messages(room_id: NewType.<locals>.new_type) → List[NewType.<locals>.new_type][source]
Return type:List[EventID[str]]
get_power_levels(room_id: NewType.<locals>.new_type, ignore_cache: bool = False) → mautrix.client.api.types.event.state.PowerLevelStateEventContent[source]
Return type:PowerLevelStateEventContent
get_room_avatar_url(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type, ignore_cache=False) → str[source]
Return type:str
get_room_displayname(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type, ignore_cache=False) → str[source]
Return type:str
get_room_joined_memberships(room_id: NewType.<locals>.new_type) → Awaitable[dict][source]
Return type:Awaitable[dict]
get_room_member_info(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type, ignore_cache=False) → mautrix.client.api.types.users.Member[source]
Return type:Member
get_room_members(room_id: NewType.<locals>.new_type, allowed_memberships: Tuple[<unknown>.Membership, ...] = (join, )) → List[NewType.<locals>.new_type][source]
Return type:List[UserID[str]]
get_room_memberships(room_id: NewType.<locals>.new_type) → Awaitable[dict][source]
Return type:Awaitable[dict]
get_state(room_id: NewType.<locals>.new_type) → List[mautrix.client.api.types.event.state.StateEvent][source]

Get the state events for the current state of a room.

See also: API reference

Parameters:room_id (RoomID[str]) – The ID of the room to look up the state for.
Return type:List[StateEvent]
Returns:A list of state events with the most recent of each event_type/state_key pair.
get_state_event(room_id: NewType.<locals>.new_type, event_type: mautrix.client.api.types.event.base.EventType, state_key: Optional[str] = '') → Union[mautrix.client.api.types.event.state.PowerLevelStateEventContent, mautrix.client.api.types.event.state.MemberStateEventContent, mautrix.client.api.types.event.state.AliasesStateEventContent, mautrix.client.api.types.event.state.CanonicalAliasStateEventContent, mautrix.client.api.types.event.state.RoomNameStateEventContent, mautrix.client.api.types.event.state.RoomAvatarStateEventContent, mautrix.client.api.types.event.state.RoomTopicStateEventContent, mautrix.client.api.types.event.state.RoomPinnedEventsStateEventContent, mautrix.client.api.types.event.state.RoomTombstoneEventContent, mautrix.client.api.types.util.obj.Obj][source]

Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room to look up the state in.
  • event_type (EventType) – The type of state to look up.
  • state_key (Optional[str]) – The key of the state to look up. Defaults to empty string.
Return type:

Union[PowerLevelStateEventContent, MemberStateEventContent, AliasesStateEventContent, CanonicalAliasStateEventContent, RoomNameStateEventContent, RoomAvatarStateEventContent, RoomTopicStateEventContent, RoomPinnedEventsStateEventContent, RoomTombstoneEventContent, Obj]
Returns:

The state event.
invite_user(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type, check_cache: bool = False) → None[source]

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 (RoomID[str]) – The ID of the room to which to invite the user.
  • user_id (UserID[str]) – 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.
Return type:

None
leave_room(room_id: NewType.<locals>.new_type) → None[source]

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 (RoomID[str]) – The ID of the room to leave.
Return type:None
mark_read(room_id: NewType.<locals>.new_type, event_id: NewType.<locals>.new_type) → None[source]
Return type:None
pin_message(room_id: NewType.<locals>.new_type, event_id: NewType.<locals>.new_type) → None[source]
Return type:None
send_message_event(room_id: NewType.<locals>.new_type, event_type: mautrix.client.api.types.event.base.EventType, content: Union[mautrix.client.api.types.event.message.TextMessageEventContent, mautrix.client.api.types.event.message.MediaMessageEventContent, mautrix.client.api.types.event.message.LocationMessageEventContent, mautrix.client.api.types.util.obj.Obj, Dict], **kwargs) → NewType.<locals>.new_type[source]

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:
Return type:

EventID[str]
Returns:

The ID of the event that was sent.
send_state_event(room_id: NewType.<locals>.new_type, event_type: mautrix.client.api.types.event.base.EventType, content: Union[mautrix.client.api.types.event.state.PowerLevelStateEventContent, mautrix.client.api.types.event.state.MemberStateEventContent, mautrix.client.api.types.event.state.AliasesStateEventContent, mautrix.client.api.types.event.state.CanonicalAliasStateEventContent, mautrix.client.api.types.event.state.RoomNameStateEventContent, mautrix.client.api.types.event.state.RoomAvatarStateEventContent, mautrix.client.api.types.event.state.RoomTopicStateEventContent, mautrix.client.api.types.event.state.RoomPinnedEventsStateEventContent, mautrix.client.api.types.event.state.RoomTombstoneEventContent, mautrix.client.api.types.util.obj.Obj, Dict], state_key: Optional[str] = '', **kwargs) → NewType.<locals>.new_type[source]

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:
Return type:

EventID[str]
Returns:

The ID of the event that was sent.
set_join_rule(room_id: NewType.<locals>.new_type, join_rule: str, **kwargs)[source]
set_membership(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type, membership: <unknown>.Membership, reason: Optional[str] = '', profile: Optional[dict] = None, **kwargs) → Awaitable[dict][source]
Return type:Awaitable[dict]
set_pinned_messages(room_id: NewType.<locals>.new_type, events: List[NewType.<locals>.new_type], **kwargs) → Awaitable[dict][source]
Return type:Awaitable[dict]
set_power_levels(room_id: NewType.<locals>.new_type, content: mautrix.client.api.types.event.state.PowerLevelStateEventContent, **kwargs) → NewType.<locals>.new_type[source]
Return type:EventID[str]
set_presence(presence: <unknown>.PresenceState = online, status: Optional[str] = None, ignore_cache: bool = False)[source]

Set the online status of the user.

See also: API reference

Parameters:
  • presence (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: NewType.<locals>.new_type, avatar_url: Optional[NewType.<locals>.new_type], **kwargs) → Awaitable[NewType.<locals>.new_type][source]
Return type:Awaitable[EventID[str]]
set_room_name(room_id: NewType.<locals>.new_type, name: str, **kwargs) → Awaitable[NewType.<locals>.new_type][source]
Return type:Awaitable[EventID[str]]
set_room_topic(room_id: NewType.<locals>.new_type, topic: str, **kwargs) → Awaitable[NewType.<locals>.new_type][source]
Return type:Awaitable[EventID[str]]
set_typing(room_id: NewType.<locals>.new_type, is_typing: bool = True, timeout: int = 5000, ignore_cache: bool = False) → None[source]

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 (RoomID[str]) – 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.
Return type:

None
unpin_message(room_id: NewType.<locals>.new_type, event_id: NewType.<locals>.new_type)[source]
user(user_id: NewType.<locals>.new_type, token: Optional[str] = None) → mautrix.appservice.api.intent.IntentAPI[source]

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 (UserID[str]) – The Matrix ID of the user whose intent API to get.
  • token (Optional[str]) – The access token to use for the Matrix ID.
Return type:

IntentAPI
Returns:

The IntentAPI for the given user.
mautrix.appservice.api.intent.quote(*args, **kwargs)[source]

Module contents