GET STARTED
Log In

Sending SMS Messages

 

The Atmosphere® Messaging API makes it simple to send and receive SMS messages through your IntelePeer Long Codes (DID and Toll-free phone numbers), and Short Codes.

All IntelePeer Long Codes and Short Codes can be used to send and receive SMS messages. Visit Provisioning Telephone Numbers for SMS to learn more about enabling your numbers to send and receive SMS applications.

Sending a single SMS Message

You can send an SMS message with a single call to the Atmosphere® Messaging API.

URI

POST to https://api.intelepeer.com/sms/v3/{tn}/send

{tn} is the phone number, in E.164 format, from which the text is to be sent.

For US Short Codes {tn} is the Short Code, in 1-Short Code format, from which the text is to be sent.

 

For example, you would send an SMS message from the North American phone number +17208675309 by POSTing to the URL

https://api.intelepeer.com/sms/v3/+17208675309/send

For example, you would send an SMS message from a US Short Code 12345 by POSTing to the URL

https://api.intelepeer.com/sms/v3/1-12345/send

 

 

Parameters

This API method requires an Authorization Token. Learn more about the Authorization token in Atmosphere® API Authentication.

Parameter Data Type Required
from string required E.164-formatted or shortcode-formatted number to which the message is being sent (e.g., +13038675309, 1-12345)
to string required E.164-formatted number to which the message is being sent (e.g., +13038675309)
text string required The message to be sent
guid string optional An identifier to be appended to the message in the Message Detail Record for correlation with other system records.

 

Long Code Request Example
{
    "from": "+17203378652",
    "to": "+13038675309",
    "text": "Hello World!",
    "guid": "1123123123123123"
}

Short Code Request Example
{
"from": "1-12345",
"to": "+13038675309",
"text": "Hello World!",
"guid": "1123123123123123"
}

 

Response Codes
Response Code Description
202 SMS message has been successfully queued for delivery to the destination phone number.
400 One of the following errors occurred:

  • The telephone number is not the proper E.164 format
  • The telephone number has not been enabled for SMS
  • to/text fields are not present in the request
401 One of the following errors occurred:

  • Authorization token has expired
  • The user does not own telephone number
  • Enterprise is not currently enabled for SMS API access
403 The international destination is not available
404 The telephone number is not available for use by the customer

 

Response Example
{
    "state": "CREATED",
    "refid": "SM5AC09A610001006568100005C32E9D"
}

 

Behavior

Messages sent through the Atmosphere® Messaging API are queued for quick and reliable delivery to the destination carrier and ultimately to the end-user’s phone.

You can check the status of a message at any time after sending it. Learn more about Checking Message Status.

The message’s lifecycle is as follows:

  1. Message queued for delivery
  2. Message delivered to mobile the carrier
  3. Message delivered to end-customer
  4. In some cases, message delivery may fail due to carrier SPAM filters or other carrier-specific restrictions

There may be delays in delivery a message to the end-customer due to:

  • Throttling enforced by IntelePeer to improve message delivery
  • Throttling or SPAM controls enforced by the mobile carrier
  • The end customers handset being out of service area, turned off, or in airplane mode

 

Example Code

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace IntelePeerSMSExampleClient.sendSMS
{
    class SendSMS
    {
        public void run()
        {
            //Authorization Token from IntelePeer Customer Portal
            string TN = "INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT";
            string url = "https://api.intelepeer.com/sms/v1/" + TN + "/send";
            string AUTH_TOKEN = "INSERT_AUTH_TOKEN_HERE";
            string DEST_TN = "INSERT_RECEIVING_TELEPHONENUMBER_HERE_IN_E.164_FORMAT";
            string MESSAGE = "the time is now:" + DateTime.Now.ToShortTimeString();

            System.Net.WebRequest httpWebRequest = System.Net.WebRequest.Create(url);
            httpWebRequest.Method = "POST";

            //Add Header
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + AUTH_TOKEN);

            //Data to be posted
            string json = new System.Web.Script.Serialization.JavaScriptSerializer().Serialize(
                    new
                    {
                        to = DEST_TN,
                        text = MESSAGE
                    }
                );

            //Add data to post
            using (System.IO.StreamWriter streamWriter = new System.IO.StreamWriter(httpWebRequest.GetRequestStream()))
            {
                streamWriter.Write(json);
                streamWriter.Flush();
                streamWriter.Close();
            }

            try
            {
                //Submit Request and Read Response
                System.Net.WebResponse httpResponse = httpWebRequest.GetResponse();

                using (System.IO.StreamReader streamReader = new System.IO.StreamReader(httpResponse.GetResponseStream()))
                {
                    string result = streamReader.ReadToEnd();

                    System.Console.Write(result);
                }

            }
            catch (System.Net.WebException webException)
            {
                string response = webException.Message;
            }
            catch (Exception exception)
            {
                string response = exception.Message;
            }
            finally
            {
                //do something else
            }
        }
    }
}

 

package main.java.tnActions.sendSms;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.util.ArrayList;
import java.util.Calendar;
import java.util.List;

import org.apache.http.HttpHeaders;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.message.BasicNameValuePair;

