admin/campaign_connector
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
campaign_connector/docs/api/endpoints.md
admin 498e1ab6ca Bunch of improvements: 
- Refactored the dashboard html into seperate pages and all the necessary components
- Added login and secured api routes / debugged getting system working on a tailnet.
- added some functionality to the debugging and health endpoints
- added in a new phone contact import and debugged.
2025-12-31 15:02:28 -07:00

10 KiB
Raw Permalink Blame History

API Endpoints Reference

Complete reference for all SMS Campaign Manager API endpoints.

Authentication

All API endpoints (except /health and /login) require authentication via:

  • API Key in X-API-Key header, or
  • Bearer Token in Authorization header, or
  • Session Cookie from web login

Base URLs

  • Ubuntu Server: http://localhost:5000
  • Tailscale: http://YOUR_TAILSCALE_IP:5000
  • Android Termux API: http://YOUR_ANDROID_IP:5001

Health & Status

GET /health

Check application health.

Authentication: None required

Response:

{
  "status": "ok",
  "version": "2.0"
}

Authentication Endpoints

POST /api/auth/login

User login (web dashboard).

Authentication: None required

Request:

{
  "username": "admin",
  "password": "your-password"
}

Response:

{
  "success": true,
  "message": "Login successful",
  "user": {
    "username": "admin",
    "role": "admin"
  },
  "redirect": "/"
}

POST /api/auth/logout

User logout.

Authentication: Session cookie required

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

GET /api/auth/status

Check authentication status.

Authentication: Session cookie required

Response:

{
  "authenticated": true,
  "user": {
    "username": "admin",
    "role": "admin"
  }
}

Campaign Management

GET /api/campaign/list

List all campaigns.

Authentication: User API key required

Response:

[
  {
    "id": 1,
    "name": "Spring Sale",
    "status": "active",
    "created_at": "2025-12-30 10:00:00",
    "total_contacts": 100,
    "sent": 50,
    "failed": 2
  }
]

POST /api/campaign/create

Create new campaign.

Authentication: User API key required

Request:

{
  "name": "Campaign Name",
  "message_template": "Hi {name}, special offer for you!",
  "contact_list_id": 1
}

Response:

{
  "success": true,
  "campaign_id": 5,
  "message": "Campaign created successfully"
}

POST /api/campaign/start

Start a campaign.

Authentication: User API key required

Request:

{
  "campaign_id": 5
}

Response:

{
  "success": true,
  "message": "Campaign started"
}

POST /api/campaign/pause

Pause running campaign.

Authentication: User API key required

Request:

{
  "campaign_id": 5
}

Response:

{
  "success": true,
  "message": "Campaign paused"
}

POST /api/campaign/resume

Resume paused campaign.

Authentication: User API key required

Request:

{
  "campaign_id": 5
}

Response:

{
  "success": true,
  "message": "Campaign resumed"
}

GET /api/campaign/status

Get campaign status and progress.

Authentication: User API key required

Query Parameters:

  • campaign_id (required): Campaign ID

Response:

{
  "id": 5,
  "name": "Spring Sale",
  "status": "running",
  "progress": {
    "total": 100,
    "sent": 45,
    "failed": 2,
    "pending": 53,
    "percentage": 45
  }
}

SMS Operations

POST /api/sms/send/enhanced

Send SMS via Termux API with retry logic.

Authentication: User API key required

Request:

{
  "phone": "+1234567890",
  "message": "Hello from SMS Campaign Manager!"
}

Response:

{
  "success": true,
  "method": "termux_api",
  "message": "SMS sent successfully",
  "timestamp": "2025-12-30 14:30:00"
}

POST /api/sms/test

Send test SMS (simulation, no actual SMS sent).

Authentication: User API key required

Request:

{
  "phone": "+1234567890",
  "message": "Test message"
}

Response:

{
  "success": true,
  "message": "Test SMS simulated successfully",
  "details": {
    "phone": "+1234567890",
    "message_length": 12,
    "estimated_cost": 0.01
  }
}

GET /api/sms/status

Get SMS sending status and statistics.

Authentication: User API key required

Response:

{
  "total_sent": 1250,
  "total_failed": 15,
  "success_rate": 98.8,
  "last_24h": {
    "sent": 120,
    "failed": 2
  },
  "connection_method": "termux_api"
}

File Upload

POST /api/csv/upload

Upload CSV file with contacts.

Authentication: User API key required

Request: multipart/form-data

  • file: CSV file with columns: phone, name (optional: message, email, etc.)

Response:

{
  "success": true,
  "filename": "contacts_20251230.csv",
  "contacts_imported": 150,
  "list_id": 3
}

POST /api/campaign/upload

Upload CSV and create campaign in one step.

Authentication: User API key required

Request: multipart/form-data

  • file: CSV file
  • campaign_name: Campaign name
  • message_template: Message template with {variables}

