Skip to content

USER_GUIDE.md

Latest commit

 

History

History
439 lines (285 loc) · 10.3 KB

USER_GUIDE.md

File metadata and controls

439 lines (285 loc) · 10.3 KB

User Guide

This guide is for users of Bot Shock. It assumes the bot is already installed and running in your Discord server.

What is Bot Shock?

Bot Shock is a Discord bot that connects to OpenShock and PiShock devices. It lets you:

  • Control shock devices through Discord commands
  • Give specific people permission to control your device
  • Set up scheduled reminders that trigger automatically
  • Create word triggers that activate when you say certain things
  • View a complete history of all actions

Getting Started

Step 1: Get Your API Credentials

For OpenShock Users

  1. Go to OpenShock and log in
  2. Click on your profile, then Settings
  3. Go to the API Tokens section
  4. Create a new token or copy an existing one
  5. Keep this token private

For PiShock Users

  1. Log in to your PiShock account
  2. Go to your account settings
  3. Find your username and API key
  4. You will also need the share code for each device you want to use

Step 2: Register with the Bot

For OpenShock Users

Run:

/openshock setup

A form will appear asking for your API token. Paste it and submit. The bot will verify your credentials and show you a list of devices to add.

For PiShock Users

Run:

/pishock setup

A form will appear asking for your username and API key. After registering, you need to add your devices manually with share codes.

Step 3: Add Your Devices

For OpenShock Users

During setup, the bot shows your available devices. Select the ones you want to use.

To add more devices later:

/openshock add

For PiShock Users

After registering, add each device using its share code:

/pishock add

A form will ask for the share code and an optional name. You can paste either the share code or the full PiShock share URL.

To get a share code from the PiShock app:

  1. Open the app and select your shocker
  2. Tap Share and create a new code
  3. Copy the code or share URL and paste it into the bot

Managing Your Device Status

By default, the bot assumes you are wearing your device. When you need to take it off, you can update your status:

/openshock device_status

This toggles between wearing and not wearing. When set to not wearing, controllers cannot send shocks to you. They will see an error message instead.

Use this when:

  • Taking off the device temporarily
  • You are unavailable for play
  • You need a quick safety measure without removing permissions

Check your current status with:

/openshock check_device

Basic Usage

Sending Shocks

The main command for sending a shock is:

/shock

Parameters:

  • user - Who to shock (yourself or someone who gave you permission)
  • intensity - Strength from 1 to 100
  • duration - Length in milliseconds (300 to 65535)
  • action - Shock, Vibrate, or Sound
  • shocker_id - Which device to use if you have multiple

Examples:

Shock yourself:

/shock intensity:30 duration:1000 action:Shock

Shock someone who gave you permission:

/shock user:@Alice intensity:40 duration:1500 action:Vibrate

Use your saved defaults:

/shock

Smart Defaults

The bot remembers your settings. When you use /shock without specifying all parameters, it uses your previous values.

To set your preferred defaults:

/preferences set_defaults intensity:30 duration:1000 action:Shock

View your current settings with:

/preferences view

The Controller System

Bot Shock uses a consent-based permission system. Nobody can control your device unless you explicitly allow them.

Giving Someone Permission

To let someone control your device:

/controllers add

A menu appears where you can select specific users, roles, or both. Choose the people you trust, review your selections, and confirm.

Viewing Your Controllers

See who has permission:

/controllers list

This shows all users and roles that can control you, along with when permission was granted.

Removing Permission

To revoke access:

/controllers remove user:@JohnDoe

Or remove a role:

/controllers remove role:@SomeRole

They lose access immediately.

Safety Tips

Good practices:

  • Only add people you trust completely
  • Review your controller list regularly
  • Remove permissions when relationships change
  • Establish boundaries and safewords outside of Discord

Things to avoid:

  • Adding people because you feel pressured
  • Giving permissions just to test if the bot works
  • Leaving old permissions active
  • Assuming role-based permissions are always safe

Scheduled Reminders

Reminders are shock commands that run automatically at scheduled times.

Creating a Reminder

/remind set time:"in 10 minutes" intensity:30 duration:1000 action:Shock

Time formats you can use:

  • in 5 minutes
  • in 2 hours
  • tomorrow at 3pm
  • next monday at 9am
  • 2024-12-25 14:30

Recurring Reminders

Add the recurrence parameter to repeat:

/remind set time:"tomorrow at 8am" intensity:25 duration:1000 action:Vibrate recurrence:"every weekday"