public class SendSms {
	public static void main(String... args) throws Exception {
		final String TN = "INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT";
		final String url = "https://api.intelepeer.com/sms/v1/" + TN + "/send";
		final String AUTH_TOKEN = "INSERT_AUTH_TOKEN_HERE";
		
		final String DEST_TN = "INSERT_RECEIVING_TELEPHONENUMBER_HERE_IN_E.164_FORMAT";
		final String MESSAGE = "the time is now: " + Calendar.getInstance().getTime();
		
		
		HttpClient httpclient = HttpClientBuilder.create().build();
		HttpPost httpPost = new HttpPost(url);
        
		// add header
		httpPost.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
		httpPost.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + AUTH_TOKEN);
        
		// Data to be posted
		List urlParameters = new ArrayList();
		urlParameters.add(new BasicNameValuePair("to", DEST_TN));
		urlParameters.add(new BasicNameValuePair("text", MESSAGE));
    	
		// add data to post
		httpPost.setEntity(new UrlEncodedFormEntity(urlParameters));
        
		// execute GET
		HttpResponse response = httpclient.execute(httpPost);
        
		System.out.println("nSending 'POST' request to URL : " + url);
		System.out.println("Response Code : " + 
                       response.getStatusLine().getStatusCode());

		BufferedReader rd = new BufferedReader(
                       new InputStreamReader(response.getEntity().getContent()));

		StringBuffer result = new StringBuffer();
		String line = "";
		while ((line = rd.readLine()) != null) {
			result.append(line);
		}

		System.out.println(result.toString());
    }
}

 

const request = require("request");

///////////////////////////////////////////////////////////////////////////////
/// update these accordingly                                                ///
///////////////////////////////////////////////////////////////////////////////
let authtoken = 'INSERT_AUTH_TOKEN_HERE'
let tn        = 'INSERT_SENDING_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
let dest_tn   = 'INSERT_RECEIVING_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
let message   = 'the time is now: {}'.format(datetime.now())

///////////////////////////////////////////////////////////////////////////////
/// leave these alone                                                       ///
///////////////////////////////////////////////////////////////////////////////
let url       = "https://api.intelepeer.com/sms/v1/" + tn +"/send"
let payload   = { 'to': dest_tn, 'text': message }
let hdrs      = {
    'Content-Type': "application/json",
    'Authorization': "Bearer " + authtoken
    }

///////////////////////////////////////////////////////////////////////////////
/// execute the task and parse results                                      ///
///////////////////////////////////////////////////////////////////////////////
request.post({
    url: url,
    headers: hdrs,
    form: payload
},
(error, response, body) => {        
    result = JSON.parse(body);
    console.log(result.text);
});

 

 "application/json",
         'Authorization' => 'Bearer '.$authtoken
];
$payload = [ 'to' => $dest_tn, 'text' => $message ];

###############################################################################
### execute the task and parse results                                      ###
###############################################################################

try{
  $client = new Client();
  $response = $client->post($url, [
    'headers' => $hdrs,
    'json' => $payload
    ]);
}
catch (RequestException $e){
  echo "Request Failed:". $e->getMessage();
}

echo $response->getBody();
?>

 

import requests
from datetime import datetime

###############################################################################
### update these accordingly                                                ###
###############################################################################
authtoken = 'INSERT_AUTH_TOKEN_HERE'
tn        = 'INSERT_SENDING_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
dest_tn   = 'INSERT_RECEIVING_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
message   = 'the time is now: {}'.format(datetime.now())

###############################################################################
### leave these alone                                                       ###
###############################################################################
url       = "https://api.intelepeer.com/sms/v1/{}/send".format(tn)
payload   = { 'to': dest_tn, 'text': message }
hdrs      = {
    'Content-Type': "application/json",
    'Authorization': 'Bearer {}'.format(authtoken)
    }

###############################################################################
### execute the task and parse results                                      ###
###############################################################################
response = requests.post(url, json=payload, headers=hdrs)
print u'{}: {}'.format('OK' if response else 'ERROR', response.text )

 

Sending SMS Messages in bulk

 

The same API above can also be used to send messages in bulk. The following describes the differences between the single-API and the bulk-API:

 

Changes to the request for bulk API:

The single-send API requires a single object which contains the message parameters. To use the bulk-send API, simply turn your JSON into a list of these objects:

 Example
[

{

"to": "+13038675309",

"text": "Hello World test 1",

"guid": "1123123123123123"

},

{

"to": "+13038675309",

"text": "Hello World test 2",

"guid": "1123123123123123"

}

]

 

Changes to the response for bulk API:

The single-send API responds with a reference identifier (refid) as well as status information about the request. The bulk-send API returns a list of these responses in the object-key, “responses”, where each response corresponds to the associated request.

The bulk HTTP response code will generally be 202 regardless of the status of individual messages, unless an error occurs at the overall request level.

 Example
{

"code": 202,

"responses": [

{

"state": "Queued",

"code": 202,

"refid": "SM5BE9B76600099999991000DE162EE8"

},

{

"state": "Queued",

"code": 202,

"refid": "SM5BE9B766000999999910008CF7795C"

}

]

}

 

 

 

Cart Overview