Messages are identified by numbers. These numbers are used to retrieve and update message contents, and to delete messages.
When a function of the module is called for the first time, it starts listening for incoming messages and enqueues their numbers. Calling sms.receive will return these numbers. Messages received earlier can be retrieved from the inbox.
Messages longer than the maximum length (160 characters in the default alphabet) can also be sent and received. They are transmitted as "concatenated SMS", but the module handles this automatically.
The typical sequence to consume messages starting with a certain token (//tok in our example) is:
|
nr=sms.receive(); // wait for a new message msg=sms.get(nr); // get the message words=split(msg["text"]); // split the text into words if len(words)>0 and words[0] = "//tok" then // first word is //tok, delete it from inbox sms.delete(nr); // process message end |
Delete the message with number msgnum from the inbox.
Throws ErrNotFound if the message with this number does not exist.
|
// delete all SMS inbox messages older than a week lastweek=time.get()-7*24*3600; for id in sms.inbox() do if sms.get(id)["time"]<lastweek then sms.delete(id) end end |
Get the contents of the message with number msgnum. The message contents are returned as an array with the following keys:
| Key | Contents |
| sender | The phone number of the sender of the message. |
| text | The text of the message. |
| time | The time stamp of the message, as seconds since the start of year 0. See also module time. |
| unread | true if the message is still unread, false if it has been seen. |
Throws ErrNotFound if the message with number msgnum does not exist.
|
// print all messages in the SMS inbox for id in sms.inbox() do print sms.get(id) end → [248,Delivery confirmation,63277873561,false]
... |
Gets the ids of all SMS messages in the inbox.
|
print sms.inbox() → [1049241,1049289,1049292]
|
Receives a new message and returns its id. If there is no message, waits until one arrives. If timeout>=0 and timeout milliseconds have passed without receiving anything, returns null.
Throws ExcValueOutOfRange if timeout exceeds 2147483 (35 minutes and 47.483 seconds).
|
// quickly check whether there is a new message id=sms.receive(0); if id#null then msg=sms.get(id); // process msg end |
Sends a short message to one or several recipients. A single recipient is specified as a single phone number string, multiple recipients are specified as an array of phone number strings.
bits indicates the number of bits used to encode a character, thus limiting the length of a simple message. Longer messages will be concatenated from several simple messages, thus increasing transmission cost. The allowed values are:
| bits | Meaning | Max. length |
| 7 | Default text alphabet | 160 |
| 8 | Data alphabet | 140 |
| 16 | Unicode alphabet | 70 |
This function does not return before the message has been sent (or an error occurs).
|
// send a silly message to two people sms.send(["+41797654321", "+393401234567"], "Good morning!") |
Updates the short message with number msgnum with the fields from message. The keys listed in sms.get must be used. The sender and text of the message will only be changed in the SMS inbox summary; they cannot be changed in the actual message.
|
// mark all messages in the inbox as unread for id in sms.inbox() do sms.set(id, ["unread":true]) end |