sms

Summit SMS Library

This library will allow you to send text messages from a Summit application.

I can send SMS messages! Let me tell you how!

Basic Use

The following will send an SMS message to 555-888-7777 from 555-222-3333.

sms = require "summit.sms"

to = "+15558887777"
from = "+15552223333"
message = "hello!"

ok, err = sms.send(to, from, message)

Multiple Recipients / Multiple Messages

The parameters to and message may be arrays. In that case, all messages will be sent to all numbers in the to array. eg:

ok, err = sms.send({"+15552227777", "+15553337777"}, "+15559998888", {"Hi", "Hi again"})

In the above example, both numbers will receive both messages.

Message Length

It is up to you to limit the length of your messages to 160 characters. Longer messages will be accepted and sent, but will be broken into multiple SMS messages.

Throttling / Multiple Senders

There is a limit on the rate which messages can be sent. In order to increase the rate of throughput, you may specify multiple sender numbers. In that case, outbound messages will be distributed as evenly as possible among those numbers.

receivers = {"+15553334343", "+15552329999", ...}
senders = {"+15554441234", "+15554441235", ...}

sms.send(receivers, senders, "Welcome to Miskatonic University")

Authorization

You must provide a sender number that is authorized for use by your application. If you try to use a number that is not assigned to your application, the call will fail. This applies to all sender numbers, so if in a list of senders, one number is invalid, the entire sms.send() call will fail with an error message and no SMS messages will be sent.

Message Status / Latency

The sms.send() function call does not send the SMS message directly, but emplaces the message on a queue and will be sent in order of receipt. This is necessary to enforce message sending rate limits and to prevent your Summit application from blocking.

This means there is a latency which cannot be determined at the time of message submission. Actual delivery time will depend on SMS network condition as well as the number of previously queued messages for your number.

This also means that it is possible that your messages may not actually be delivered due to errors which are unknowable at the time your application submits them. Errors such as bad recipient numbers and network errors fall into this category. In order to track message status, we provide a callback URL option.

Callback URL

The fourth parameter to sms.send() is optional and may contain a URL. When an SMS message is actually sent, this URL will be sent a request. It is up to you to provide and maintain the web server on the other end of this URL. Note that a single attempt will be made to send a request, if it fails, it fails.

ok, err = sms.send("5559341222",
                  "5554443322",
                  "Provisional authority granted",
                  "http://mcmurdo.example.com/sms_status")

When this messages is delivered or fails, the server at mcmurdo.example.com will receive a POST request with a request body that is structured like this:

{
  "Body": "Provisional authority granted",
  "To": "5559341222",
  "From": "5554443322",
  "Success": true,
  "SMSMessageId": "d193b771-68f1-4e2e-945e-8d332e08c2b5"
}

Functions

Name Summary
send

The function that actually sends your SMS messages.

Functions : sms

send(to, sender, message, callback_url)

The function that actually sends your SMS messages.

Parameters
Name Type Default Summary

to

string or list

Recipient(s) of the text message(s)

sender

string or list

Sender(s) of the message(s)

message

string or list

Message(s) to send

callback_url

string

URL which will receive a POST notification of message status at the time of attempted delivery.

Returns
Type Summary

string

‘OK’ if successful, nil on error

string

nil if successful, error_message otherwise.

Usage
ok, err = sms.send({"+15555553434", "+15554446543"}, "+15557773233", "Your shirt is ready")
ok2, err2 = sms.send("+15555553434", "+15557773233", "Proceed to level five", "http://3xz.example.com/status")