INSTALL

# Installation

## 🚀 Quick Setup (Recommended)

**Use the web-based setup wizard for the easiest installation experience!**

1. Install dependencies: `npm install`
2. Start SlackONOS: `node index.js`
3. Open your browser: `http://localhost:8181/setup`
4. Follow the interactive wizard to configure all integrations
5. Save and restart SlackONOS

The setup wizard will:
- ✅ Guide you through each step
- ✅ Auto-discover Sonos devices on your network
- ✅ Validate Slack, Spotify, and Discord tokens
- ✅ Generate your configuration automatically

## Manual Installation

If you prefer to configure manually or need more control:

### Pre-requisites

1: #Slack-group with admin rights
2: A server / machine that can run node.js
3: A working Sonos player configured with Spotify
4: You need to know the IP of your Sonos player (or use auto-discovery in the wizard)

Note: In order to get Text-to-speech working you need to know the IP of the host running SlackONOS as well as having a TCP port (in setting) open for traffic from the Sonos to the device.

## Slack App (v2.0+ - Socket Mode Required)

**⚠️ Important: As of v2.0, SlackONOS requires Socket Mode. Legacy bot tokens are no longer supported.**

Follow these steps to create and configure your Slack app:

### 1. Create a Slack App

1. Go to https://api.slack.com/apps and click "Create New App"
2. Choose "From scratch"
3. Give it a name (e.g., "SlackONOS") and select your workspace
4. Click "Create App"

### 2. Enable Socket Mode

1. In your app settings, go to **"Socket Mode"** (under Features)
2. Toggle **"Enable Socket Mode"** to ON
3. You'll be prompted to generate an app-level token
4. Give it a name (e.g., "SlackONOS Socket Token")
5. Add the `connections:write` scope
6. Click "Generate"
7. **IMPORTANT**: Copy this token (starts with `xapp-`). This is your `slackAppToken`

### 3. Configure OAuth Permissions

1. Go to **"OAuth & Permissions"** (under Features)
2. Scroll to **"Scopes"** → **"Bot Token Scopes"**
3. Add the following scopes:
   * `app_mentions:read` - To receive @mentions
   * `channels:history` - To read messages in public channels
   * `chat:write` - To send messages
   * `users:read` - To look up user information
   * `im:history` - (Optional) To receive direct messages
4. Scroll to the top and click **"Install to Workspace"**
5. Authorize the app
6. **IMPORTANT**: Copy the **"Bot User OAuth Token"** (starts with `xoxb-`). This is your `token`

### 4. Subscribe to Events

1. Go to **"Event Subscriptions"** (under Features)
2. Toggle **"Enable Events"** to ON
3. Under **"Subscribe to bot events"**, add:
   * `app_mention` - When someone @mentions the bot
   * `message.channels` - Messages in public channels (bot must be invited)
   * `message.im` - (Optional) Direct messages to the bot
4. Click **"Save Changes"**

### 5. Invite Bot to Channels

1. In Slack, go to the channel where you want to use the bot (e.g., `#music-test`)
2. Type `/invite @SlackONOS` (or whatever you named your bot)
3. Do this for both your music channel and admin channel

### 6. Save Your Tokens

You now have two tokens:
- **App-Level Token** (`xapp-...`) → `slackAppToken` in config
- **Bot User OAuth Token** (`xoxb-...`) → `token` in config

## Node.js - Slackonos!

This guide assume you have git, node.js and NPM installed, and running linux =)

Run the following commands in your terminal:

cd /opt
git clone https://github.com/htilly/SlackONOS.git
cd SlackONOS
npm install
cp config.json.example config.json

Almost there... some simple configuration first.
Edit config.json with your favorit text editor.

Replace:

- `"music-admin"` - with the #slack channel you want the bot to respond to admin commands
- `"music"` - with the #slack channel you want the bot to be a DJ in
- `"IP_TO_SONOS"` - with the (static) IP of your Sonos player/controller
- `"SLACK:APP:TOKEN"` - with the app-level token (xapp-...) from step 2 above
- `"SLACK:BOT:TOKEN"` - with the bot user OAuth token (xoxb-...) from step 3 above
- `"SPOTIFY:CLIENT:ID"` - with your Spotify Client ID from https://developer.spotify.com/dashboard
- `"SPOTIFY:CLIENT:SECRET"` - with your Spotify Client Secret
- `"US"` - with the country code where you use Spotify (e.g., "SE" for Sweden, "US" for United States)
- `75` - with the maximum volume you can set the Sonos to via "setvolume" in #Slack

**Example config.json:**
```json
{
  "adminChannel": "music-admin",
  "standardChannel": "music",
  "sonos": "192.168.1.100",
  "slackAppToken": "xapp-1-A0ABC123...",
  "token": "xoxb-123456789...",
  "spotifyClientId": "abc123...",
  "spotifyClientSecret": "def456...",
  "market": "SE",
  "maxVolume": 75
}
```

And last thing... start the bot!

Type:
node index.js

You should see something like:

[Sat Apr 30 2016 21:44:10 GMT+0200 (CEST)] INFO Connecting... Welcome to Slack. You are @SlackONOS of Schibsted Media Group You are in: #music As well as: music-admin 

## Known Issues

If you for any reason get the following 500 error in the logs:

Error: HTTP response code 500 for "urn:schemas-upnp-org:service:AVTransport:1#AddURIToQueue"

Please try to change the following code in index.js. You need to change this in three places.
Don´t know what this is happening, but it has been confirmed on at least two systems :/

// Old version.. New is supposed to fix 500 problem...
// sonos.addSpotifyQueue(spid, function (err, res) {

sonos.addSpotify(spid, function (err, res) {