> ## Documentation Index
> Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Presence

> Choose the status of your bot and what it shows under its name, with one file

In the member list, a bot has a colored dot and sometimes a line under its name: "Watching over the server", say. That is its **presence**. It is one file, `src/presence.ts`, the one the template gave you, and this page is short because the file is.

## The file

The template shows a custom text, "Getting ready". Replace the file:

```ts src/presence.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { presence } from 'chapterjs';

export default presence({
  status: 'online',
  activity: { type: 'watching', name: 'over the server' },
});
```

Save it with the bot running, then change the `name` and save again:

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
↻ Presence updated
```

No reconnection: the bot tells Discord its new presence at once. Without the file, the bot is online and shows nothing. Both fields are optional.

## Status

| Write | Shown |
| - | - |
| `'online'` | A green dot (the default) |
| `'idle'` | An orange moon |
| `'dnd'` | A red dot, "do not disturb" |
| `'invisible'` | Offline, while the bot keeps running |

`'invisible'` is useful for a bot that works in the background and should not look like someone to talk to.

## Activity

`type` says how Discord words it, `name` is the text after it:

| Type | Shown |
| - | - |
| `'playing'` | Playing *name* |
| `'listening'` | Listening to *name* |
| `'watching'` | Watching *name* |
| `'competing'` | Competing in *name* |
| `'custom'` | *name*, alone |
| `'streaming'` | Streaming *name*, with a link to the stream (needs a Twitch or YouTube `url`) |

A common use is a hint: `{ type: 'playing', name: '/help' }` tells people where to start. That is all a bot may set: Discord lets a person show much more (a song, a game with details), but a bot only has a type, a name, and a URL for a stream.

## Taking turns

One line is little room. `activities` gives several, shown one after the other: each stays for its `for` (30 seconds when you leave it out, 5 seconds at least), then the next one comes, and after the last one, the first one again. Replace the file:

```ts src/presence.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { presence } from 'chapterjs';

export default presence({
  status: 'online',
  activities: [
    { type: 'playing', name: '/help', for: '20s' },
    { type: 'watching', name: ({ guilds }) => `${guilds} servers`, for: '20s' },
  ],
});
```

The second `name` is a function, not a text. The bot runs it each time that activity comes back, and gives it `guilds`, the number of servers it is in: the line follows your bot as it grows, without you touching the file. A function may also be `async` and read a [store](https://www.chapterjs.org/tutorial/storage.md), and `activities` itself may be a function that gives the whole list: the [guide](https://www.chapterjs.org/presence.md#activities-from-your-data) shows both.

Why `for` and not "change every second"? Discord takes 5 changes of presence per 20 seconds from a bot. Below 5 seconds, changes would be dropped: ChapterJS refuses it when the file loads.

## Points of attention

* **The presence is the bot's, not the server's.** It is the same in every server the bot is in. That is one more reason for a separate dev application: what you try here is shown everywhere the bot is.
* **Discord accepts 5 changes per 20 seconds.** When you save faster than that, only the latest presence is sent, when it may be.
* **A file that does not load** is reported with what is wrong, and the bot keeps the last presence that worked. Deleting the file puts the bot back to online with nothing shown.
* **The presence comes from the file only.** Your commands never set it: they change the data its functions read (a store, for example), and the next turn shows it.
* **A function that throws** is reported once, with its line, and the bot keeps the last text that worked.

## Recap

* `presence({ status, activity })` is declared once, in `src/presence.ts`; saving it applies at once.
* `status` is the dot; `activity` is the line under the name, with a `type` and a `name`.
* `activities` shows several in turn, each for its `for`; a `name` can be a function, run each time its activity comes.
* One presence for the whole bot, in every server.

> [card] [Translated messages](https://www.chapterjs.org/tutorial/translations.md)
>
> Answer each person in their language.

> [card] [Guide: Presence](https://www.chapterjs.org/presence.md)
>
> The same, in short.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.