How to receive sms in C#

This article gives information about how to receive sms in C# with the Ozeki C# SMS API. It provides some example code you can use and outlines the steps you need to take. To complete the steps, you need about 5 minutes. In a nutshell, to receive an SMS with the C# SMS API you need to sign up to the OnMessages received event, and write the event handler method that will process the incoming SMS sent by the Ozeki SMS gateway. Read on to learn more about this procedure!

Why do you want to receive sms in C#?

To receive sms in C# there are various reasons. You might want to collect data from sensor or mobile users, you may create sms services that send a reply with information, or you can simply ask your users to confirm that they have received an SMS.

Prerequisites

How to receive sms in C# (Quick steps)

How to receive sms in C#
  1. Download the C# SMS receive example
  2. Open the solution in Visual Studio
  3. Connect to Ozeki SMS Gateway
  4. Receive a simulated SMS in C#
  5. Connect to the mobile network
  6. Receive an SMS in C# that was sent from a mobile
  7. Check the logs in the SMS gateway
  8. Check the delivery report on your mobile

receive sms in c#
Figure 1 - Receive sms in C#

C# code sample for receiving text messages

The C# sms code sample below outlines the most important steps to take to create an SMS receiving service. The Ozeki C# sms api comes free of charge. You can modify the api library, the examples that come with it, and you can use it in your project and freely redistribute it or its derivatives. The following example shows you how to subscribe to the OnMessageReceived C# event, and how to handle this event. The example prints the incoming SMS message to the console. 


class Program
{
    static OzxClient Client;

    static void Main(string[] args)
    {
        Client = new OzxClient();
        Client.AutoReconnect = true;
        Client.OnMessageReceived += Client_OnMessageReceived;
        
        Client.Connect("127.0.0.1",9580,"testuser","testpass");
    }

    static void Client_OnMessageReceived(object sender, OzxArgs<IOzxMessage> e)
    {
        Console.WriteLine("Message received: " + e.Item.ToString());
    }
}

The e.Item parameter is a full OzxMessage. This means, that you have all the details of the SMS messages in your C# sms api event. These details include the SMS sender ID, the phone number where the SMS was sent to, the SMS text, and the corresponding timestamps.

One of the biggest advantages to using the Ozeki C# SMS API is that you get incoming SMS messages instantly. As soon as they hit the SMS gateway, they are forwarded to your C# SMS client through the established TCP/IP link. This means you will not experience any delays.

If you C# sms api client is not connected to the SMS gateway when the SMS is received, the SMS is stored in the inbox folder of the SMS gateway. This means your incoming messages will not get lost event if the sms software you have written using the C# sms api is offline. This is due to the fact that Ozeki SMS Gateway is actually an SMS server.

Step 1 - Download the Ozeki C# sms library

Navigate to https://ozeki-sms-gateway.com/attachments/5755/OzekiConsole.zip and download the zip file with your browser. The zip file will end up in your Download directory (Figure 2). You can open the download directly in Windows Explorer. The downloaded zip package will contain the example code you can use to receive sms in C#.

ozeki SMS library downloaded
Figure 2 - Ozeki SMS library downloaded

Step 2 - Extract the C# sms library

Extract the C# sms library by clicking on the OzekiConsole.zip file with the right mouse button (Figure 2). This will bring up the context menu. In the Context menu select "Extract All...". This will show the "Extract dialog window", where you have to click Extract.

Click the "Extract" button in the "Extract All" dialog window (Figure 3).

Extract the SMS C# receive example
Figure 3 - Extract the SMS C# receive example

Step 3 - Open the project in Visual studio

Open the OzekiConsole folder. This folder will appear, after you have extracted the OzekiConsol.zip package. In the OzekiConsole folder double click on the OzekiConsole.sln file. This will show the "How do you want to open this file?" dialog box. In this dialog box select "Visual Studio". After Visual Studio has been selected, click OK to open the C# sample project. (Figure 4)

Open the C# SMS receive example in Visual studio
Figure 4 - Open the C# SMS receive example in Visual studio

