community.general/plugins/modules/twilio.py

#!/usr/bin/python

# Copyright (c) 2015, Matt Makai <matthew.makai@gmail.com>
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later

from __future__ import annotations


DOCUMENTATION = r"""
module: twilio
short_description: Sends a text message to a mobile phone through Twilio
description:
  - Sends a text message to a phone number through the Twilio messaging API.
notes:
  - 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 need a Twilio
    account with a purchased or verified phone number to send the text message.
extends_documentation_fragment:
  - community.general.attributes
attributes:
  check_mode:
    support: full
  diff_mode:
    support: none
options:
  account_sid:
    type: str
    description:
      - User's Twilio account token found on the account page.
    required: true
  auth_token:
    type: str
    description:
      - User's Twilio authentication token.
    required: true
  msg:
    type: str
    description:
      - The body of the text message.
    required: true
  to_numbers:
    type: list
    elements: str
    description:
      - One or more phone numbers to send the text message to, format C(+15551112222).
    required: true
    aliases: [to_number]
  from_number:
    type: str
    description:
      - The Twilio number to send the text message from, format C(+15551112222).
    required: true
  media_url:
    type: str
    description:
      - A URL with a picture, video or sound clip to send with an MMS (multimedia message) instead of a plain SMS.

author: "Matt Makai (@makaimc)"
"""

EXAMPLES = r"""
# 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
- name: Send a text message to a mobile phone through Twilio
  community.general.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
- name: Send a text message to a mobile phone through Twilio
  community.general.twilio:
    msg: This server configuration is now complete.
    account_sid: ACXXXXXXXXXXXXXXXXX
    auth_token: ACXXXXXXXXXXXXXXXXX
    from_number: "+15553258899"
    to_numbers:
      - "+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
- name: Send a text message to a mobile phone through Twilio
  community.general.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
"""

# =======================================
# twilio module support methods
#
from urllib.parse import urlencode
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url


def post_twilio_api(module, account_sid, auth_token, msg, from_number, to_number, media_url=None):
    URI = f"https://api.twilio.com/2010-04-01/Accounts/{account_sid}/Messages.json"
    AGENT = "Ansible"

    data = {"From": from_number, "To": to_number, "Body": msg}
    if media_url:
        data["MediaUrl"] = media_url
    encoded_data = urlencode(data)

    headers = {
        "User-Agent": AGENT,
        "Content-type": "application/x-www-form-urlencoded",
        "Accept": "application/json",
    }

    # Hack module params to have the Basic auth params that fetch_url expects
    module.params["url_username"] = account_sid.replace("\n", "")
    module.params["url_password"] = auth_token.replace("\n", "")

    return fetch_url(module, URI, data=encoded_data, headers=headers)


# =======================================
# Main
#


def main():
    module = AnsibleModule(
        argument_spec=dict(
            account_sid=dict(required=True),
            auth_token=dict(required=True, no_log=True),
            msg=dict(required=True),
            from_number=dict(required=True),
            to_numbers=dict(required=True, aliases=["to_number"], type="list", elements="str"),
            media_url=dict(),
        ),
        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_numbers = module.params["to_numbers"]
    media_url = module.params["media_url"]

    for number in to_numbers:
        r, info = post_twilio_api(module, account_sid, auth_token, msg, from_number, number, media_url)
        if info["status"] not in [200, 201]:
            body_message = "unknown error"
            if "body" in info:
                body = module.from_json(info["body"])
                body_message = body["message"]
            module.fail_json(msg=f"unable to send message to {number}: {body_message}")

    module.exit_json(msg=msg, changed=False)


if __name__ == "__main__":
    main()