Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

SMSMatrix

Outdated egg!
SMSMatrix

Description

A convenient library for the SMSMatrix SMS/fax gateway.

Author

Written for Response Genetics, Inc. by Peter Bex.

Documentation

The API broadly consists of two parts: pure querying and actual message sending.

Most procedures accept a username and password argument, which you can pass on each call. Alternatively, you can set the username and password once in a global parameter so you can easily put it in a configuration file, or enter it once on the REPL. If you pass a username and password to the procedure, those will have precedence over the global parameters.

[parameter] (smsmatrix-username [USERNAME])

USERNAME should be a string which identifies your SMSMatrix username (generally in the form of an email address).

[parameter] (smsmatrix-password [PASSWORD])

PASSWORD should be a string which identifies your SMSMatrix password.

Sending messages

[procedure] (send-sms RECIPIENTS MESSAGE [username: USERNAME] [password: PASSWORD] [group: GROUP?] [tts-fallback: FALLBACK?] [error-on-failure ERROR?])

Send MESSAGE (a string) as an SMS-message to RECIPIENTS, which is either a string or a list of strings identifying the recipients. These can be either phone numbers or a group name. If it's a group, GROUP? should be #t, otherwise it should be #f (the default). Groups can be defined in the SMSMatrix user interface on their site.

If FALLBACK? is #t, and one of the recipient numbers is a land line which can't receive SMS messages, the service will attempt to use a text-to-speech fallback for delivering your message, otherwise it will raise an error. FALLBACK? defaults to #f.

If ERROR? is #t (the default) this procedure will raise an error on the first number that failed. Be careful, however, this will currently just throw one error even if multiple phone numbers failed (there can also be different reasons for failure). If it is #f, you will just get a list of result alists which you will need to check for errors yourself.

The result of this call is a list of alists. Each alist represents one message sent, and includes the following keys:

pin: The phone number of this record (a string)
id: The internal ID (an opaque hash code as a string) assigned to this message. You can use this to request more information with message-status or to look up the message in the CSV report.
timestamp: A number which is the UNIX timestamp at which time the message was delivered.
statuscode: A status code (number) indicating the delivery status of this record.
statustxt: A string containing the delivery status message.

[procedure] (send-fax RECIPIENTS FILENAME [username: USERNAME] [password: PASSWORD] [group: GROUP?] [error-on-failure ERROR?])

Send the file indicated by FILENAME as a fax-message to RECIPIENTS, which is either a string or a list of strings identifying the recipients. These can be either phone numbers or a group name. If it's a group, GROUP? should be #t, otherwise it should be #f (the default). Groups can be defined in the SMSMatrix user interface on their site.

The file types accepted by SMSMatrix are listed on their site. At the time of writing this includes PDF, most common image formats and several office file formats.

The result of this call is a list of alists. Each alist represents one message sent, and includes the following keys:

pin: The phone number of this record (a string)
id: The internal ID (an opaque hash code as a string) assigned to this message. You can use this to request more information with message-status or to look up the message in the CSV report.
timestamp: A number which is the UNIX timestamp at which time the message was delivered.
statuscode: A status code (number) indicating the delivery status of this record.
statustxt: A string containing the delivery status message.

Warning: The fax API is undocumented save for one Perl example. It is also officially unsupported by SMSmatrix at the time of writing. The procedure has been tested and returned the same error as the Perl example did, so it should most likely work, but nothing is guaranteed.

Retrieving information

[procedure] (get-credits [username: USERNAME] [password: PASSWORD])

Get the number of credits left on your account, as a number (possibly a flonum).

[procedure] (message-status MESSAGE-ID [username: USERNAME] [password: PASSWORD])

Get the status of a message that was sent earlier. The MESSAGE-ID should be a string which send-sms returned (ie, an opaque hash code).

Returns 5 values:

The user's response, which is a number indicating which key on the phone the user pressed in response to a voice question, or #f if it was a non-interactive call or the user didn't choose anything.
The timestamp when the message was sent (a UNIX timestamp number)
The timezone (a string which appears to always be "PDT")
The message delivery status code (a number)
The message delivery status message (a string)

[procedure] (get-rate TYPE PHONE-NUMBER)

Get the current rate (credits subtracted from your account when you would send a message of the given TYPE) for PHONE-NUMBER (a string). TYPE is a symbol indicating the type of message and can currently be one of sms (SMS messages), voice (prerecorded audio) or tts (text-to-speech synthesis).

This is the only API entry point which does not require a valid SMSMatrix account, hence there are no username/password arguments.

[procedure] (carrier-name PHONE-NUMBER [username: USERNAME] [password: PASSWORD])

Returns the name (a string) of the cellular carrier (one of those listed in the carrier table on the SMSMatrix website) for PHONE-NUMBER. It might also return "UNKNOWN" if the phone number is valid but it doesn't know the carrier.

[procedure] (call-with-csv-report PROC [username: USERNAME] [password: PASSWORD] [limit: LIMIT] [incoming-only: INCOMING-ONLY?])

Get a summary report of all transactions made on your account.

The procedure PROC is invoked with one argument: an input port from which the report can be read (in CSV format).

If LIMIT (a number) is given and nonzero, a maximum of that many records will be returned (defaults to zero, ie all messages).

If INCOMING-ONLY? is #t, only incoming messages are shown (useful when using the "virtual mobile phone number" feature, whatever that may be....

Changelog

0.1 Initial release

License

 Copyright (c) 2011, Response Genetics, Inc.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.