Step 4 - Click Program.cs

Open Program.cs by clicking on the file in the solution explorer in the left hand side of the screen. This is the main code of this example C# project. This code contains examples on how to send sms from c# and on how to receive sms in C#. The code is not too long, it is about 300 lines. It demonstrates the full functionality of the C# SMS API. (Figure 5)

Load Program.cs into the editor
Figure 5 - Load Program.cs into the editor

Step 5 - Set a break point in the SMS receiver code

Find the OnMessageReceived event handler and set a breakpoint on the begin line of the procedure. This breakpoint will give you a chance to capture the OnMessageReceived event. The OnMessageReceived event is triggered, when your C# SMS client receives the SMS message from the SMS gateway. (Figure 6)

set a breakpoint in the on sms received event
Figure 6 - set a breakpoint in the on message received event

Step 6 - Create an OZX user account for the SMS api

To let the C# sms api example connect to the SMS gateway, you need to create an OZX user account in the sms gateway. To do this navigate to the SMS gateway management console by opening the https://127.0.0.1:9515 url and click on the "Add new user/application" link in the right hand side of the screen. (Figure 7)

Create sms user account to receive text messages
Figure 7 - Create sms user account to receive text messages in C#

The "Add new user/application" link will bring up a list of installable user types. You need to find the OZX user account in the list. The OZX user account uses a highly optimizes SMS protocol, that lets your C# sms application communicate with the SMS gateway over the network. Because the SMS gateway and the C# sms client communicates over the network, you can receive a text message in your C# project even if project runs on a different computer. (Figure 8)

install to install the C# sms api user account
Figure 8 - Click install to install the C# sms api user account (OZX user)

Provide a username and password. In our example we use testuser as the username and testpass ass the password. The C# sms client will use these credentials to connect to the sms gateway. If you would like more than one C# sms api connection, you can create multiple OZX user accounts. Each user account will host its own C# sms api client. To decide which C# sms client will receive an incoming SMS, you need to create inbound routes in the Ozeki sms routing table. (Figure 9)

Set testuser as the C# sms api username
Figure 9 - Set testuser as the C# sms api username

Enable the logging options for the C# sms api account to get communication logs. I recommend that you tick all the logging checkboxes first, so you get detailed information about what happens to a message. If you receive a text, you will see it appear in the log before it is forwarded to your C# sms client. (Figure 10)

Enable logging to see received sms before it gets to the C# sms client
Figure 10 - Enable logging to see received sms before it gets to the C# sms client

Step 6 - Add new route to simulate incoming SMS

Create a new SMS route to allow the admin user to send test SMS message to the C# sms api client. One of the best things about using Ozeki SMS Gateway is that it allows you to manage your SMS messages with a routing table. You can setup various mobile network connections and you can decide which sms will go where. In our example we want to route sms messages coming from the admin account to the C# sms api client. In a real life system you will not route sms from the admin account, instead you will route sms messages received on mobile network connections to your C# sms api client.

To create a new sms route, click on Add new route in the Ozeki SMS Gateway dashboard (Figure 11).

Add new sms route for the C# sms client
Figure 11 - Add new sms route

To receive a text while you write your c# sms code, you will use the SMS gateway's compose form, and you will send the SMS in as the admin user. The sms route you we are going to create will route the sms messages coming from admin to the testuser account. The testuser account will forward the sms to the C# sms client (Figure 12).

sms from gui to c#
Figure 12 - SMS from admin to c# client

Select testuser as the destination for your incoming sms messages in the routing details form. This route will send sms messages from the admin user to the testuser. The testuser will forward the received sms messages to the C# api client (Figure 13).

Create sms route for simulating incoming texts
Figure 13 - Create sms route for simulating incoming texts

Step 7 - Start the C# sms example project

To start your C# sms project, you need to click on the Start button in the Visual Studio toolbar. After you click this button, Visual Studio will compile the code, and will run it in the development environment. Program execution will be stopped when the algorithm hits a break point. Since our example is a console application you will see the black console window appear once the execution is started. (Figure 14)

