afterhours-shift-manager/SETUP.md

After-Hours Shift Manager — Setup Guide

1. Create a Slack App

1. Go to api.slack.com/apps → Create New App → From scratch
2. Name: After-Hours Shift Manager, pick your workspace
3. Under OAuth & Permissions, add these Bot Token Scopes:
   • chat:write — post messages to channels
   • commands — register slash commands
   • chat:write.public — post to channels the bot isn't in
4. Under Slash Commands, create a new command:
   • Command: /oncall
   • Request URL: (fill in after deploy — see step 4)
   • Short Description: Manage after-hours on-call shifts
   • Usage Hint: [schedule | pick <date> | drop <date> | swap <date> @person | register <ext> | roster | help]
5. Under Interactivity & Shortcuts, toggle ON:
   • Request URL: same URL as the slash command (the /slack/events endpoint)
6. Install to Workspace — approve the permissions
7. Copy the Bot User OAuth Token (xoxb-...) and Signing Secret (under Basic Information)

2. Store Secrets in SSM Parameter Store

aws ssm put-parameter \
  --name "/afterhours-shift-manager/slack-bot-token" \
  --type SecureString \
  --value "xoxb-YOUR-BOT-TOKEN"

aws ssm put-parameter \
  --name "/afterhours-shift-manager/slack-signing-secret" \
  --type SecureString \
  --value "YOUR-SIGNING-SECRET"

# Channel ID where the bot will post weekly schedules
# (right-click channel in Slack → Copy link → the ID is the last segment)
aws ssm put-parameter \
  --name "/afterhours-shift-manager/channel-id" \
  --type SecureString \
  --value "C0XXXXXXX"

3. Deploy the Stack

# Build and deploy
sam build
sam deploy --guided --stack-name afterhours-shift-manager --region us-east-1

# Note the SlackBotApiUrl output — you'll need it for step 4

4. Set the Slack Request URL

After deploy, copy the SlackBotApiUrl from the SAM output. Go back to your Slack app settings:

• Slash Commands → edit /oncall → set Request URL to the output URL
• Interactivity & Shortcuts → set Request URL to the same URL

5. Seed the Schedule

python scripts/seed_schedule.py

This populates the DynamoDB table with the employee roster and default weekly schedule.

6. Invite the Bot & Register Users

1. Create a channel (e.g. #after-hours-shifts) and invite the bot: /invite @After-Hours Shift Manager
2. Each employee links their Slack account by running:

   /oncall register 114
   

   (using their own extension number)

7. Update the 3CX Scheduler (optional)

To have the 3CX scheduler read overrides from DynamoDB (so Slack-driven changes apply to future dates automatically), deploy the updated 3CX scheduler from the feature/dynamodb-shift-integration branch. See that branch's changes for details.

Without this step, the Slack bot still works — it invokes the 3CX scheduler Lambda directly for same-day changes. Future-date overrides would only take effect if the scheduler reads DynamoDB.

Commands Reference

Command	Description
/oncall	Show this week's schedule
/oncall next	Show next week's schedule
/oncall pick <date>	Pick up a shift
/oncall drop <date>	Drop your shift (marks it open)
/oncall swap <date> @person	Hand your shift to someone else
/oncall register <ext>	Link your Slack to your extension
/oncall roster	Show all employees and their link status
/oncall help	Show help

Dates can be: today, tomorrow, monday–sunday, 4/5, 2026-04-05