Sending SMS Messages via Long Codes

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

All IntelePeer Long 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/v1/{tn}/send

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

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

https://api.intelepeer.com/sms/v1/+17203378652 /send

 

Parameters

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

ParameterData TypeRequired
tostringrequiredE.164-formatted number to which the message is being sent to (e.g., +13038675309)
textstringrequiredThe message to be sent
guidstringoptionalAn identifier to be appended to the message in the Message Detail Record for correlation with other system records.

 

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

Response Codes
Response CodeDescription
202SMS message has been successfully queued for delivery to the destination phone number.
400One 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
401One 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
403The international destination is not available
404The 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 the mobile carrier
  3. Message delivered to end-customer

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

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

There may be message delivery failures due to carrier SPAM filters or the carrier-specific restrictions.

Example Code

C#

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
            }
        }
    }
}

 

Java

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<NameValuePair> urlParameters = new ArrayList<NameValuePair>();
		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());
    }
}

 

Node.js

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);
});

 

PHP

<?php

require '../../vendor/autoload.php';
use GuzzleHttpClient;

###############################################################################
### update these accordingly                                                ###
###############################################################################
$authtoken = 'INSERT_AUTH_TOKEN_HERE';
$tn = 'INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT';
$dest_tn = 'INSERT_RECEIVING_TELEPHONENUMBER_HERE_IN_E.164_FORMAT';
$message = 'the time is now: '. date("Y-m-d H:i:s");

###############################################################################
### leave these alone                                                       ###
###############################################################################
$url  = "https://api.intelepeer.com/sms/v1/$tn/send";
$hdrs = ['Content-Type' => "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();
?>

 

Python

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 )