How to send and receive SIP Instant Messages
 |
Download: | instant-messages.zip |
This guide demonstrates how to send and receive SIP instant messages using Ozeki VoIP SIP SDK in C#. It builds upon the previous SIP Registration example to create a softphone capable of real-time text-based messaging without establishing a voice call. The implementation uses two classes (Program.cs and Softphone.cs) to separate the user interface from the softphone logic, allowing peer-to-peer communication between VoIP clients.
Why do we need SIP instant messaging?
Sometimes two parties need to exchange a short piece of information, like a status update or a quick note, and placing a full voice call is slower and more disruptive than the message itself deserves. Setting up an audio call also means creating a call object, attaching a microphone and speaker, and connecting media handlers, which is a lot of overhead for something as simple as sending text. SIP instant messaging solves this by letting a softphone send text directly to another SIP client without ever establishing a call or touching any audio device.
What is instant messaging?
Instant messaging is real-time, text-based communication sent directly between two parties without establishing a voice call. In this example, the softphone sends and receives SIP instant messages peer-to-peer between VoIP clients, using the phone line's own messaging support rather than any call, microphone, or speaker object.
How does it work?
The softphone registers a phone line with a PBX exactly as in the SIP Registration example, then subscribes to that phone line's MessageReceived event. To send a message, the application builds an InstantMessage with the recipient's number and text content, and passes it to the phone line's SendMessage method, which delivers it directly to the recipient without opening a call. Incoming messages arrive the same way, firing an event that the application displays to the console.
Introduction
Instant messaging (IM) is a form of real-time direct text-based chatting communication in push mode between two or more people using personal computers or other devices, along with shared clients. The user's text is conveyed over a network, such as the Internet. More advanced instant messaging software clients also allow enhanced modes of communication, such as live voice or video calling and inclusion of links to media.
Session Initiation Protocol (SIP) is used for establishing a phone line between two VoIP clients using a PBX. In case of an instant messaging system the PBX is not needed, the clients can communicate peer to peer.
Ozeki VoIP SIP SDK has the support for SIP instant messaging between VoIP clients as the following example will show you.
The support for instant message sending can be used by calling some provided methods of Ozeki VoIP SIP SDK. The message should be typed in and the sending method should be called.
The following program code uses the background support of Ozeki VoIP SIP SDK, therefore you will need to download and install the SDK on your computer before starting to use the program code. You will also need to have Visual Studio 2010 (or higher) or compatible IDE and .NET Framework installed on your system, as the program code below is written in C# language.
How to build and run your solution
Download the project, extract the archive, and open the solution in Visual Studio. Build the solution and run the compiled console application to start the softphone, which prompts for SIP account details.
How to test the solution
Enter your SIP account details and wait for registration to succeed, then enter the recipient's phone number when prompted. Type a message and press Enter to send it, and confirm it arrives on the recipient's side; if the other softphone sends a message back, confirm it appears on the console without either side ever placing a call.
Key source code
The core of this example is how instant messaging attaches directly to the phone
line rather than to a call. During registration, the softphone subscribes to the
phone line's InstantMessaging.MessageReceived event right alongside its
RegistrationStateChanged event, and SendMessage() hands an
outgoing message to that same InstantMessaging object. No
IPhoneCall, microphone, or speaker is involved at any point.
What is Softphone.cs used for?
This class is used to introduce how to declare, define and initialize a softphone, how to handle some of the Ozeki VoIP SIP SDK's events and how to use some of that's functions. In other words, we would like to create a "telephone software", which has the same functions (or much more), as an ordinary mobile (or any other) phone. In the Program.cs class we will use this class to create a new softphone, so we can use the functions, we can listen to the events placed here.
Objects and variables
This application's Softphone class needs only two objects and one variable:
private ISoftPhone softphone; // softphone object private IPhoneLine phoneLine; // phoneline object public string recipient; // the recipient's number as string
As you can see, this class is using a ISoftPhone and an IPhoneLine object. You can initialize them,
as you did in the first example.
There are two possible ways to send instant messages to an other party:
- through the IPhoneLine object, with the object's SendOutofDialogInstantMessage() method. In this case, you don't need to establish a call with the other party. This example introduces this case.
- through the IPhoneCall object, with the SendInstantMessage() method. In this case, you have to establish a call before you try to send an instant message.
This example doesn't need any IPhoneCall or Microphone, Speaker, MediaConnector etc. MediaHandler objects, since it sends messages without establishing a call and doesn't need the devices, which an audio call would.
How to send Instant Messages?
To send an instant message, you need to set the IPhoneLine's object's (called phoneLine in this example) with an InstantMessage parameter:
- message: an InstantMessage object
public void SendMessage(InstantMessage message)
{
phoneLine.InstantMessaging.SendMessage(message);
}
This method will receive the message string's value from the user, and will send the given message to the recipient, defined by the recipient variable.
How to receive Instant Messages?
To receive instant messages through the phoneLine object, the application needs to be subscribed to the MessageReceived event of the phoneLine:
phoneLine.InstantMessaging.MessageReceived += phoneLine_InstantMessageReceived;
The phoneLine_InstantMessageReceived method notifies the application if there is an incoming instant message through an event, called IncomingMessage in this example.
Please note that, if you are editing the source code of the first example, called "SIP Registration", since there is no IPhoneCall object being used in this example, you can remove that and all of its dependencies from the source code (for example the handling of the call's states).
What is Program.cs used for?
This class will introduce the usage of a softphone object, handles the console events, interacts with the user, and uses the opportunities provided by the Softphone class. In this example, the softphone can send and receive Instant Messages. We are handling everything with separated methods; these methods are communicating with each other, and making the source code more understandable and reusable.
What objects and variables are being used?
There is only one new variable: messageToSend, to store the message which is being sent, as String:
static InstantMessage messageToSend;
How to initialize the softphone?
The first step is to initialize the softphone, we have created. To do this, we need to call an initializer method. We also need to subscribe to the softphone's events. If you are using the SIP Registration example's source code, to do this, you need to add the following line:
mySoftphone.IncomingMessage += mySoftphone_IncomingMessage;
As you can see, the application is subscribing to the IncomingMessage event of the Softphone class, and is setting the declared variable to be empty.
How to get the phone number of the recipient?
The application is using a method, called GetRecipient() for the purpose to ask the user about the recipient's number, and to store that in the previously declared recipient variable of the Softphone object, called mySoftphone in this example. This method is being called when the registration was successful (or no registration was needed).
How to get message from the user to be sent?
There is a method, called MessageToSend in this example, which is asking the user for messages to be sent, and sends those to the recipient, until the user closes the application. This method is using the mySoftphone object's SendMessage() method (see above), with the user's message as parameter:
var content = GetMessage(); messageToSend = new InstantMessage(mySoftphone.recipient, content); mySoftphone.SendMessage(messageToSend);
The MessageToSend() method is being called after the setting of the recipient's number.
How to receive incoming instant messages?
To receive an instant message, the softphone is already subscribed to the necessary event (see above), which calls the mySoftphone_IncomingMessage() method, which displays the received message's originator and the message itself:
Console.WriteLine("\nMessage received from {0}: {1}", instantMessage.Sender, instantMessage.Content);
Conclusion
After reading this article, you must be familiar with instant message sending and receiving without making a call.
If you have any questions or need assistance, please contact us at info@voip-sip-sdk.com
You can select a suitable Ozeki VoIP SIP SDK license for your project on Pricing and licensing information page