You are looking at historical revision 23962 of this page. It may differ significantly from its current revision.
A convenient library for the SMSMatrix SMS/fax gateway.
Requires the http-client egg.
The SMSMatrix egg is maintained in a Bitbucket repository.
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:
- The phone number of this record (a string)
- 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.
- A number which is the UNIX timestamp at which time the message was delivered.
- A status code (number) indicating the delivery status of this record.
- A string containing the delivery status message.
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)
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....
Currently no release available yet
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.