Appservice client API

class mautrix.appservice.AppServiceAPI

Bases: HTTPAPI

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

__init__(base_url, bot_mxid=None, token=None, identity=None, log=None, state_store=None, client_session=None, child=False, real_user=False, real_user_as_token=False, bridge_name=None, default_retry_count=None, loop=None)
Parameters:

  • base_url (URL | str) – The base URL of the homeserver client-server API to use.

  • bot_mxid (UserID) – The Matrix user ID of the appservice bot.

  • token (str) – The access token to use.

  • identity (UserID | None) – The ID of the Matrix user to act as.

  • log (TraceLogger) – The logging.Logger instance to log requests with.

  • state_store (ASStateStore) – The StateStore instance to use.

  • client_session (ClientSession) – The aiohttp ClientSession to use.

  • child (bool) – Whether or not this is instance is a child of another AppServiceAPI.

  • real_user (bool) – Whether or not this is a real (non-appservice-managed) user.

  • real_user_as_token (bool) – Whether this real user is actually using another as_token.

  • bridge_name (str | None) – The name of the bridge to put in the fi.mau.double_puppet_source field in outgoing message events sent through real users.

  • default_retry_count (int)

  • loop (AbstractEventLoop | None)

Return type:

None

bot_intent()

Get the intent API for the appservice bot.

Returns:

The IntentAPI object for the appservice bot

Return type:

IntentAPI

intent(user=None, token=None, base_url=None, real_user_as_token=False)

Get the intent API of a child user.

Parameters:

  • user (UserID) – The Matrix user ID whose intent API to get.

  • token (str | None) – The access token to use. Only applicable for non-appservice-managed users.

  • base_url (str | None) – The base URL of the homeserver client-server API to use. Only applicable for non-appservice users. Defaults to the appservice homeserver URL.

  • real_user_as_token (bool) – When providing a token, whether it’s actually another as_token (meaning the user_id query parameter needs to be used).

Returns:

The IntentAPI object for the given user.

Raises:

ValueError – When this AppServiceAPI instance is a real user.

Return type:

IntentAPI

real_user(mxid, token, base_url=None, as_token=False)

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

Parameters:

  • mxid (UserID) – The Matrix user ID of the user whose AppServiceAPI to get.

  • token (str) – The access token for the user.

  • base_url (URL | None) – The base URL of the homeserver client-server API to use. Defaults to the appservice homeserver URL.

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

Returns:

The AppServiceAPI object for the user.

Raises:

ValueError – When this AppServiceAPI instance is a real user.

Return type:

AppServiceAPI

request(method, path, content=None, timestamp=None, headers=None, query_params=None, retry_count=None, metrics_method='', min_iter_size=26214400)

Make a raw Matrix API request, acting as the appservice user assigned to this AppServiceAPI instance and optionally including timestamp massaging.

Parameters:

  • method (Method) – The HTTP method to use.

  • path (PathBuilder) – The full API endpoint to call (including the _matrix/… prefix)

  • content (dict | bytes | str | None) – The content to post as a dict/list (will be serialized as JSON) or bytes/str (will be sent as-is).

  • timestamp (int | None) – The timestamp query param used for timestamp massaging.

  • headers (dict[str, str] | None) – A dict of HTTP headers to send. If the headers don’t contain Content-Type, it’ll be set to application/json. The Authorization header is always overridden if token is set.

  • query_params (dict[str, Any] | None) – A dict of query parameters to send.

  • retry_count (int | None) – Number of times to retry if the homeserver isn’t reachable. Defaults to default_retry_count.

  • metrics_method (str | None) – Name of the method to include in Prometheus timing metrics.

  • min_iter_size (int) – If the request body is larger than this value, it will be passed to aiohttp as an async iterable to stop it from copying the whole thing in memory.

Returns:

The parsed response JSON.

Return type:

Awaitable[dict]

user(user)

Get the AppServiceAPI for an appservice-managed user.

Parameters:

user (UserID) – The Matrix user ID of the user whose AppServiceAPI to get.

Returns:

The ChildAppServiceAPI object for the user.

Return type:

ChildAppServiceAPI

base_log: TraceLogger
identity: UserID | None
bot_mxid: UserID
state_store: ss.ASStateStore
txn_id: int

A counter used for generating transaction IDs.

children: dict[str, ChildAppServiceAPI]
real_users: dict[str, AppServiceAPI]
is_real_user: bool
bridge_name: str | None
class mautrix.appservice.ChildAppServiceAPI

Bases: AppServiceAPI

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

__init__(user, parent)
Parameters:

  • user (UserID) – The Matrix user ID of the child user.

  • parent (AppServiceAPI) – The parent AppServiceAPI instance.

Return type:

None

property txn_id: int
parent: AppServiceAPI