Figure 14 - Start the C# sms api project

Type in help in the console window. The help text will list the available commands available for you in this example project. The first command you will use is the connect command. Type in "connect 127.0.0.1:9580 testuser testpass" into the console window to connect your C# sms code to the SMS Gateway. Note that 127.0.0.1 means that the SMS gateway is running on the same PC where your C# sms code is running. 9580 is the TCP/IP port used by the SMS gateway to accept C# sms clients (OZX users), and the testuser and testpass credentials are the ones we have defined when we have created the OZX user account in step 6 of this sms tutorial. (Figure 15)

Figure 15 - Launch the C# sms console app

Once you have connected to the SMS gateway you are ready to send your first SMS to your C# api client.

Step 8 - Send a test sms

Send a test SMS message by clicking on the "New" toolbar button in the Ozeki toolbar in the SMS Gateway management console. When you send your test sms, you will have to define a recipient address and the messages text. In the Advanced tab page you may also define a sender ID, such as an SMS short code or an alphanumeric server ID for your SMS. (Figure 16)

test sms about to be received
Figure 16 - Compose the test sms about to be received

Click OK to submit the test sms. Your sms gateway will provide you with the events related to SMS submission, and you will be presented with a Message ID. You may notice the GUID string in the last line of Figure 17.

SMS message ID to be used in the C# sms api
Figure 17 - SMS message ID to be used in the C# sms api

After the sms is sent by the admin user, it is received by the OZX user account called testuser. This user account forward the SMS to the C# sms client over the network. The C# sms client receives the text over the TCP/IP link established by the connect method. If you have set the break point in the OnMessageReceived event, this is when your breakpoint will pause program execution.

Step 9 - Receive SMS in the C# console

Read the message received line in the C# console. You will see that the SMS was sent by admin@localhost to the phone number +361111111. The C# sms api client received the text 'Hello c sharp client' (Figure 18). The text message was presented to the C# client in the form of a C# event. The OnMessageReceived event handler is called when this event is raised, and the messages was put into the OzMessageReceived event handler method's input parameter.

receive sms in C# console
Figure 18 - receive sms in C# console

The next thing you want to do is take a look at the log in the SMS gateway.

Step 10 - View the logs in the SMS Gateway

Open the details page of the testuser by clicking on the testuser link in the Ozeki SMS Gateway dashboard. This will take us to the event log of the testuser account. In this event log we expect to see the communication that takes place between the C# sms client and the SMS Gateway. We also expect to see the received sms message in the communication log. (Figure 19)

Figure 19 - Open the testuser details page

Locate the "Received." line in the testuser events tab. You will see the sms received by the C# sms client in this line. You can see the date and time of the event, and you can see the message details. Below the human readable log entry, you will see the OZX protocol communication log. This log allows your to debug the communication in case any problem comes up. (Figure 20)

Figure 20 - check the incoming sms in the user account associated with the C# sms api

Receive a text message from the mobile network

In the steps above we have simulated an incoming message. The admin user sent a message that was forwarded to the C# sms example. The next step is to connect the system to the mobile network. For this you have various options. You can connect to an Internet based SMS service provider using an SMPP client connection, or you can install ozeki 10 sms gateway on your Android phone and use the built in sms connection of the android sms gateway. (Figure 21)

Figure 21 - Receive sms with an Android phone

To make the above solution work with an Android phone, all you have to do is create an inbound route in the Ozeki SMS Routing table. You need to create this route between the mobile network connection and the C# sms api user (testuser). To find the best mobile network connection method for your project consult our how to connect your sms gateway to the mobile network guide. (Figure 22)

Figure 22 - Receive sms routing table

To sum it up

This was a long and very detailed instruction list to help you get started with developing a C# SMS project, that can receive SMS messages. If you start to use this solution, you will find out quickly that this solution is very good if you wish to receive sms messages promptly over various mobile network connections. This solution works whether you want to receive SMS over an Android Mobile phone or through an IP SMS link, such as an SMPP client connection.

More information