path: root/chat.sr.ht/bouncer-usage.md

# Using the chat.sr.ht bouncer

For full details, refer to the [soju(1)](https://soju.im/doc/soju.1.html) man
page. Information about common use-cases is provided here.

## Connecting with a third-party IRC client

<!-- Note: update chat.sr.ht/quickstart.md if changing this -->

To connect with a third-party IRC client, you will need to generate an OAuth 2.0
personal access token to use as your server password. Visit [the personal access
token issuance page](https://meta.sr.ht/oauth2/personal-token) and set the
grant string to "meta.sr.ht/PROFILE:RO", adding an optional comment, and leaving
the other fields unchanged.

<dl>
<dt>Hostname</dt><dd>chat.sr.ht</dd>
<dt>Port</dt><dd>6697</dd>
<dt>SSL/TLS</dt><dd>Yes</dd>
<dt>SASL</dt><dd>Yes</dd>
<dt>Username</dt><dd><em>your sourcehut username</em></dd>
<dt>Password</dt><dd><em>your personal access token</em></dd>
</dl>

If you intend to use multiple clients, it is recommended that you append
"@*clientname*" to your username, using an arbitrary unique string to identify
each client. If your IRC client does not support soju's
"soju.im/bouncer-networks" extension (check if [a plugin is available][config]),
you may want to configure separate connections for each network by using the
username format `username/network-name@client-name`.

See [client-specific configuration][config] for recommended configuration steps
specific to your preferred IRC client.

[config]: https://git.sr.ht/~emersion/soju/tree/master/item/contrib/clients.md

## Managing your IRC networks

The webchat at [chat.sr.ht](https://chat.sr.ht) provides a UI for managing your
bouncer networks. Third-party clients with soju support may detect the bouncer
and offer similar functionality. If not, you can also message BouncerServ to
configure soju. Use `/msg BouncerServ help` for a full list of supported
commands.

To add a new IRC network via BouncerServ:

```
/msg BouncerServ network create -addr <hostname> [options...]
```

See [soju(1)](https://soju.im/doc/soju.1.html#IRC_SERVICE) for details on the
supported options.

## Detaching from channels

You can instruct the bouncer to "detach" from a channel. This causes it to be
hidden from your channel list, but to leave your connection to the channel
active. If you're mentioned by a user in this channel, you will receive
notifications for it, and if you re-join later, you will be able to view logs of
discussions which took place in your absence.

To detach from a channel, use the `/part detach` command, or `/msg BouncerServ
channel update <name> -detached=<true|false>`.

## Client-specific configuration

Various configuration recommendations for third-party IRC clients are documented
here: [contrib/clients.md](https://git.sr.ht/~emersion/soju/tree/master/item/contrib/clients.md).