To add an avatar to a Matrix user programmatically, you must first upload the image to the homeserver’s media repository to obtain a Matrix Content URI (MXC URI), and then update the user’s profile with that URI. This process requires administrative privileges.

Follow these steps using curl commands in your terminal.

Prerequisites

• Admin Access: You must have an access token for an administrator account.
• Image File: Ensure you have the image file ready (e.g., avatar.jpg).
• Server Details: Replace YOUR_SERVER with your homeserver domain (e.g., matrix.example.com).

Step 1: Upload the Image

First, upload the image file to the media repository. This returns a unique identifier for the image.

Run the following command, replacing /path/to/avatar.jpg with the actual path to your image file:

curl -X POST \
  https://YOUR_SERVER/_matrix/media/v3/upload \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: image/jpeg" \
  --data-binary @/path/to/avatar.jpg

Expected Response: The server will return a JSON object containing the content_uri. Copy this value:

{
  "content_uri": "mxc://YOUR_SERVER/abc123xyz"
}

Step 2: Assign the Avatar to the User

Next, update the target user’s profile to use the uploaded image.

Run the following command, replacing @USERNAME:YOURSERVER with the full Matrix ID of the user (e.g., @john:matrix.example.com) and the contenturi with the value obtained in Step 1:

curl -X PUT \
  https://YOUR_SERVER/_synapse/admin/v2/users/@USERNAME:YOUR_SERVER \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"avatar_url": "mxc://YOUR_SERVER/abc123xyz"}'

Note: Ensure the JSON body is correctly formatted with double quotes around keys and values.

Troubleshooting

• 403 Forbidden: Ensure the access token used has administrative privileges.
• 404 Not Found: Verify that the @USERNAME:YOUR_SERVER is correct and that the user exists on the server.
• Invalid Content URI: Ensure the content_uri from Step 1 was copied exactly, including the mxc:// prefix.
• Image Format: Synapse typically supports JPEG, PNG, and GIF. Ensure your file is one of these formats.