Overview

This repository contains a .Net 8 service that can run on both Windows and Linux operating systems, along with a database installation tool.
The service interacts with a Microsoft SQL Server database and retrieves SMS messages from a table and sends them to SMSPortal using the RESTful API. It also retrieves Delivery Receipts (DLRs), replies and short messages sent to hosted short codes from SMSPortal and writes them to the same database.

Prerequisites

• Microsoft SQL Server 2016 or later
• Windows 10, 11, or Windows Server 2012 or later, OR Ubuntu 20.04 or later.
• .Net 8 runtime installed (Download)

Building from Source

The following are prerequisites in order to build the service from the source code. If you need access to the source code, please contact our support team via email at [email protected].

• NuGet package manager (included with .NET SDK)
• .NET 8 SDK installed (Download)
• Build Tools. The project uses the .Net CLI (dotnet build) to compile the source code.

Database Installation

The repository includes the source code for an executable sets up the required database schema.

Steps

1. Download the binaries from our links below, both Windows and Linux versions are available:
2. Edit the appsettings.json and modify the connection string contained in the file to have the desired database name and the
   correct credentials for a user that has the necessary permissions to create databases, tables and stored procedures.
3. Run the following command:

C:\path\to\executable\PhotonDbInstaller.exe

4. The executable will connect to SQL Server and install the database and necessary schema.
5. Consult the log file to ensure the database was installed successfully and that there are no error messages.

Installation of Service

As mentioned in the requirements the service can either be installed on Windows or Ubuntu. Obtain binaries targeting the chosen operating system by
either building from source or downloading and then following the appropriate instructions.

Windows Installation

1. Open a command prompt with administrator privileges.
2. Skip to step 5 if you already have the binaries.
3. Navigate to the project root of the source code and restore dependencies:

C:\path\to\source\dotnet restore

4. Build the project:

C:\path\to\source\dotnet publish -c Release -r win-x64 --self-contained false

5. Install the service using Service Control Manager

sc create Photon binPath= "C:\path\to\published\Photon.exe"

6. Start the service using either the Services Managment Console or

sc start Photon

Linux Installation

Photon has only been tested on Ubuntu but may be able to run on a different distribution of Linux. To install and run the service as a systemd service on Ubuntu:

1. Navigate to the project root of the source code and restore the dependencies:

dotnet restore

2. Install the require Linux-specific dependencies:

dotnet add package Microsoft.Extensions.Hosting.Systemd

3. Remove the follwing line from Program.cs:

builder.UseWindowsService();

4. Add the following line in its place:

builder.UseSystemd();

5. Build the project targeting Linux:

dotnet publish -c Release -r linux-x64 --self-contained false

6. Create a systemd service file:

sudo nano /etc/systemd/system/photon.service

Add the following content:

[Unit]
Description=Photon SMS Service
After=network.target

[Service]
ExecStart=/path/to/published/Photon
Restart=always
User=your-username
Group=your-group
WorkingDirectory=/path/to/published

[Install]
WantedBy=multi-user.target

7. Reload systemd and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable myservice
sudo systemctl start myservice

8. Ensure that the binary file is executable by assigning the necessary permissions

chmod +x /path/to/published/Photon

The path above has been used for illustration purposes, you can use your preferred location.

Create an API Key

Photon uses SMSPortal's RESTful API to send SMS messages and receive DLRs, replies and SMS messages to short codes.
You will need to create an API Key for Photon to use to Authenticate with SMSPortal. Please consult the REST API's Quick Start Guide for more details on how to create an API Key.

Settings

The Photon service can be configured by editing the appsettings.json file in the root directory of the service. The
following can be configured.

Example

The following is an example of the appsettings.json file with proxy configured.

{
  "ConnectionStrings": {
    "SmsServiceDb" : "Server=localhost;Database=sms_service2;Trusted_Connection=true;Encrypt=false"
  },
  "SmsPortalApiUrl": "https://rest.smsportal.com",
  "ProxyServer" : {
    "Ip": "192.0.2.0",
    "Port": 12345,
    "Username": "proxy-username",
    "Password": "proxy-password",
    "Domain": "domain-name"
  }
}

The remaining settings are stored in ApiKeys table in the sms_service2 database. The following section describes the table in more detail.

Basic Usage

API Keys

