Документация на русском здесь

SMS server for sending messages using GSM modem

This application allows you to send text SMS and flash messages from your server with a connected GSM modem to recipients by phone number. The application also logs the sent messages and results, and displays them in the console in a beautiful and convenient way. The application is written in JavaScript via NodeJS & Express framework, and also uses the serialport-gsm library to access the connected USB devices via NodeJS. The application can be used both for monolithic applications and in a microservice architecture.

Example of work

This application makes it easy to send a message from your configured with this application server with connected GSM modem. To send a message, you need to send a POST request in JSON format from your application to your configured server. Example of the request:

  {
    "recipient": "+99362000000", // recipient's number (without spaces, in international format)
    "message": "Hello, this SMS from sms_server application" // message text
  }

The application will receive and process this request, access the modem and if no problems with the number and modem are detected, it will send a message to the specified number.

Setup

Note: it is recommended to use new generations of modems, insert a SIM card with a replenished balance and/or a purchased subscription for sending (unlimited) SMS from your service provider.

Prerequisites

• Linux OS (recommended Ubuntu (20/04 or higher), CentOS 8)
• Installed NodeJS version not lower than 12.0.0
• Connected to USB port GSM modem with prepaid tariff SIM card
• Standard Linux system drivers for working with USB ports
• IP address (static)

Connecting and identifying the modem

Before setting up, you need to connect the GSM modem with a SIM card to any available USB port on server. Next, you need to find out the address of the connected USB port by command:

ls /dev/ttyUSB*

It will show the addresses of the connected USB ports (for example /dev/ttyUSB0 or something similar, you need to remember the address of the port connected to the USB modem, it will come in handy later when setting up the application configuration). You can also use the command:

dmesg | grep tty

which will display system messages about connected devices.

Initialization and project setup

Creating and setting up a folder for the project:

mkdir sms_server && cd sms_server

Downloading the application from the stable branch of the GitHub project repository:

git clone https://github.com/yunusmi/sms_server.git .

Installing project dependencies:

npm install

Creating a .env file based on the .env.example template for storing the project configuration:

cp .env.example .env && nano .env

In the opened file, you need to edit the following values:

• MODEM_PORT - address of the connected USB port (the command ls /dev/ttyUSB* shows a list of connected ports, for example /dev/ttyUSB0, described in the previous steps)
• MODEM_MODE - modem operating mode. Can be 'SMS' or 'PDU'. By default 'PDU'
• MODEM_BAUD_RATE - speed of GSM modem in bauds. Every GSM modem has own baud rate and they has different baud rate and speed of work. Their baud rate are depends on manufacturers. You can set for your type of modem maximum baud rate.. By default 115200
• SMS_TYPE - type of SMS sent. Can be a regular text message or a flash message. This variable must have a boolean value (true/false). False - if you want the system to send regular text SMS messages, true - if it should send flash messages. By default false
• APP_PORT - port for the NodeJS application (usually 3000). By default 3000
• APP_HOST - host for the application (usually localhost). By default localhost
• TIMEOUT - maximum time (in milliseconds) to wait for a response from the modem (due to some features of the modems of some manufacturers, the response from them can be expected for a long time, as they may not issue an error, but at the same time do not respond or respond for a long time). Therefore, you need to specify the maximum allowable time to wait for a response from the modem, after this time, the program will return an error to the client with the TimeOut status. By default 30 000 ms. (30 seconds)

Launch and use

Before using, you need to install a process manager. The process manager allows you to monitor and study the logs and performance of the application in real time, as well as reload it in case of errors. It is recommended to use pm2. To install pm2, you need to enter the command:

npm install pm2

then you can run the application by entering the command:

pm2 start ./src/app.js

The application will start on the port and host specified in the .env file.

To monitor the performance of the application in real time, you need to enter the command:

pm2 start ./src/app.js

To send a message, you need to send a POST request in JSON format from your Web or BackEnd application (also you can send requests from query emulator programms as Postman or etc.) to the address
http://YOUR_SMS_CONFIGURED_SERVER_ADDRESS:APP_PORT/send-sms. Example request:

  {
    "recipient": "+99362000000", // recipient's number (without spaces, in international format)
    "message": "Hello, this SMS from sms_server application" // message text
  }

but put your real phone number instead +99362000000

The application will return a response in JSON format with information about sending the message. Example response:

  {
    "success": true,
    "message": "Message successfully has sent to +99362000000"
  }

You can also send a request from the system terminal (if curl is installed), open a new terminal window and enter the command:

    curl -X POST http://127.0.0.1:APP_PORT/send-sms -H "Content-Type: application/json" -d '{"recipient": "+99362000000", "message": "Hello, this SMS from sms_server application"}'

Load testing

To test the load on sending SMS, the speed and performance of the GSM modem, there is a separate route (POST request to /check-speed), which takes 3 parameters: count - the number of sending cycles, recipient - the phone number of the recipient, message - the text of the message. An example of a request in the terminal using curl:

curl -X POST http://127.0.0.1:3000/check-speed -H "Content-Type: application/json" -d '{"recipient": "+99300000000", "message": "Test SMS message to check speed of GSM modem", "count": 100}'

After that, you can see the output of the start of testing in the terminal console:

[22:41:30.037] INFO (127282): --------------------------------
[22:41:30.037] INFO (127282): New request: +99300000000 - Test SMS message to check speed of GSM modem
[22:41:30.037] INFO (127282): Start testing
[22:41:30.037] INFO (127282): Count of SMS: 100, message: Test SMS message to check speed of GSM modem, recipient number: +99300000000
[22:41:30.038] INFO (127282): Start sending SMS to +99300000000

Then, the server will start sending SMS to the specified number, with the text specified in the body message the specified number of times. At this time, you can observe the output in the console logs, whether it is errors or successful sends. After finish the checking process, you will get this kind of output:

[22:42:08.057] INFO (127282): Test completed successfully
[22:42:08.057] INFO (127282): Sent 100 SMS messages in 36326 ms
[22:42:08.057] INFO (127282): Speed: 3 SMS/s
[22:42:08.058] INFO (127282): Success: 99
[22:42:08.058] INFO (127282): Failure: 1

You can do the same thing if you send a POST request to the same IP address and port, with the same body of the request in Postman or any other request emulator:

  {
    "recipient": "+99300000000",
    "message": "Test SMS message to check speed of GSM modem",
    "count": 100
  }

The application also logs the sent messages and results, and displays them in the console in a beautiful and convenient way. Example output:

[2021-12-15 16:15:23] [INFO] New request: +99362000000 - Hello, this SMS from sms_server application
[2021-12-15 16:15:23] [INFO] Start sending SMS to +99362000000
[2021-12-15 16:15:24] [INFO] Message successfully has sent to +99362000000

Logging to text and debugging errors

For client applications, the response from the server, whether errors or successful submissions, will contain short responses. For more detailed error research or tracking server response statuses, logging to a text file and output to the terminal console is provided. All log entries are stored in the src/logs directory. Every day, the system will create log entries for that day and save them in the same directory. The log file name starts with the current date and ends with _log.txt

In the log entries, status - message sending status, message - text description of the status, data - all data about the sent message, including the recipient's number, message text and link to the message in the modem.

Conclusion

This project is distributed under the MIT license. You can use the full code of this project on your projects for free.

If you need any help or consultations, you can contact me by email: [email protected]