SMS/MMS

Table of Contents

Overview

The ability to send and receive SMS and MMS messages. Your DID to a cell phone and vice versa. All just a web call away.

Restrictions

SMS is intended for enhancing person to person communication. You may not send more than 1 message per second per phone number and no more than 3,000 messages per day per number. You are also not to spam the same message to multiple people.

Sending spam or many automated messages will result in immediate SMS suspension.

Controller: /sms or /mms
Full Url: https://sms.teleapi.net/sms/ NOTE: The URL here is different than a lot of the rest of the API

Functions

/sms/send

Full Url: https://sms.teleapi.net/sms/send

Arguments:

Info: source must be a number from your inventory. Basically, you're saying "Send an SMS from this number to that (10 digit) number. Here's the message".

/mms/send

Full Url: https://sms.teleapi.net/mms/send

Arguments:

Info: source must be a number from your inventory. file_data needs to be a base 64 encoded string of your file's contents. Alternatively, if you already have a URL for the image you can simply send us that url in file_url. We'll grab it and do the rest for you. Ultimately, though, we need file_name and file_data OR file_url. Your choice.

Example PHP MMS message

Update: There is also a PHP client library available at https://github.com/teleapi/php-client

$source = "3035551212";
$destination = "3039991111";
$token = "32hfrehfehrfh34f";
$file_name = "catpicture.png"; //you know someone's going to do it..
$file_data = file_get_contents('/path/to/file/' . $file_name);
$file_data = base64_encode($file_data);

$baseurl = "https://sms.teleapi.net/mms/send";
$data = array(
    'token' => $token,
    'source' => $source,
    'destination' => $destination,
    'file_name' => $file_name,
    'file_data' => $file_data
);
$data = http_build_query($data);

$ch = curl_init($baseurl);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/x-www-form-urlencoded',
    'Content-Length: ' . strlen($data)
));
$response = curl_exec($ch);
curl_close($ch);
$response = json_decode($response);
if ($response->code == 200) {
    //success
} else {
    //fail
    print_r($response);
}

Receiving SMS/MMS

In order to receive SMS or MMS messages we need somewhere to send them. In your "My Settings" page in the user portal, there is a settings for "Incoming SMS Post URL". All messages that come to any of your phone numbers will get sent to this URL via HTTP POST. So, all you need is a script that will consume these web calls and do something with it.

Example HTTP POST
//SMS
source=3035551212
destination=3039991111
message=Hello, World!
type=sms

//MMS
source=3035551212
destination=3039991111
message=http://picmsg.org/[unique identifier]
type=mms
PHP example

Update: There is also a PHP client library available at https://github.com/teleapi/php-client

$source = $_POST['source'];
$destination = $_POST['destination'];
$message = $_POST['message'];

//save to a csv file... if you're into that sort of thing
$csv_line = sprintf('%s,%s,%s', $source, $destination, $message);
file_put_contents('/path/to/awful_csv_log.csv', $csv_line);

//make it show up in apache's error log
error_log(print_r($_POST, true));

//I've gone to Cancun and "acccidentally" left my phone at home
$ch = curl_init('https://sms.teleapi.net/sms/send');
$data = array(
    'token' => $my_api_token,
    'source' => $destination,
    'destination' => $source,
    'message' => 'Hello. I am unavailable right now. Please leave a brief message and I will get back to you when I'm sober.'
);
$data = http_build_query($data);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/x-www-form-urlencoded',
    'Content-Length: ' . strlen($data)
));
$resp = curl_exec($ch);
curl_close($ch);
$resp = json_decode($resp);
if ($resp->code == 200) {
    //the boss is mad
} else {
    //the boss is still mad. but he didn't get a snarky message
}

Delivery Notifications

Delivery Notifications are only supported via our API and SMPP connections. We don't support delivery notifications via Jabber/XMPP or Slack.

Let me preface this by saying delivery notifications are not always a sure thing. In order for delivery notifications to work every hop along the way, from here to the end number, has to send them. Sometimes they don't. Also, sometimes you won't get a delivery notification for quite a while. It all depends on many variables from here to there. That said, they can be very nice in letting you know how successful your SMS message was. They are also asynchronous. This means that sending the message is a separate process from knowing if the message is delivered or not, which is why this is a separate web call to look for.

Breakdown of the delivery notification process:

  1. You give us a message to send to some end number
  2. The API call that you made to us to send the SMS message ends, in the response is an ID that we will refer to when we deliver the notification
  3. We pass that message along to carriers
  4. Carriers may pass to other carriers
  5. Message gets delivered to device, or is rejected, fails, etc
  6. A notification is passed back down the chain of carriers, one by one, with the status of the message
  7. The notification finally makes it back to us
  8. We grab your SMS Delivery Notification URL and, finally, pass that notification on to you via HTTP POST using the ID we gave you as a reference point

To receive delivery notifications via HTTP POST, simply set an SMS Delivery Notification URL in your My Accounts page in the user portal. Once set, you will receive notifications for all messages sent.
To receive delivery notifications via SMPP, send a registered_delivery value of 1 in your submit_sm command to send the message.

The POST that you get to your server will look something like:

{
  url: 'http://yoursite.com/sms/notifications',
  id: '72b83667-a8f1-4c09-861f-e1ee6dd4561b',
  send_status: 'delivered',
  status: 'DELIVRD',
  error: '000'
}

Possible send_status:

Possible error code / status:

Since all DLR information is relayed from upstream providers and differences in carrier specific response types exist in an unregulated industry, error codes will by varied. Instead of using this information, we suggest looking at the status to determine the cause of an error or send_status for high level checking.