API Keys can be added to the ApiKeys table using Microsoft SQL Sever Management Studio by directly editing the table. You can also use the following SQL script to insert
an API Key.

INSERT INTO ApiKeys (ClientId, ApiSecret, GetRepliesInterval, GetDRInterval)
VALUES ('Your_ClientId', 'Your_ApiSecret', 1, 1)

Please take note of the value of the ID colum from the newly inserted row. It is needed in the next section.

Sending a Short Message and Checking its Status

Insert a row in the Queue table to schedule a SMS to be sent. The following SQL script provides an example.

DECLARE @ApiKeyId INT = 1 -- Replace with the value of the ID column from the previous section.

INSERT INTO Queue (ApiKeyId, NumTo, Content)
VALUES (@ApiKeyId, 27720000000, 'Test Message')

The row is moved from the Queue table to the Sent table once it has been successfuly submitted to SMSPortal. A delivery receipt is sent by the handset after receiving the SMS. Photon updates the
status of the message in the Sent when it receives notification of the delivery receipt. The script below is used for illustration purposes only and should not be used in a production environment with a lot of traffic.

SELECT *
FROM Sent
WHERE NumTo = 27720000000

Replies and Messages to Short Codes

Replies and SMS messages to short codes will be inserted into the Reply and ShortCode table respectively. The below scripts are used for illustration purposes
only and should not be used in a production environment with a lot of traffic.

SELECT * 
FROM Reply

SELECT *
FROM ShortCode

Changes

This section outlines the biggest changes between the old service and Photon

• Previous system used web services and Photon uses RESTful over HTTPS.
• Previous system had a Users table. Photon has an ApiKeys table
• Photon no longer has columns for MessageType, Flash and Data2. Data1 has been renamed Content.

License

Photon is made available under the MIT License.

Security

When configuring IP whitelisting for any apiKey's used by this integration, please ensure that you first determine all possible public IP addresses our servers could recieve requests from.

• If you are running this service on a dedicated host in a DC with a static Public IP, then that single entry is sufficent. If not, please contact relevant support personal (or your ISP of choice) to determine what range of IP's your server could make Outbound requests on.
• If you are unsure what your public IP is of the production server but are certain it is static, then you can make a call from that server to https://cp.smsportal.com/aegis/api/v1/public/ip-lookup. Assuming no proxy is added after the fact, the response body will contain the IP our servers will see for requests made from that machine.
• If you are running your infrastructure in the cloud you very likely do not have a static public IP. However, most cloud providers provide publically available lists of their IP blocks.
  • AWS
  • Azure
  • Google Cloud
• Whilst you can add all the ranges in such lists, we recommend isoloating the regions your servers run under and only include those ranges.
• If you are using a proxy, our servers will only see the Public IP of that proxy server, so please ensure the API Keys are configured with the proxy's possible IP addresses as explained above.

Migration

Photon was designed to be a complete replacement for the previous SQL API. For this reason a new Database and tables are
installed.

Modifications

If your version of the legacy SQL API has modifications from the original source code that was made available then it is
advised that similar modifications are made to this source code otherwise features may be lost. The following steps are only applicable for those that have the previous SQL API service without any modifications. It is further advised that migrating to Photon is attempted in QA and UAT environments before attempting a migration in a production environment.

Steps

1. Install the database and Photon service. See Installation Instructions.
2. Stop writing rows into the Queue table.
3. Stop the legacy API service, use the Microsoft Services Management console to stop the _SmsService.
4. If there are still rows remaining in the Queue table then execute the script to move those rows to the new database.
5. Ensure that there are API Keys available for your account by using the SMSPortal control panel. See [link]
6. Add the Client IDs and API Secrets to the ApiKeys table.
7. Start the Photon service
8. Check log files for any issues.

Troubleshooting

Installation

Logging

Photon uses the Serilog logging framework which implements logging abstractions provided in the Microsoft.Extensions.Hosting package.
The service sets up basic logging to a file as a starting point and includes logging to console in development environments. The logging framework used can be swapped out for a different 3rd party library or even a custom one. For more information on how to further configure Serilog please visit their project page.

Another popular alternative to Serilog is NLog and provides similar functionality and extensibility.

Support

If you are having any difficulty or require any further assistance you can contact SMSPortal via email at [email protected] or phone
+27 86 111 2021.

Versioning