modules/smsgateway/README.txt

$Id: README.txt,v 1.1 2005/10/22 22:24:14 therave Exp $

SMSGateway
----------

This is a module that allows the sending/receiving of SMS messages from/to a 
Drupal website. You need an account with a SMS Service Provider to make this 
work.

Currently the system only provides support for the Clickatell Service Provider
and only for HTTP/HTTPS protocol message sending. See Gateway Services below for 
more details.

This module only has configuration, logging and self-test functionality. In 
order to use it as part of your site, you need to adapt your own modules.

To send a message, call the 'smsgateway_sendmessage' function, with the 
destination telephone number and the message body text as parameters.
The function returns an array with the response from the Service Provider
Gateway in the 'response' key, the string used to contact the gateway in the 
'connectstring' key (used for debugging) and the balance at the start of the
transmission under the 'initialbalance' key. 

To send more than one message at a time, call the 'smsgateway_sendmessageset' 
function, with an array of messages keyed by unique ID (used for tracking the 
responses) and subarray with the destination number in 'destination_number' and
the text of the message in 'message_body'.
The function returns an array with the string used to contact the gateway in the 
'connectstring' key (used for debugging), the balance at the start of the
transmission under the 'initialbalance' key and the response from the Service 
Provider Gateway for each message under the uid key provided.

The message reception requires requires 'anonymous user' access to be set for
the 'receive sms message' permission. Modules that wish to be informed of a 
newly arrived message should implement the 'smsgateway_newmessage' hook and
process the array passed as a parameter with the message parts in the following 
fields:
        'account_id' the ID of the account that the message was received on
        'sender_number' the telephone number of the message sender
        'destination_number' the telephone number that the message was sent to
        'timestamp' the timestamp placed on the message
        'charset' optional character set information for the message body
        'header' any additional header information
        'body' the body of the message - the message text


Gateway Services
----------------

Clickatell - http://www.clickatell.com/

This provides a good value range of services for low-medium volumes of messages.
Registration is straightforward - for the HTTP/S service go to:
http://www.clickatell.com/central/login.php?prod_id=2
and fill out the form. Currently they give 10 free credits on registration.

To Do
-----

Add support for the Clickatell bulk message sending to improve the speed of 
sending multiple messages. Currently the smsgateway_sendmessageset method logs 
in once, but sends the actual messages using the single message-send protocol.

Add filtering support for SMS logs and support for autodeletion after a defined 
period.

Add support for alternative Service Providers.

Add support for other protocols, notably the XML method supported by 
Clickatell.


Special Thanks
--------------

Aleksandar Markovic for providing the Clickatell Service Provider API.
http://sourceforge.net/projects/sms-api/

iMustard.com - http://www.imustard.com - for sponsoring this module.

--
David Hamilton <david dot hamilton at jiffle dot net>
1	$Id: README.txt,v 1.1 2005/10/22 22:24:14 therave Exp $
2
3	SMSGateway
4	----------
5
6	This is a module that allows the sending/receiving of SMS messages from/to a
7	Drupal website. You need an account with a SMS Service Provider to make this
8	work.
9
10	Currently the system only provides support for the Clickatell Service Provider
11	and only for HTTP/HTTPS protocol message sending. See Gateway Services below for
12	more details.
13
14	This module only has configuration, logging and self-test functionality. In
15	order to use it as part of your site, you need to adapt your own modules.
16
17	To send a message, call the 'smsgateway_sendmessage' function, with the
18	destination telephone number and the message body text as parameters.
19	The function returns an array with the response from the Service Provider
20	Gateway in the 'response' key, the string used to contact the gateway in the
21	'connectstring' key (used for debugging) and the balance at the start of the
22	transmission under the 'initialbalance' key.
23
24	To send more than one message at a time, call the 'smsgateway_sendmessageset'
25	function, with an array of messages keyed by unique ID (used for tracking the
26	responses) and subarray with the destination number in 'destination_number' and
27	the text of the message in 'message_body'.
28	The function returns an array with the string used to contact the gateway in the
29	'connectstring' key (used for debugging), the balance at the start of the
30	transmission under the 'initialbalance' key and the response from the Service
31	Provider Gateway for each message under the uid key provided.
32
33	The message reception requires requires 'anonymous user' access to be set for
34	the 'receive sms message' permission. Modules that wish to be informed of a
35	newly arrived message should implement the 'smsgateway_newmessage' hook and
36	process the array passed as a parameter with the message parts in the following
37	fields:
38	'account_id' the ID of the account that the message was received on
39	'sender_number' the telephone number of the message sender
40	'destination_number' the telephone number that the message was sent to
41	'timestamp' the timestamp placed on the message
42	'charset' optional character set information for the message body
43	'header' any additional header information
44	'body' the body of the message - the message text
45
46
47	Gateway Services
48	----------------
49
50	Clickatell - http://www.clickatell.com/
51
52	This provides a good value range of services for low-medium volumes of messages.
53	Registration is straightforward - for the HTTP/S service go to:
54	http://www.clickatell.com/central/login.php?prod_id=2
55	and fill out the form. Currently they give 10 free credits on registration.
56
57	To Do
58	-----
59
60	Add support for the Clickatell bulk message sending to improve the speed of
61	sending multiple messages. Currently the smsgateway_sendmessageset method logs
62	in once, but sends the actual messages using the single message-send protocol.
63
64	Add filtering support for SMS logs and support for autodeletion after a defined
65	period.
66
67	Add support for alternative Service Providers.
68
69	Add support for other protocols, notably the XML method supported by
70	Clickatell.
71
72
73	Special Thanks
74	--------------
75
76	Aleksandar Markovic for providing the Clickatell Service Provider API.
77	http://sourceforge.net/projects/sms-api/
78
79	iMustard.com - http://www.imustard.com - for sponsoring this module.
80
81	--
82	David Hamilton <david dot hamilton at jiffle dot net>