updating twilio module docs and making it possible to send to a list of phone numbers

lib/ansible/modules/extras/notification/twilio.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2014, Matt Makai <matthew.makai@gmail.com>
+# (c) 2015, Matt Makai <matthew.makai@gmail.com>
 #
 # This file is part of Ansible
 #
@@ -24,18 +24,20 @@ version_added: "1.6"
 module: twilio
 short_description: Sends a text message to a mobile phone through Twilio.
 description:
-   - Sends a text message to a phone number through an the Twilio SMS service. 
+   - Sends a text message to a phone number through the Twilio SMS API.
 notes:
-   - Like the other notification modules, this one requires an external 
+   - This module is non-idempotent because it sends an email through the
+     external API. It is idempotent only in the case that the module fails.
+   - Like the other notification modules, this one requires an external
      dependency to work. In this case, you'll need a Twilio account with
      a purchased or verified phone number to send the text message.
 options:
   account_sid:
     description:
-      user's account id for Twilio found on the account page
+      user's Twilio account token found on the account page
     required: true
   auth_token:
-    description: user's authentication token for Twilio found on the account page
+    description: user's Twilio authentication token
     required: true
   msg:
     description:
@@ -43,36 +45,45 @@ options:
     required: true
   to_number:
     description:
-      what phone number to send the text message to, format +15551112222
+      one or more phone numbers to send the text message to,
+      format +15551112222
     required: true
   from_number:
     description:
-      what phone number to send the text message from, format +15551112222
+      the Twilio number to send the text message from, format +15551112222
     required: true
-  
-requirements: [ urllib, urllib2 ]
+
 author: Matt Makai
 '''
 
 EXAMPLES = '''
-# send a text message from the local server about the build status to (555) 303 5681
-# note: you have to have purchased the 'from_number' on your Twilio account
-- local_action: twilio msg="All servers with webserver role are now configured." 
-  account_sid={{ twilio_account_sid }}
-  auth_token={{ twilio_auth_token }}
-  from_number=+15552014545 to_number=+15553035681
+# send an SMS about the build status to (555) 303 5681
+# note: you have to have the 'from_number' on your Twilio account
+- twilio:
+    msg: "All servers with webserver role are now configured."
+    account_sid: "{{ twilio_account_sid }}"
+    auth_token: "{{ twilio_auth_token }}"
+    from_number: "+15552014545"
+    to_number: "+15553035681"
+  delegate_to: localhost
+
+# send an SMS to multiple phone numbers about the deployment
+# note: you must have the 'from_number' on your Twilio account
+- twilio:
+    msg: "This server's configuration is now complete."
+    account_sid: "{{ twilio_account_sid }}"
+    auth_token: "{{ twilio_auth_token }}"
+    from_number: "+15553258899"
+    to_number:
+      - "+15551113232"
+      - "+12025551235"
+      - "+19735559010"
+  delegate_to: localhost
 
-# send a text message from a server to (555) 111 3232
-# note: you have to have purchased the 'from_number' on your Twilio account
-- twilio: msg="This server's configuration is now complete."
-  account_sid={{ twilio_account_sid }}
-  auth_token={{ twilio_auth_token }}
-  from_number=+15553258899 to_number=+15551113232
-  
 '''
 
 # =======================================
-# text module support methods
+# twilio module support methods
 #
 try:
     import urllib, urllib2
@@ -82,10 +93,11 @@ except ImportError:
 import base64
 
 
-def post_text(module, account_sid, auth_token, msg, from_number, to_number):
+def post_twilio_api(module, account_sid, auth_token, msg, from_number,
+                    to_number):
     URI = "https://api.twilio.com/2010-04-01/Accounts/%s/Messages.json" \
         % (account_sid,)
-    AGENT = "Ansible/1.5"
+    AGENT = "Ansible"
 
     data = {'From':from_number, 'To':to_number, 'Body':msg}
     encoded_data = urllib.urlencode(data)
@@ -94,7 +106,7 @@ def post_text(module, account_sid, auth_token, msg, from_number, to_number):
         (account_sid, auth_token)).replace('\n', '')
     request.add_header('User-Agent', AGENT)
     request.add_header('Content-type', 'application/x-www-form-urlencoded')
-    request.add_header('Accept', 'application/ansible')
+    request.add_header('Accept', 'application/json')
     request.add_header('Authorization', 'Basic %s' % base64string)
     return urllib2.urlopen(request, encoded_data)
 
@@ -115,7 +127,7 @@ def main():
         ),
         supports_check_mode=True
     )
-  
+
     account_sid = module.params['account_sid']
     auth_token = module.params['auth_token']
     msg = module.params['msg']
@@ -123,12 +135,18 @@ def main():
     to_number = module.params['to_number']
 
     try:
-        response = post_text(module, account_sid, auth_token, msg, 
-            from_number, to_number)
-    except Exception, e:
+        if isinstance(to_number, list):
+            for number in to_number:
+                post_twilio_api(module, account_sid, auth_token, msg,
+                    from_number, number)
+        else:
+            post_twilio_api(module, account_sid, auth_token, msg,
+                from_number, to_number)
+        pass
+    except Exception:
         module.fail_json(msg="unable to send text message to %s" % to_number)
 
-    module.exit_json(msg=msg, changed=False) 
+    module.exit_json(msg=msg, changed=False)
 
 # import module snippets
 from ansible.module_utils.basic import *