Commits

Matthew Schinckel  committed c52381c

Updated readme.

  • Participants
  • Parent commits 45bf1d0

Comments (0)

Files changed (2)

 django-sms-gateway
 ====================
 
-Easily send SMS messages through a web gateway from django.
+Easily send SMS messages through a web gateway from django.
+
+Installation
+-------------
+
+  * Install the package into your project's virtual environment:
+  
+    ``pip install django-sms-gateway``
+
+  * Add ``sms`` to your project's ``settings.INSTALLED_APPS``.
+
+  * Run ``./manage.py migrate`` or ``./manage.py syncdb``
+  
+Configuration
+--------------
+
+There are three django models: ``sms.Message``, ``sms.Gateway``, and ``sms.Reply``.
+
+Before you are able to send any messages, you will need to configure at least one gateway. There is some sample data for some gateway providers. You can adapt one of these for your own purposes.
+
+Usage
+------
+
+Create a message, ready to be sent::
+
+    msg = Message.objects.create(
+      recipient_number="123456789", 
+      content="Test message",
+      sender=user,
+      billee=user
+    )
+
+Note that you must provide at least these fields. ``recipient_number`` must include the international prefix (or your gateway must be configured to add it). ``content`` should be ASCII, some gateways reject unicode. ``sender`` must be an ``auth.User``, but ``billee`` may be any object.
+
+This does not send the message::
+
+    >>> msg
+    <Message: [Unsent] Sent to 123456789 by matt at None [1]>
+
+To send it, you need to provide a gateway::
+
+    msg.send(gateway)
+
+Status/Reply Callback
+----------------------
+
+If your gateway supports it, you can have it hit your server whenever there are status updates on any message. You can use the included views, in your urlpatterns::
+
+    urlpatterns = patterns('',
+      (r'^sms/', include('sms.urls')),
+    )
+
+This would mean that you would need to enter something like::
+
+    http://example.com/sms/status_postback/
+
+In your gateway's settings.
+
+The same applies for replies, if you have a 2-way gateway, but using ``/sms/reply_postback/`` instead.
+
+Reply callback functions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you send a message, you can store a ``reply_callback`` function in the object. This function will be called, with the reply object passed in as the parameter. The reply object has access to it's original message (as well as it could be matched).
+
+Future
+--------
+Currently, all sending happens in-process. There is a preliminary celery task, but it has not been extensively tested as yet.

File sms/views.py

     msg = Message.objects.get_matching_message(data)
     
     if not msg:
-        logger.debug("Message could not be found: %s" % data)
+        logger.warn("Message could not be found: %s" % data)
         # Need to respond with OK, else remote server will keep trying.
         return HttpResponse('OK')
         
 @csrf_exempt
 def handle_reply(request):
     logger.debug("SMS Reply received.")
+    
+    # If this request was 'empty', it was a ping test by the server.
+    if not request.GET:
+        return HttpResponse("OK")
+    
     data = {}
     for k,v in request.GET.items():
         if isinstance(v, list) and len(v) == 1:
     msg = Message.objects.get_original_for_reply(data)
     
     if not msg:
-        logger.debug("Original message could not be found: %s" % data)
+        logger.warn("Original message could not be found: %s" % data)
         return HttpResponse('OK')
         
     logger.debug("Found message %i" % msg.pk)