Oref Alerts Slack Bot

Real-time Pikud HaOref (Israel Home Front Command) emergency alerts in Slack. Users pin their locations and get @mentioned when an alert affects their area.

Features

• Polls the official oref.org.il endpoint every 3 seconds
• Color-coded severity sidebar (red for danger, yellow for drills)
• English alert labels with Hebrew zone names
• Users subscribe to zones via /oref pin <zone> and get @mentioned
• Threaded check-in prompt after each alert — react ✅ to confirm you're safe
• Dynamic zone list fetched from Pikud HaOref and cached locally
• Runs via Socket Mode — no public URL or ngrok needed
• SQLite storage, Docker-ready

Slack App Setup

Option A: Create from manifest (recommended)

1. Go to api.slack.com/apps
2. Click Create New App → From an app manifest
3. Select your workspace
4. Paste the contents of slack-manifest.yml
5. Click Create

Option B: Create manually

1. Go to api.slack.com/apps → Create New App → From scratch
2. Name it Oref Alerts, select your workspace

Enable Socket Mode:

3. Go to Settings → Socket Mode → toggle Enable Socket Mode
4. Create an App-Level Token with the connections:write scope — save the xapp-... token

Add slash command:

5. Go to Features → Slash Commands → Create New Command
   • Command: /oref
   • Short description: Manage Oref alert location subscriptions
   • Usage hint: [pin|unpin|zones|my-locations] [zone name or search query]

Set bot scopes:

6. Go to Features → OAuth & Permissions → Scopes → Bot Token Scopes
   • channels:manage, chat:write, commands, im:history, reactions:write, users:read

Install:

7. Go to Settings → Install App → Install to Workspace
8. Copy the Bot User OAuth Token (xoxb-...)

Get the channel ID

9. In Slack, right-click the channel where alerts should be posted → View channel details → scroll to the bottom to find the Channel ID (starts with C)

Configuration

Copy .env.example to .env and fill in:

SLACK_BOT_TOKEN=xoxb-...          # Bot User OAuth Token (step 8)
SLACK_APP_TOKEN=xapp-...          # App-Level Token (step 4)
ALERT_CHANNEL_ID=C0123456789      # Channel ID (step 9)

Optional:

DB_PATH=./oref.db                 # SQLite database path
DATA_DIR=./data                   # Zone cache directory
POLL_INTERVAL=3                   # Seconds between polls

Running

With Docker (recommended)

cp .env.example .env
# edit .env with your tokens

docker compose up --build

Locally with uv

uv sync
uv run python -m oref_alerts.main

Usage

Once the bot is running and connected to Slack:

Command	Description
/oref zones תל אביב	Search for zones matching a query
/oref pin תל אביב - מרכז העיר	Subscribe to alerts for a zone
/oref unpin תל אביב - מרכז העיר	Unsubscribe from a zone
/oref my-locations	List your pinned zones
/oref lang en	Switch to English responses
/oref	Show help

All responses are ephemeral (only visible to you). When an alert fires, the bot posts to the configured channel and @mentions users who have pinned the affected zones. A threaded check-in prompt follows each alert — team members react ✅ to signal they're safe.

Development

uv sync                  # install deps including dev
uv run pytest            # run tests

Architecture

asyncio event loop
├── Slack Socket Mode (outbound WebSocket)
│   ├── /oref slash command handler
│   └── DM handler (pin/unpin/zones via direct message)
├── Oref Poller (aiohttp, every 3s)
│   └── Alert Processor → dedup → lookup users → Block Kit message → Slack
│       └── Threaded check-in prompt with seeded ✅ reaction
└── Zone Refresher (every 12h)
    └── Fetch zone list from oref.org.il → cache to disk

Invite the bot

After setup, invite the bot to your alerts channel:

/invite @Oref Alerts