We understand how important SMS communication is in our industry. We have two implementations to choose from to allow you complete control of how you can use SMS in your organization.
-
- SMS using your VoiceElements Client – click here to navigate to this article
- SMS via REST APIs – continue reading
SMS via REST API
Using our REST API will allow you to quickly create an ASP.NET Application/Controller in your environment to send and receive SMS messages.
Documentation
For complete documentation, refer to our SMS REST API Reference Guide.
Get a Security Key and Set Your Webhook URL
Log into your account on our portal https://customer.voiceelements.com/ and navigate to API Keys under Settings. Click on the REST API tab.
Here you can get your token and set the URL for your webhook.
Outbound SMS
Messages are sent to our servers by way of REST calls. For example to send an SMS message, POST to https://ivlrest.voiceelements.com/v1/SendSMS passing in the BODY the following JSON:
{
"toNumber": "3035551212",
"fromNumber": "6025551212",
"text": "Your text here",
"customerTag": ""
}
Inbound SMS
Upon receiving an inbound text on your account, we will POST to your specified Webhook URL the following JSON:
{
"toNumber": "7205757673",
"fromNumber": "7202731927",
"text": "Your text here.",
"messageDateTime": "2018-09-06T21:37:32",
"messageId": "666313",
"lastMessageId": "666312"
}
MMS Via REST API
Outbound MMS
Sending MMS is similar to sending SMS; however, there is an additional parameter in the JSON when you send an MMS message. The URL(s) passed in the body must be publicly accessible from the internet, or if you wish the image to be secure, you can alternatively upload the media to our servers prior to posting the MMS message. For more information, see our SMS REST API Reference Guide and the code example in the Outbound MMS Images section below.
For example, to send an MMS message, POST to https://ivlrest.voiceelements.com/v1/SendSMS passing in the BODY the following JSON:
{
"toNumber": "3035551212",
"fromNumber": "6025551212",
"text": "Your text here",
"customerTag": "",
"media": ["https://s3.amazonaws.com/bw-v2-api/demo.jpg" ]
}
Inbound MMS
Upon receiving an inbound MMS message on your account, we will POST to your specified Webhook URL the following JSON:
{
"toNumber": "7205757673",
"fromNumber": "7202731927",
"text": "Your text here.",
"messageDateTime": "2018-09-06T21:37:32",
"messageId": "666313",
"lastMessageId": "666312",
"media":["https://s3.amazonaws.com/bw-v2-api/demo.jpg"]
}
Note, you can see that the media is passed as an array of URLs. It is your responsibility to retrieve the media. This can be done by following the example below in the section Inbound MMS Messages.
Outbound MMS Images Example Code
If the media you are sending is publicly accessible, you do not need to send the images to our server.
However, if you wish to use our secure image processing, note that you must upload the media to our servers prior to posting the MMS message. Here is an example:
public string PutImage(byte[] image, string fileName)
{
string retString = "";
string baseAddress = "https://ivlrest.voiceelements.com";
try
{
string query = $"/v1/media/{fileName}";
retString = baseAddress + query;
log.Write("{0}{1}", baseAddress, query);
log.Write("Byte array size: {0}", image.Length);
HttpClient client = new HttpClient();
string uri = baseAddress;
client.BaseAddress = new Uri(uri);
client.DefaultRequestHeaders.Add("Token", ivlToken);
HttpContent content = new ByteArrayContent(image);
content.Headers.ContentLength = image.Length;
HttpResponseMessage response = client.PutAsync(query, content).Result;
log.Write("Back from Call: {0} {1}", (int)response.StatusCode, response.ReasonPhrase);
if (response.IsSuccessStatusCode)
{
string json = response.Content.ReadAsStringAsync().Result;
log.Write("Back from fetching json");
if (json.Length > 0)
{
OutJsonBasic ojb = Newtonsoft.Json.JsonConvert.DeserializeObject<OutJsonBasic>(json);
log.Write($"Status:{ojb.status} {ojb.reason}");
}
return retString;
}
return "";
}
catch (Exception ex)
{
log.WriteException(ex, "PutImage");
return "";
}
}
Inbound MMS Images Example Code
MMS messages are passed by links that are sent when receiving an MMS message as described in the section above. The following code demonstrates how you can receive an image that was sent to your SMS enabled phone number using our REST API.
public byte[] GetImage(string url, ref string error)
{
error = "";
try
{
log.Write("Get Image:{0}.", url);
Uri uriAddress = new Uri(url);
string baseAddress = uriAddress.GetLeftPart(UriPartial.Authority);
log.Write("BaseAddress {0}", baseAddress);
string query = uriAddress.AbsolutePath;
log.Write("Query {0}", query);
HttpClient client = new HttpClient();
string uri = baseAddress;
client.BaseAddress = new Uri(uri);
client.DefaultRequestHeaders.Add("Token", ivlToken);
HttpResponseMessage response = client.GetAsync(query).Result;
log.Write("Back from Call: {0} {1}", (int)response.StatusCode, response.ReasonPhrase);
if (response.IsSuccessStatusCode)
{
byte[] image = response.Content.ReadAsByteArrayAsync().Result;
log.Write("Back from fetching image - Returned {0} bytes";, image.Length);
return image;
}
else
{
string jsonString = response.Content.ReadAsStringAsync().Result;
log.Write(jsonString);
OutJsonBasic ojb=Newtonsoft.Json.JsonConvert.DeserializeObject<OutJsonBasic>(jsonString);
string s = $"Status:{ojb.status} {ojb.reason}";
log.Write(s);
error = s;
return null;
}
}
catch (Exception ex)
{
log.WriteException(ex, "Error: Error making call to get image");
error = "Catch. Error: Error making call to get image";
}
return null;
}
If you would like to learn more about SMS using your VoiceElements Client, please see our article Voice Elements SMS.
Please contact us if you have any questions!
We invite you to schedule a free consultation with our Tech Team to explore your project goals and how we can help you get quickly into production.