Element Stickers - Advanced Guide!

This guide assumes some prior knowledge about terminal basics such as navigating files, understanding what a directory is, using a Python virtual environment, and using git.

This is something that only needs a one-time setup and then gives you access to stickers in all your chats in Element though, so if you can have a technical-oriented friend help you out, you’ll be set!

You will need to redo the last part of this process every time you want to add more stickers, but after you do it once and know how it works, it becomes much easier on subsequent updates.

Information

This guide is only going to fill in some gaps I encountered in the actual documentation of Maunium Sticker Picker. Most of the documentation will either be copied from or paraphrased from the original repository. Please give it a star if you find it useful!

ORIGINAL REPOSITORY HERE: https://github.com/maunium/stickerpicker

If you have any problems with the steps in this guide, it is recommended to follow the original repository’s instructions. This website is not affiliated with the official developer.

Setup

  1. Fork the repo
    arrow pointing at fork button
  2. Go to settings
    arrow pointing at settings button
  3. Scroll down to the bottom to the “GitHub Pages” section”
  4. In the “Source” dropdown, select “master”
    arrow pointing at branch dropdown in GH pages settings
  5. Click “Save”
    arrow pointing at save button
  6. Clone your fork (git clone git@github.com:username/stickerpicker.git)

Installing the program

Now that you cloned the repository, there’s actually some things you need to install inside the project directory.

To get started, install the dependencies by using the commands below: (do these commands inside the root directory of the project!)

  1. Make sure you have Python 3.6 or higher.
  2. Set up a virtual environment:
    1. Create with virtualenv -p python3 .venv
    2. Activate with source .venv/bin/activate
  3. Install the utility commands and their dependencies with pip install .

For NixOS Users

This can be done in a nix-shell!

nix-shell -p python311 python311Packages.virtualenv

After entering the shell, perform the following commands (one at a time):

virtualenv -p python3 .venv
source .venv/bin/activate
pip install .

Setting up your stickers!

  1. Create a directory with your sticker images.
    • The file name (excluding extension) will be used as the caption.
    • The directory name will be used as the pack name/ID.
    • If you want the stickers to appear in a specific order, prefix them with number-, e.g. 01-Cat.png. The number and dash won’t be included in the caption.
  2. Run sticker-pack <pack directory> --add-to-index web/packs.

Pushing the stickers to GitHub Pages

If your commands were successful, you should now see a thumbnails folder, an index.json file, and a .json file of the sticker pack you just added.

This means you’re ready to push these changes to the GitHub repository! Go back to the root directory of the project and run the following commands:

git add web/packs
git commit -m 'added stickers'
git push

Once that is done, you should now be able to view your website on GitHub pages. If done correctly, you should see you stickers at:

https://<GITHUB_USERNAME>.github.io/stickerpicker/web/

If everything checks out, you’re free to now add the widget to your account!

Adding the sticker widget to your account

Now, we need to do some command-line magic in order to actually put this sticker widget onto your account. Down below is a command you need to fill in the blanks for.

curl -X PUT "https://<HOMESERVER>/_matrix/client/v3/user/<MATRIX_ID>/account_data/m.widgets" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "stickerpicker": {
      "content": {
        "type": "m.stickerpicker",
        "url": "https://<GITHUB_USERNAME>.github.io/stickerpicker/?theme=$theme",
        "name": "Stickerpicker",
        "creatorUserId": "<MATRIX_ID>",
        "data": {}
      },
      "sender": "<MATRIX_ID>",
      "state_key": "stickerpicker",
      "type": "m.widget",
      "id": "stickerpicker"
    }
  }'

Once you do this, you should now be able to go in the Element app on web, iOS, Android, or PC and you will see your stickers pop up when you try to open the sticker widget! This will also apply to all chats, so there is no need to redo this anywhere you chat.

Do note that this is a different system than all the other Matrix clients. If you switch to another client such as Cinny, you will have to follow the pack system

Extra Information

Read this section if you want to know a little bit more of what we just did, conceptually. This could help with troubleshooting or just wanting to know how it works.

Matrix stores data in your account. One of these data points is called m.widgets. By default, the m.widgets data point in your Matrix account is empty, but what we do here is embed it with maunium’s webapp called “stickerpicker”.

Element itself also has a way to access the “stickerpicker” widget (lucky for us), but by default, its empty. This is because Element allows us to create our own custom solutions and put them in the client ourselves (this is more complicated, but definitely more flexible). So, we used an already existing widget in the UI (the sticker picker) that was left empty by default, and put in our own program, the sticker picker!

Kinda silly, but yes. We put a sticker picker in the stickerpicker widget, because Element leaves the stickerpicker widget empty by default.