Merge pull request #393 from makaimc/twilio

Update twilio module for MMS & multiple message recipients

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 messaging 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,64 @@ 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 ]
+  media_url:
+    description:
+      a URL with a picture, video or sound clip to send with an MMS
+      (multimedia message) instead of a plain SMS
+    required: false
+
 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 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
-  
+# send an SMS about the build status to (555) 303 5681
+# note: replace account_sid and auth_token values with your credentials
+# and you have to have the 'from_number' on your Twilio account
+- twilio:
+    msg: "All servers with webserver role are now configured."
+    account_sid: "ACXXXXXXXXXXXXXXXXX"
+    auth_token: "ACXXXXXXXXXXXXXXXXX"
+    from_number: "+15552014545"
+    to_number: "+15553035681"
+  delegate_to: localhost
+
+# send an SMS to multiple phone numbers about the deployment
+# note: replace account_sid and auth_token values with your credentials
+# and you have to have the 'from_number' on your Twilio account
+- twilio:
+    msg: "This server's configuration is now complete."
+    account_sid: "ACXXXXXXXXXXXXXXXXX"
+    auth_token: "ACXXXXXXXXXXXXXXXXX"
+    from_number: "+15553258899"
+    to_number:
+      - "+15551113232"
+      - "+12025551235"
+      - "+19735559010"
+  delegate_to: localhost
+
+# send an MMS to a single recipient with an update on the deployment
+# and an image of the results
+# note: replace account_sid and auth_token values with your credentials
+# and you have to have the 'from_number' on your Twilio account
+- twilio:
+    msg: "Deployment complete!"
+    account_sid: "ACXXXXXXXXXXXXXXXXX"
+    auth_token: "ACXXXXXXXXXXXXXXXXX"
+    from_number: "+15552014545"
+    to_number: "+15553035681"
+    media_url: "https://demo.twilio.com/logo.png"
+  delegate_to: localhost
 '''
 
 # =======================================
-# text module support methods
+# twilio module support methods
 #
 try:
     import urllib, urllib2
@@ -82,19 +112,22 @@ 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, media_url=None):
     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}
+    if media_url:
+        data['MediaUrl'] = media_url
     encoded_data = urllib.urlencode(data)
     request = urllib2.Request(URI)
     base64string = base64.encodestring('%s:%s' % \
         (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)
 
@@ -112,23 +145,29 @@ def main():
             msg=dict(required=True),
             from_number=dict(required=True),
             to_number=dict(required=True),
+            media_url=dict(default=None, required=False),
         ),
         supports_check_mode=True
     )
-  
+
     account_sid = module.params['account_sid']
     auth_token = module.params['auth_token']
     msg = module.params['msg']
     from_number = module.params['from_number']
     to_number = module.params['to_number']
+    media_url = module.params['media_url']
+
+    if not isinstance(to_number, list):
+        to_number = [to_number]
 
-    try:
-        response = post_text(module, account_sid, auth_token, msg, 
-            from_number, to_number)
-    except Exception, e:
-        module.fail_json(msg="unable to send text message to %s" % to_number)
+    for number in to_number:
+        try:
+            post_twilio_api(module, account_sid, auth_token, msg,
+                from_number, number, media_url)
+        except Exception:
+            module.fail_json(msg="unable to send message to %s" % number)
 
-    module.exit_json(msg=msg, changed=False) 
+    module.exit_json(msg=msg, changed=False)
 
 # import module snippets
 from ansible.module_utils.basic import *