Client-Server API

Client-Server API

The Client-Server API allows programmatic communication with a Matrix homeserver. Using this API, a client can authenticate, retrieve and send room events, and perform other operations. The following examples assume that a bot user already exists.

Before implementing a complete client from scratch, it is recommended to check existing clients first.

Authentication

Firstly, the bot account uXXXXX needs to authenticate with the bot instance. This process generates a temporary access token.

curl -X POST "https://bot.academiccloud.de/_matrix/client/v3/login" -d \
    '{
    "type": "m.login.password",
    "user": "uXXXXX",
    "password": "<Password or token from IDM>"
    }'

If successful, the response will look something like this:

{"user_id":"@uXXXXX:bot.academiccloud.de","access_token":"<ACCESS_TOKEN>","home_server":"bot.academiccloud.de","device_id":"<DEVICE_ID>","well_known":{"m.homeserver":{"base_url":"https://bot.academiccloud.de/"}}}

The <ACCESS_TOKEN> from this response must be used in subsequent API requests.

Send a Message to a Room

The following command sends a simple text message to a room:

curl -X PUT "https://bot.academiccloud.de/_matrix/client/v3/rooms/%21<ROOM_ID>:<HOME_SERVER>/send/m.room.message/$(uuidgen)" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "msgtype": "m.text",
           "body": "Hello, world!"
         }'

Listen for Messages in Rooms

You can listen for incoming messages in all rooms where the bot is a member using:

curl -X GET "https://bot.academiccloud.de/_matrix/client/v3/sync?timeout=3600" \
    -H "Authorization: Bearer <ACCESS_TOKEN>"

To limit this to specific rooms or event types, filters can be applied.

Existing Clients

Here are some examples of existing Matrix clients and SDKs for reference: