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_content_key=None, default_retry_count=None, loop=None)
Parameters

  • base_url (Union[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_content_key (Optional[str]) – The key to inject 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)

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.

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)

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.

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)

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

Parameters

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

  • path (mautrix.api.PathBuilder) – The API endpoint to call. Does not include the base path (e.g. /_matrix/client/r0).

  • content (Optional[Union[Dict, bytes, str]]) – The content to post as a dict (json) or bytes/str (raw).

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

  • 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.

  • retry_count (Optional[int]) – Number of times to retry if the homeserver isn’t reachable.

Returns

The response as a dict.

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: Optional[UserID]
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
real_user_content_key: Optional[str]
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