SMS Gateway for Android™ (SMSGate) Web Client

A demonstration app that utilizes the SMS Gateway for Android to create an SMS management web interface
Explore the source »

Report Bug · Request Feature

• 🌐 About The Project
  • Key Features
  • Built With
• 🚀 Getting Started
  • 📋 Prerequisites
  • 📦 Installation
  • ⚙️ Configuration
• 💻 Usage
  • Development Mode
  • Production Build
  • Production Start
• ⚙️ Technical Implementation
  • Event Sequence
  • Client Events
  • Server Events
  • CSV Bulk Send
• 🤝 Contributing
• 📄 License

🌐 About The Project

This web client serves as the frontend component of the SMS Gateway for Android ecosystem, providing a user-friendly interface for managing SMS communications through the SMS Gateway for Android app. It connects to both cloud and private server deployments, enabling real-time SMS management capabilities.

Key Features

• 🌐 Connect to any account registered on Cloud/Private server
• 📩 Real-time receipt of SMS messages
• 📤 Capability to send SMS messages
• 🔒 Session-based authentication with no persistent credential storage

The application follows strict privacy practices - credentials are stored only in session memory (cleared upon logout) and SMS messages are not stored persistently.

Built With

• 🟩 Node.js
• 📦 npm/yarn
• ⚡ Socket.IO
• 📘 TypeScript

(back to top)

🚀 Getting Started

📋 Prerequisites

• Node.js (v18+)
• npm or yarn package manager

📦 Installation

1. Clone the repository:

   git clone https://github.com/android-sms-gateway/web-client-ts.git

2. Navigate to the web client directory:

   cd web-client-ts

3. Install dependencies:

   npm install

   or with yarn:

   yarn install

⚙️ Configuration

Create a .env file in the project root with the following environment variables (see .env.example for a ready-to-copy template):

Variable	Description	Default Value
HTTP__PORT or PORT	Server listening port	3000
HTTP__SESSION_SECRET	Session encryption secret	random bytes (32 bytes)
GATEWAY__URL	SMS Gateway API URL	https://api.sms-gate.app/3rdparty/v1
GATEWAY__WEBHOOK_URL	External address for webhooks (<your-url>/api/webhooks)	http://localhost:<your-configured-port>/api/webhooks
NODE_ENV	Application environment (development or production)	production

For complete configuration options, see src/config.ts.

Notes:

• Do not commit your .env file to version control.
• Always set a strong, unique HTTP__SESSION_SECRET in production (rotate it periodically). If not provided, the app may auto-generate one for development only.

(back to top)

💻 Usage

After starting the server, navigate to http://localhost:<your-configured-port> to access the web interface.

Development Mode

npm run dev

Production Build

npm run build

Production Start

npm start

(back to top)

⚙️ Technical Implementation

The application uses Socket.IO for real-time communication between client and server. All communication follows a strict event-based protocol.

Event Sequence

1. Client sends login with credentials
2. Server responds with login:success or login:fail
3. Client sends sms:send to send a message to a single recipient
4. Client sends sms:send:bulk to send a message to multiple recipients (CSV bulk send)
5. Server sends sms:received for incoming messages
6. Client sends logout to terminate session
7. Server responds with logout:success

Client Events

• login - Authentication attempt
• sms:send - Send SMS message to single recipient
• sms:send:bulk - Send SMS message to multiple recipients
• logout - Terminate session

Server Events

• sms:received - Incoming SMS notification
• login:success - Successful authentication
• login:fail - Authentication failure
• logout:success - Successful logout

CSV Bulk Send

The application supports sending messages to multiple recipients via CSV upload:

• Upload a CSV file with columns: phoneNumber (required) and message (optional)
• If the message column is not present, a default message is used for all recipients
• Messages are sent individually if per-recipient messages are provided
• All phone numbers receive the same default message if no message column is present

(back to top)

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

📄 License

Distributed under the Apache-2.0 License. See LICENSE for more information.

(back to top)