Recurrence patterns:

  • every day
  • every weekday (Monday through Friday)
  • every 2 hours
  • every monday at 10am
  • every 30 minutes

Managing Reminders

View all your reminders:

/remind list

Get details on a specific reminder:

/remind info reminder_id:42

Cancel a reminder:

/remind cancel reminder_id:42

Word Triggers

Triggers automatically shock you when you send a message containing certain words or phrases.

How Triggers Work

  1. You create a trigger with a pattern to match
  2. When you send a message matching that pattern, the trigger activates
  3. The configured shock is sent
  4. A cooldown prevents the trigger from activating again for a set time

Creating a Trigger

/trigger add intensity:30 duration:1000 action:Shock cooldown:60

A form appears asking for:

  • Trigger Name (optional) - A description for your reference
  • Pattern - The words or phrases to match

Pattern examples:

  • bad word matches "bad word"
  • oops|mistake|whoops matches any of those words
  • \bstupid\b matches "stupid" as a whole word only

Test your patterns at regex101.com before creating triggers.

Managing Triggers

View all triggers:

/trigger list

Disable a trigger without deleting it:

/trigger toggle trigger_id:7 enabled:False

Re-enable it:

/trigger toggle trigger_id:7 enabled:True

Delete permanently:

/trigger remove trigger_id:7

Trigger Safety Tips

Start with safe values:

  • Intensity: 25 to 30 percent
  • Duration: 1000 milliseconds (1 second)
  • Cooldown: 60 to 120 seconds

Test carefully. Create the trigger with low intensity, test it with a few messages, check if the pattern is too broad or too narrow, then adjust as needed.

Action Logs

Every shock command is logged for transparency and safety.

Viewing Logs

/logs view

Parameters:

  • days - How far back to look (1 to 90, default is 7)
  • page - Page number for long lists

Each entry shows who sent the command, who received it, the shock details, and whether it came from a manual command, reminder, or trigger.

Exporting Logs

Download your logs as a spreadsheet:

/logs export days:90

Why Logs Matter

Logs provide accountability, help you detect unauthorized activity, let you analyze patterns, and give you documentation if you ever need it.

Review your logs regularly, especially if you have multiple controllers or triggers.

Safety and Best Practices

Start Slow

For new users:

  1. Begin with intensity around 20 to 30 percent
  2. Use short durations of 500 to 1000 milliseconds
  3. Test in a safe, private environment
  4. Gradually increase as you learn your limits

Establish Boundaries

Before giving someone control:

  • Discuss limits and expectations
  • Establish safewords or signals outside of Discord
  • Agree on maximum intensity and frequency
  • Set clear rules about when control is active

Regular Reviews

Check these things weekly:

  • Who has controller permissions
  • What reminders are active
  • What triggers are active
  • Action logs for unusual activity
  • That your device status is correct

Emergency Procedures

If something goes wrong:

  1. Disable your device status immediately with /openshock device_status
  2. Disable triggers with /trigger toggle trigger_id:X enabled:False
  3. Cancel reminders with /remind cancel reminder_id:X
  4. Remove controller access with /controllers remove user:@Person
  5. If necessary, unregister completely with /openshock unregister
  6. Power off the physical device

Always have a way to stop things outside of Discord. Keep the OpenShock or PiShock app on your phone, know where the device power switch is, and have someone you trust available to help.

Privacy

The bot stores your Discord user ID, your encrypted API token, your device IDs, who can control you, and the history of all shock commands.

Keep your Discord account secure, do not share your API token, and understand that whoever runs the bot can access the database.

Frequently Asked Questions

Can I use the bot in DMs?

No, the bot only works in servers. This is for accountability and the permission system.

Can I control multiple people?

Yes, if each person gives you permission with /controllers add.

What happens if I lose my encryption key?

If you are the bot administrator, users will need to re-register with /openshock setup. If you are a user, the administrator will need to help you.

How do I know if someone tried to control me without permission?

Check your logs with /logs view. All attempts are recorded.

Can I use both OpenShock and PiShock?

Each registration is for one platform. If you want to use both, you would need separate registrations in different servers, or the bot administrator would need to support multiple accounts.

What if the API is down?

Commands will fail. Check the status page for your platform.

Can triggers activate in any channel?

Yes, in any channel the bot can see. Be careful in public channels.

Getting Help

Your safety comes first. Do not hesitate to use emergency procedures if you need them.