Appservice client API

class mautrix.appservice.AppServiceAPI

Bases: mautrix.api.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 (yarl.URL | str) – The base URL of the homeserver client-server API to use.

  • bot_mxid (Optional[mautrix.types.UserID]) – The Matrix user ID of the appservice bot.

  • token (Optional[str]) – The access token to use.

  • identity (Optional[mautrix.types.UserID]) – The ID of the Matrix user to act as.

  • log (Optional[mautrix.util.logging.TraceLogger]) – The logging.Logger instance to log requests with.

  • state_store (Optional[mautrix.appservice.ASStateStore]) – The StateStore instance to use.

  • client_session (Optional[aiohttp.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 (Optional[str]) – 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 (Optional[int]) –

  • loop (Optional[asyncio.events.AbstractEventLoop]) –

Return type

None

bot_intent()

Get the intent API for the appservice bot.

Returns

The IntentAPI object for the appservice bot

Return type

mautrix.appservice.IntentAPI

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

Get the intent API of a child user.

Parameters

  • user (Optional[mautrix.types.UserID]) – 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.

  • 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

mautrix.appservice.IntentAPI

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

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

Parameters

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

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

  • base_url (Optional[yarl.URL]) – 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

mautrix.appservice.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 (mautrix.api.Method) – The HTTP method to use.

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

  • content (Optional[Union[dict, bytes, str]]) – The content to post as a dict/list (will be serialized as JSON) or bytes/str (will be sent as-is).

  • timestamp (Optional[int]) – The timestamp query param used for timestamp massaging.

  • headers (Optional[dict[str, str]]) – 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 (Optional[dict[str, typing.Any]]) – A dict of query parameters to send.

  • retry_count (Optional[int]) – 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 (mautrix.types.UserID) – The Matrix user ID of the user whose AppServiceAPI to get.

Returns

The ChildAppServiceAPI object for the user.

Return type

mautrix.appservice.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: mautrix.appservice.AppServiceAPI

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

__init__(user, parent)
Parameters
Return type

None

property txn_id: int
parent: AppServiceAPI