Sending SMS in China with SMS Framework

SMS platforms are surely nothing new to anyone, but as a Drupal module it is still quite a novelty. The module is called “SMS Framework”, and it lives at http://drupal.org/project/smsframework. It has released version 1.0.

The core of SMS Framework is a very basic framework: it defines a set of functions, or interfaces, that let other developers easily build front-end interfaces or back-end SMS interfaces (Gateways), and it also provides some useful modules built on this framework. For example, sms_user lets each user be associated with a phone number, sms_clickatell is a Gateway, and so on (see the appendix at the end for details). These modules are not yet complete, so for now SMS Framework is still only a development tool. What this article wants to show is how to use it to develop a Drupal module that can send text messages in China.

The first thing to explain is how to send a text message to a mobile phone over the web. Simply put, the website's server sends a network request, following a specific protocol, to an SMS provider (China Mobile and the like, or a second-tier reseller). The protocol is decided by the provider: it may be custom-built (China Mobile, for example), it may be REST (commonly HTTP GET), or it may be SOAP, and so on. This raises the question of which provider to choose. Generally speaking, top-tier providers suit well-resourced companies better, because not only is the bar to apply high, but since the protocols are custom-built, development costs are also higher; second-tier resellers, by contrast, suit fast sign-up and fast development, but with varying degrees of limitation in features and flexibility.

Next, let's look at SMS Framework itself. I am using the HEAD version from early September. (Note that because this module is at an early stage of development, the APIs and functions change often and substantially, so the module itself should be taken as the reference.) It defines a set of hooks and functions, the most basic of which are:

1. hook_gateway_info() —— used to add an SMS interface, that is, to implement a given SMS protocol. Simply put, you define a new function whose parameters are the recipient number, the message content and so on, and whose job is to package this content and send it out using the protocol.
2. sms_send() —— used to send a text message; its parameters are also the recipient number, the message content and so on. This is meant for the front end: it calls a designated Gateway to send the message.

What we want to implement here is a Gateway; as for using it, you can write a simple page that calls sms_send() to test it. Before you start, refer to “API.txt” and to modules such as sms_clickatell that implement a Gateway.

Taking the Webservice (SOAP) of WINIC (http://www.winic.org/) as an example, here is what needs to be written:

1. Module —— call it sms_winic; you need to write the info file;
2. sms_winic_gateway_info() —— defines the Gateway's information and functions;

   return array(
     'winic' => array(
       'name' => 'WINIC',
       'configure form' => 'sms_winic_admin_form', // specify a function name; you have to implement it yourself
       'send' => 'sms_winic_send', // same as above
       'send form' => 'sms_winic_send_form', // same as above
     ),
   );

3. sms_winic_send($number, $message, $options) —— the sending function itself;
   First, use “$soapclient = new SoapClient($winic_url);” to create the client (requires PHP SOAP support);
   Then you can use methods such as “__getFunctions()” and “__getTypes()” to get the methods offered by the SOAP server; these can be used while testing.
   For the methods WINIC provides, a single call to “$response = $soapclient->SendMessages($parameters);” sends the message. $parameters must contain the following information:

   array
     'tos' => string 'number,number'
     'msg' => string 'message content'
     'otime' => string ''
     'uid' => string 'test'
     'pwd' => string '123456'

   Generally, the SOAP server returns an object containing a status message; analyze this message according to the documentation WINIC provides, report back to the user or move on to the next step, and this function's job is done.
4. configure form —— a standard form function, where you can put settings such as the username and password;
5. send form —— also a standard form function, which can be used to add extra fields to the sending form.

With that, a simple Gateway is implemented. To use or test it, first set it as the Default on the configuration page, then call sms_send() wherever you like.

As you can see, SMS Framework makes implementing an SMS protocol very straightforward, which is very close to Drupal's own philosophy, and the complexity of a Gateway depends largely on the complexity of the SMS protocol.

End of article.

Note: I have already submitted sms_winic: http://drupal.org/node/310154

Appendix —— existing modules and what they do

• sms.module —— core API
• sms_clickatell.module —— Clickatell gateway (http://clickatell.com/) SMS interface
• sms_muse.module —— Muse gateway (http://mobilemuse.ca/) SMS interface
• sms_email_gateway.module —— sends text messages via email
• sms_user.module —— integrates with Drupal users, letting each user set a mobile phone number
• sms_sendtophone.module —— provides some interfaces for sending text messages
• sms_blast.module —— sends bulk text messages
• sms_receive.module —— provides support for receiving text messages (not yet complete)
• sms_og.module —— provides support for receiving text messages for Organic Groups (depends on sms_receive)
• Besides these built-in modules, another module —— the Messaging module (http://drupal.org/project/messaging) —— also supports it, which means messaging can use sms to send messages.