How to use the SMS API Platform

How To Get Your First SMS App Up and Running

We have two implementations to allow you complete control of how you can use SMS in your organization.

Click the link to skip right to the section you’re interested in:

• SMS using the Voice Elements Client
• SMS via REST API’s

SMS using the Voice Elements Client

Sending and receiving SMS from within Voice Elements is a snap. It requires version 8.6.3 of the VoiceElements Client. You can find our Voice Elements Package on NUGET here: InventiveLabs.VoiceElementsClient

Set Encryption Keys

Before you can use SMS, you must set the encryption keys.

These keys are unique to your account and you can get the keys for your SMS enabled number(s) when you log into your account on our Voice Elements Customer Portal.

Setting the keys in code is done at startup:

s_telephonyServer.SmsMyPrivateKeyXml = AppSettings.CustomerKeyPairXml;
s_telephonyServer.SmsBorderElementsPublicKeyXml = AppSettings.BorderKeyPairXml;

You should also subscribe to the SMS events to receive SMS messages and delivery reports:

s_telephonyServer.SmsMessage += TelephonyServer_SmsMessage;
s_telephonyServer.SmsDeliveryReport += TelephonyServer_SmsDeliveryReport;

Outgoing SMS

After these are set, you can easily send an SMS message as in this example:

public static void SendSms(string number, string smsText)
{
     try
     {
          Guid messageGuid;
          string[] headers;
          string[] sdp;

          var sipStatusCode = s_telephonyServer.SmsSendMessage(smsText, number, fromNumber, null, out messageGuid, out headers, out sdp);
          Log.Write("SMS Result: {0}", sipStatusCode);
     }
     catch (Exception ex)
     {
          Log.WriteException(ex, "SendSms()");
     }
}

Incoming SMS

And then handle incoming SMS messages upon arrival:

private static void TelephonyServer_SmsMessage(object sender, SmsMessageEventArgs e)
{
     Log.Write($"Received SMS (From: {e.SmsFrom}, To: {e.SmsTo}): {e.SmsMessage}");
}

Delivery Reports

The system will also give you delivery reports for sent SMS messages:

private static void TelephonyServer_SmsDeliveryReport(object sender, SmsDeliveryReportEventArgs e)
{
     if (string.IsNullOrWhiteSpace(e.DeliveryDescription) && e.DeliveryState.ToLower() == "waiting")
     {
          Log.Write($"Received SMS Delivery Report (From: {e.SmsFrom}, To: {e.SmsTo}): Message delivery is pending...");
     }
     else
     {
          Log.Write($"Received SMS Delivery Report (From: {e.SmsFrom}, To: {e.SmsTo}): {e.DeliveryDescription}");
     }
}

Handling Undeliverable Messages

You can also request that any undelivered SMS messages be sent to you. These would be messages that may have arrived while your application was offline.

try
{
     string[] headers;
     string[] sdp;

     var result = s_telephonyServer.SmsRequestUndeliveredMessages(out headers, out sdp);
     Log.Write($"Requesting undelivered SMS messages.  Result: {result}");
}
catch { }

SMS Via REST APIs

Get a Security Key

Using our REST APIs for SMS is done by first getting a security key by logging into your account on our Voice Elements Customer Portal.

Outgoing SMS

Messages are then sent to our servers by way of REST calls to our server.

For example to send a message:

POST https://ivlrest.voiceelements.com/v1/SendSMS
HTTP HEADER: token:   [your token here]

JSON Post Data

{
     "toNumber": "3035551212",
     "fromNumber": "6025551212",
     "text": "Your text here",
     "customerTag": ""
}

Receiving SMS

For receiving SMS messages, we will POST back JSON to your server in a similar fashion.

Documentation

For complete documentation, refer to our SMS REST API Reference Guide.