====== Appservices ======

Application services are distinct modules which sit alongside a homeserver providing arbitrary extensible functionality decoupled from the homeserver implementation. Just like the rest of Matrix, they communicate via HTTP using JSON. Application services function in a very similar way to traditional clients, but they are given much more power than a normal client. They can reserve entire namespaces of room aliases and user IDs for their own purposes. They can silently monitor events in rooms, or any events directed at any user ID. This power allows application services to have extremely useful abilities which overall enhance the end user experience.

In short, Appservices are used to implement the bridges. In general, appservices extend a Matrix server functionality. Think of them as some powerful external plugins.


===== How to create =====

Assuming you already have the Appservice developed (this is not a devleoper's guide for Appservices, but an end-user guide)...

Creating an appservice require writing a YAML registration file to let the server know about the Appservice you ant to connect to it (register).

An example //registration.yaml// could look like:
<code>
id: telegram
as_token: << a nice long secret string >>
hs_token: << a nice long secret string >>
namespaces:
    users:
    - exclusive: true
      regex: '@telegram_.*:chat\.mydomain\.com'
    - exclusive: true
      regex: '@telegrambot:chat\.mydomain\.com'
    aliases:
    - exclusive: true
      regex: \#telegram_.*:chat\.mydomain\.com
url: http://localhost:29317
sender_localpart: << a nice long secret string >>
rate_limited: false
de.sorunome.msc2409.push_ephemeral: true
push_ephemeral: true
</code>

The ID is arbitrary, pick whatever you like or need. Usually, these registration YAML are created automatically by the Bridges during the configuration phase.

===== How to register =====

Registering appservices depends on the Matrix server. 

Some general information on registering appservices can be found [[https://docs.mau.fi/bridges/general/registering-appservices.html|here]] as well.

If you use Conduwuit as i recomend, the procedure is quite different from Synapse (maybe the most common Matrix server), because the appservice must be registered from the admin chat with the //!admin appservices register// command and a sligthly unusual syntax:
  * Open up your matrix client
  * go to the //chat.mydomain.com Admin room//
  * Type the following command:
<code>
!admin appservices register << shift+enter >>
```  << shift+enter >>
[ ... copy here the content of registration.yaml ... ]
``` << enter >>
</code>

When you see « shift enter » you need to press those two keys (on PC, on mobile usually return, not send, is enough) in order to create a new line in the same command. The three ``` (backthicks) are the markdown token to create a code block.

The chat should reply with a message like:
<code>
Appservice registered with ID: telegram
</code>

and you are all set.