Response:

{
  "success": true,
  "campaign_id": 6,
  "contacts_imported": 150,
  "message": "Campaign created and ready to start"
}

Phone/Device Status

GET /api/phone/status

Check Android device connection and status.

Authentication: User API key required

Response:

{
  "connected": true,
  "ip_address": "100.107.173.66",
  "termux_api": {
    "available": true,
    "port": 5001,
    "last_check": "2025-12-30 14:35:00"
  },
  "adb": {
    "available": false,
    "fallback_mode": false
  },
  "battery": {
    "percentage": 85,
    "status": "charging"
  }
}

Database Operations

GET /api/database/stats

Get database statistics.

Authentication: User API key required

Response:

{
  "campaigns": 12,
  "contacts": 5430,
  "messages_sent": 15280,
  "success_rate": 98.2,
  "database_size_mb": 45.6,
  "users": 5
}

POST /api/database/reset

Reset database (destructive operation).

Authentication: Admin API key required

Request:

{
  "confirm": true
}

Response:

{
  "success": true,
  "message": "Database reset successfully",
  "warning": "All data has been deleted"
}

Admin Endpoints

GET /api/admin/users

List all users (admin only).

Authentication: Session cookie + admin role required

Response:

[
  {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "created_at": "2025-12-30 10:00:00",
    "last_login": "2025-12-30 14:00:00",
    "is_active": true
  },
  {
    "id": 2,
    "username": "user1",
    "role": "user",
    "created_at": "2025-12-30 11:00:00",
    "is_active": true
  }
]

POST /api/admin/users/create

Create new user (admin only).

Authentication: Session cookie + admin role required

Request:

{
  "username": "newuser",
  "password": "SecurePassword123!",
  "role": "user",
  "email": "user@example.com",
  "full_name": "New User"
}

Response:

{
  "success": true,
  "user_id": 3,
  "message": "User created successfully"
}

DELETE /api/admin/users/

Delete user (admin only).

Authentication: Session cookie + admin role required

Response:

{
  "success": true,
  "message": "User deleted successfully"
}

Android Termux API Endpoints

Base URL: http://YOUR_ANDROID_IP:5001

GET /health

Check Termux API server health.

Authentication: None required

Response:

{
  "status": "healthy",
  "uptime_seconds": 3600,
  "version": "1.0"
}

POST /api/sms/send

Send SMS via Termux API (internal use).

Authentication: Termux API key required

Request:

{
  "phone": "+1234567890",
  "message": "Hello!"
}

Response:

{
  "success": true,
  "message": "SMS sent successfully",
  "timestamp": "2025-12-30 14:40:00"
}

GET /api/device/battery

Get Android device battery status.

Authentication: Termux API key required

Response:

{
  "percentage": 85,
  "status": "charging",
  "temperature": 32.5,
  "health": "good"
}

Error Responses

All endpoints may return these error statuses:

401 Unauthorized

{
  "error": "Authentication required",
  "message": "Please provide valid API key or login"
}

403 Forbidden

{
  "error": "Insufficient permissions",
  "message": "Admin role required for this operation"
}

404 Not Found

{
  "error": "Resource not found",
  "message": "Campaign with ID 999 does not exist"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please wait before trying again."
}

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "An unexpected error occurred",
  "details": "Error details here"
}

Rate Limits

Default rate limits per IP address:

  • /api/auth/login: 5 requests/minute
  • /api/sms/*: 10 requests/minute, 100/hour, 500/day
  • /api/csv/upload: 10 requests/hour, 50/day
  • /api/database/reset: 2 requests/hour
  • All other endpoints: 200 requests/hour, 1000/day

Rate limit headers included in responses:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1767117854

Usage Examples

Using curl

# With API key header
curl -H "X-API-Key: YOUR_API_KEY" \
  http://localhost:5000/api/campaign/list

# With Bearer token
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:5000/api/campaign/list

# POST with JSON data
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+1234567890","message":"Hello"}' \
  http://localhost:5000/api/sms/send/enhanced

# File upload
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@contacts.csv" \
  http://localhost:5000/api/csv/upload

Using Python requests

import requests

API_KEY = "your-api-key-here"
BASE_URL = "http://localhost:5000"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# List campaigns
response = requests.get(f"{BASE_URL}/api/campaign/list", headers=headers)
campaigns = response.json()

# Send SMS
data = {
    "phone": "+1234567890",
    "message": "Hello from Python!"
}
response = requests.post(
    f"{BASE_URL}/api/sms/send/enhanced",
    headers=headers,
    json=data
)
print(response.json())

# Upload CSV
files = {"file": open("contacts.csv", "rb")}
response = requests.post(
    f"{BASE_URL}/api/csv/upload",
    headers={"X-API-Key": API_KEY},
    files=files
)
print(response.json())

Related Documentation