Skip to content

SMS Gateway Service (cbsms)

Status: Active URL: https://sms.nominate.ai Port: 32207

Overview

cbsms is an SMS Gateway API for interacting with Ejoin SMS/MMS gateway devices. It provides a FastAPI-based REST API for sending SMS/MMS messages, managing device status, and handling webhooks.

Quick Start

# Activate environment
source ~/.pyenv/versions/nominates/bin/activate

# Start development server
./startit.sh
# Or: uvicorn src.api.main:app --port 32207 --reload

# Run tests
pytest tests/ -v

API Endpoints

SMS Operations

Method Endpoint Description
POST /api/sms/send Send single SMS
POST /api/sms/send-mms Send MMS with attachments
POST /api/sms/send-bulk Send bulk SMS
POST /api/sms/status Get task status
POST /api/sms/pause Pause task
POST /api/sms/resume Resume task
POST /api/sms/delete Delete task

Device Management

Method Endpoint Description
GET /api/status/device Get device status
POST /api/status/command Send device command

Webhooks

Method Endpoint Description
POST /api/webhooks/sms Receive incoming SMS
POST /api/webhooks/status Receive status reports
GET /api/webhooks/recent-responses Get recent SMS responses

Architecture

Client → cbsms API → Ejoin Device → Mobile Network
             ↓
        SQLite DB

Key Components

  • FastAPI Application - REST API with Swagger docs at /docs
  • SQLAlchemy ORM - SQLite database for message tracking
  • Service Layer - Business logic for SMS, device, and webhook handling
  • VictoryText App - WebSocket-based messaging interface

Configuration

Environment variables (.env):

Variable Description
DEVICE_IP Ejoin device IP address
DEVICE_USERNAME Device authentication username
DEVICE_PASSWORD Device authentication password
DATABASE_URL SQLite URL (e.g., sqlite:///./sms_gateway.db)
WEBHOOK_SECRET Secret for webhook authentication
SMS_FORWARD_URL URL for forwarding SMS status reports

Deployment

  • Systemd Service: systemd/cbsms.service
  • Health Endpoint: /health (NGINX health bypass)

Additional Resources