Get Started — ClawPing

01. Prerequisites

Make sure you have these before starting. The whole stack runs on Python with minimal dependencies.

✓

System Requirements

ClawPing requires Python 3.9+ and runs on Linux, macOS, or Windows. Docker is optional but recommended for production.

bash

# Check Python version (must be 3.9+)
python3 --version

# Check pip
pip3 --version

# Optional: Check Docker
docker --version

🤖

Telegram Bot Token

You need a Telegram Bot token. Create one via @BotFather on Telegram — it's free and takes 30 seconds.

💡

How to get it: Open Telegram → search @BotFather → send /newbot → follow the steps → copy the token that looks like 123456:ABCdef...

📧

SMTP Credentials (for Email)

For email notifications, you need SMTP access. Gmail with an App Password works great, or use any SMTP provider.

💡

Gmail: Go to Google Account → Security → 2-Step Verification → App Passwords → Generate one for "Mail". Use smtp.gmail.com:587 with TLS.

02. Install ClawPing

Choose your preferred installation method. Docker is recommended for production; pip install is faster for development.

Option A — Docker (Recommended)

bash

# Pull the official ClawPing image
docker pull clawping/clawping:latest

# Run with environment variables
docker run -d \
  --name clawping \
  --restart unless-stopped \
  -p 8000:8000 \
  -e TELEGRAM_BOT_TOKEN="your_token_here" \
  -e SMTP_HOST="smtp.gmail.com" \
  -e SMTP_PORT="587" \
  -e SMTP_USER="you@gmail.com" \
  -e SMTP_PASS="your_app_password" \
  -v clawping_data:/app/data \
  clawping/clawping:latest

# Verify it's running
docker logs clawping

Option B — pip install

bash

# Create virtual environment
python3 -m venv clawping-env
source clawping-env/bin/activate  # Windows: clawping-env\Scripts\activate

# Install ClawPing
pip install clawping

# Initialize config
clawping init

# Start the service
clawping start

Option C — Clone from Source

bash

git clone https://github.com/clawping/clawping.git
cd clawping

# Create venv and install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Copy example config
cp .env.example .env

# Start the FastAPI server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

03. Configuration

ClawPing is configured via environment variables or a .env file in the project root.

.env

# ─── Telegram ───────────────────────────────
TELEGRAM_BOT_TOKEN=123456:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_CHAT_ID=437734870          # Default chat to notify

# ─── Email / SMTP ────────────────────────────
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASS=your_app_password_here
EMAIL_FROM="ClawPing "
EMAIL_TO=you@yourdomain.com         # Default recipient

# ─── API ─────────────────────────────────────
API_SECRET_KEY=your-secret-key-here
API_PORT=8000
API_HOST=0.0.0.0

# ─── Scheduler ───────────────────────────────
SCHEDULER_TIMEZONE=UTC
MAX_PINGS_PER_USER=100

# ─── Storage ─────────────────────────────────
DATABASE_URL=sqlite:///./data/clawping.db

Environment Variables Reference

Variable	Description	Required
TELEGRAM_BOT_TOKEN	Token from @BotFather	required
TELEGRAM_CHAT_ID	Default Telegram chat ID	optional
SMTP_HOST	SMTP server hostname	required
SMTP_PORT	SMTP port (587 for TLS)	required
SMTP_USER	SMTP login username / email	required
SMTP_PASS	SMTP password or app password	required
API_SECRET_KEY	Secret for signing API tokens	required
SCHEDULER_TIMEZONE	Timezone for reminders (e.g. Asia/Jakarta)	optional
MAX_PINGS_PER_USER	Rate limit — max active pings per user	optional
DATABASE_URL	SQLite or PostgreSQL URL	optional

04. Setup Telegram

Connect ClawPing to your Telegram bot to enable chat-native commands and direct notifications.

Create your bot with @BotFather

Open Telegram, search for @BotFather, and send these commands:

/newbot
# Enter bot name: ClawPing Notifications
# Enter username: YourClawPingBot

# BotFather replies with your token:
# 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Get your Chat ID

Send a message to your bot, then visit this URL to get your Chat ID:

bash

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
# Look for: "chat": { "id": 437734870, ... }

Register slash commands

Telegram → @BotFather

/setcommands
# Select your bot, then paste:
remind - Set a time-based reminder
alert - Set a condition-based alert
repeat - Create a recurring ping
list - List all active pings
cancel - Cancel a ping by ID
ping - Send an instant test notification
help - Show available commands

Test the connection

bash

curl -X POST https://api.clawping.xyz/api/test/telegram \
  -H "Authorization: Bearer $CLAWPING_TOKEN"

# Expected response:
# { "success": true, "message": "Telegram connected ✓" }

05. Setup Email

Configure SMTP to send beautifully formatted HTML notification emails.

Configure SMTP in .env

.env

# Gmail (recommended for testing)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=yourname@gmail.com
SMTP_PASS=xxxx-xxxx-xxxx-xxxx  # App Password, NOT your real password

# SendGrid (recommended for production)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.your_sendgrid_key_here

Test email delivery

bash

curl -X POST https://api.clawping.xyz/api/test/email \
  -H "Authorization: Bearer $CLAWPING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "you@example.com"}'

# Expected response:
# { "success": true, "message": "Test email sent ✓" }

06. Your First Ping

Let's send your first real notification. Try all three methods — Telegram, API, and webhook.

Via Telegram Bot

Telegram commands

# Instant test ping
/ping Hello from ClawPing! 🔔

# 30-minute reminder
/remind 30m Check the oven

# Price alert
/alert btc below 60000 BTC dipped — check positions

# Daily standup (Mon–Fri, 9am UTC)
/repeat "0 9 * * 1-5" Daily standup reminder 📋

Via REST API

bash

# Generate an API token first
curl -X POST https://api.clawping.xyz/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"secret": "your-secret-key"}'
# Returns: { "token": "cp_eyJ0e..." }

# Create your first reminder
curl -X POST https://api.clawping.xyz/pings \
  -H "Authorization: Bearer cp_eyJ0e..." \
  -H "Content-Type: application/json" \
  -d '{
    "type":    "reminder",
    "message": "Hello from ClawPing API!",
    "delay":   "10s",
    "channel": "telegram",
    "chat_id": "437734870"
  }'

🎉

You should receive a Telegram message in ~10 seconds. If not, check the logs with docker logs clawping or clawping logs.

07. Test the API

Verify all endpoints are working correctly with this health check sequence.

bash

# Health check
curl https://api.clawping.xyz/health
# { "status": "ok", "version": "1.0.0", "uptime": "2m 34s" }

# List all pings
curl https://api.clawping.xyz/pings \
  -H "Authorization: Bearer $TOKEN"

# Interactive API docs (Swagger UI)
open https://api.clawping.xyz/docs

# ReDoc
open https://api.clawping.xyz/redoc