> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BunnyNabbit/voxel-telephone/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack integration for Voxel Telephone server events

> Configure the Slack integration to forward game events, chat messages, and player connections to a Slack channel using a Slack bot token.

The `Slack` integration sends server events to a Slack channel using the Slack Web API. It authenticates with a bot token and posts plain-text messages to a channel you specify.

## How it works

When an event matching a configured interest fires, the integration calls Slack's `chat.postMessage` API method with the message text and the target channel. The `@slack/web-api` package handles authentication and the HTTP request.

## Create a Slack bot token

<Steps>
  <Step title="Create a Slack app">
    Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**. Choose **From scratch**, give your app a name, and select the workspace where your Slack channel lives.
  </Step>

  <Step title="Add the chat:write permission">
    In your app's settings, go to **OAuth & Permissions** → **Scopes** → **Bot Token Scopes**. Add the `chat:write` scope.
  </Step>

  <Step title="Install the app to your workspace">
    Click **Install to Workspace** at the top of the **OAuth & Permissions** page. Approve the permissions. Copy the **Bot User OAuth Token** — it starts with `xoxb-`.
  </Step>

  <Step title="Invite the bot to your channel">
    In Slack, open the channel where you want events posted and type `/invite @YourAppName`.
  </Step>

  <Step title="Add the token and channel to your config">
    Paste the bot token and channel name or ID into the `authData` field in `config.json` (see the configuration section below).
  </Step>
</Steps>

## Configuration

Add an entry to the `integrations` array in `config.json` with `"class": "Slack"`. The `authData` object requires two fields:

| Field              | Type   | Description                                                            |
| ------------------ | ------ | ---------------------------------------------------------------------- |
| `authData.token`   | string | The bot user OAuth token starting with `xoxb-`.                        |
| `authData.channel` | string | The channel name (e.g. `#general`) or channel ID (e.g. `C1234567890`). |
| `interests`        | array  | Event types this integration should receive.                           |
| `language`         | string | Optional locale for formatted messages. Defaults to `"en"`.            |

```json theme={null}
{
  "integrations": [
    {
      "class": "Slack",
      "authData": {
        "token": "xoxb-your-bot-token",
        "channel": "#voxel-telephone"
      },
      "interests": [
        "gameProgression",
        "playerConnection",
        "chatMessage"
      ]
    }
  ]
}
```

<Note>
  You can use either a channel name prefixed with `#` or the channel's ID. Channel IDs are more reliable if your channel is ever renamed.
</Note>

## Choosing interests for Slack

* **`gameProgression`** — posts when game turns complete, useful for activity tracking.
* **`playerConnection`** — records when players join or leave.
* **`chatMessage`** — mirrors in-game chat to Slack, enabling a full chat bridge.
* **`announcement`** — forwards server tips and announcements to your Slack channel.
* **`startServer`** — posts a message when the server finishes starting up.

<Warning>
  Keep your bot token private. Treat it like a password — it grants permission to post to any channel the bot has been invited to. Rotate the token in your Slack app settings if it is ever compromised.
</Warning>