> ## 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()

> Everything presence() declares: the status of the bot and what it is doing

`presence()` declares the presence of the bot, once, from any file of `src/`. It takes one object, `PresenceConfig`.

```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' },
});
```

> [!NOTE]
>
> How to write the file, and what Discord shows for each type, is in the
> [guide](https://www.chapterjs.org/presence.md). This page lists what exists.

## presence()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
presence(config: PresenceConfig): PresenceDeclaration
```

Declares the presence of the bot: its status and what it is doing, shown under its name. Export the result from any file of `src/`, once; the bot has it as soon as it is connected.

### PresenceDeclaration

What `presence()` returns: a declaration the framework finds in the exports of a file.

**config** `unknown`

What the file gave to `presence()`, not checked yet.

## PresenceConfig

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type PresenceConfig = SinglePresenceConfig | RotatingPresenceConfig;
```

What a file gives to `presence()`: `activity` for one, or `activities` for several shown in turn.

### SinglePresenceConfig

A presence with one activity, or none.

**status** `PresenceStatusName`

The status of the bot. `'online'` by default.

**activity** `Activity`

What the bot is doing. Nothing by default.

### RotatingPresenceConfig

A presence whose activities are shown in turn.

**status** `PresenceStatusName`

The status of the bot. `'online'` by default.

**activities** `Activities` *required*

Several activities, shown one after the other, each for its `for`: a list,
or a function that gives it.

### PresenceStatusName

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type PresenceStatusName = 'online' | 'idle' | 'dnd' | 'invisible';
```

The status of the bot: `'online'` (green), `'idle'` (orange), `'dnd'` (red, "do not disturb") or `'invisible'` (shown as offline).

## Activities

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type Activities =
  | readonly Activity[]
  | ((context: PresenceContext) => readonly Activity[] | Promise<readonly Activity[]>);
```

The activities shown in turn: a list, or a function that gives it (maybe after a promise, from a store for example), run again each time the list has been shown in full.

## Activity

What the bot is doing: a `PlainActivity` or a `StreamingActivity`.

### PlainActivity

An activity that is not a stream.

**type** `ActivityKind` *required*

What the bot is doing, as Discord shows it: "Playing *name*", "Listening to
*name*", "Watching *name*", "Competing in *name*", or the text itself with
`'custom'`.

**name** `ActivityText` *required*

What is shown after the type (or alone with `'custom'`).

**for** `Duration`

How long the activity is shown before the next one, at least 5 seconds:
`'30s'`, `'2m'`. 30 seconds by default. Alone, it is how often a `name` that
is a function runs again.

### ActivityKind

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ActivityKind =
  'playing' | 'listening' | 'watching' | 'competing' | 'custom';
```

### StreamingActivity

A stream: "Streaming *name*", with a link to it.

**type** `'streaming'` *required*

**name** `ActivityText` *required*

What is shown after "Streaming".

**url** `string` *required*

The stream: Discord only accepts a `https://twitch.tv/` or a
`https://youtube.com/` link.

**for** `Duration`

How long the activity is shown before the next one, at least 5 seconds:
`'30s'`, `'2m'`. 30 seconds by default. Alone, it is how often a `name` that
is a function runs again.

### ActivityText

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ActivityText =
  string | ((context: PresenceContext) => string | Promise<string>);
```

The text of an activity: a text, or a function that gives it (maybe after a promise), run each time the activity is shown.

## PresenceContext

What a presence function receives, each time it runs: how many servers the bot is in, and the texts of the language files in the default language.

**guilds** `number` *required*

How many servers the bot is in, all processes together.

**t** `Translator`

The texts of the language files, in the default language. Only when the
project has language files.

[Discord documentation](https://docs.discord.com/developers/events/gateway-events#update-presence)


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