DTMF API Client for Python
==========================

Install it with :code:`pip install dtmf`. It works on both Python 2 and Python 3.

.. currentmodule:: dtmf

.. class:: DTMF(token)

    This class provides methods for each of the DTMF API functions.

    .. code-block:: python

       >>> from dtmf import DTMF
       >>> dtmf = DTMF("your token")

    :param str token: An active API token associated with your account on DTMF.io

    .. method:: account()

       Gets your account information (currently only your account balance in satoshis).

       .. code-block:: python

          >>> dtmf.account()
          {'balance': 12345}

    .. method:: addresses()
       
       Gets your active Bitcoin deposit addresses for adding funds to your account.

       .. code-block:: python

          >>> dtmf.addresses()
          [{'address': '1xxxxxx....'}, {'address': '1xxxxxx....'}]
    
    .. method:: new_address()

       Generates a new Bitcoin deposit address for adding funds to your account.

       .. code-block:: python

          >>> dtmf.new_address()
          {'address': '1xxxxxx....'}

    .. method:: groups(group_type)

       Gets all possible phone number groups of a given type.

       .. code-block:: python

          >>> dtmf.groups('mobile')
          [{'id': 'cz-mobile',
            'type': 'mobile',
            'name': 'Czech Republic',
            'country_code': 'cz',
            'sms_support': true,
            'voice_support': false,
            'setup_cost': 32093,
            'rental_cost_per_minute': 269,
            'cost_per_inbound_message': 601,
            'cost_per_inbound_call_minute': null},
           ...
          ]

       :param str group_type: The type of phone number groups to return, 'mobile' or 'local'
       :raises ValueError: if group_type has an invalid value

    .. method:: numbers()
          
       Gets all phone numbers currently rented by your account.

       The information returned includes whether the number supports SMS; the rental cost per minute; the cost of inbound SMS messages; when the rental started; forwarding settings (which can be changed with :func:`~dtmf.DTMF.set_sms_action`) and details of all SMS messages that were sent or received by this number during the rental period. All costs are in satoshis.

       .. code-block:: python

          >>> dtmf.numbers()
          [{'e164': '+1234567890',
            'group_id': 'us-mobile',
            'sms': true,
            'cost_per_minute': 13,
            'cost_per_inbound_message': 705,
            'assignment_start': '2018-01-01T01:01:01.000000',
            'sms_forwarded_to': null,
            'messages': [{'from': '+1234567890',
                          'to': '+1234',
                          'content': 'abc',
                          'timestamp': '2018-01-01T01:01:02.000000',
                          'success': true,
                          'cost': 1000},
                         ...
                        ]},
           ...
          ]

    .. method:: number(e164)

       Gets a specific phone number that is currently rented by your account.

       .. code-block:: python

          >>> dtmf.number("+1234567890")
          {'e164': '+1234567890',
           'group_id': 'us-mobile',
           'sms': true,
           'cost_per_minute': 13,
           'cost_per_inbound_message': 705,
           'assignment_start': '2018-01-01T01:01:01.000000',
           'sms_forwarded_to': null,
           'messages': [{'from': '+1234567890',
                         'to': '+1234',
                         'content': 'abc',
                         'timestamp': '2018-01-01T01:01:02.000000',
                         'success': true,
                         'cost': 1000}

       :param str e164: the phone number to return details about, in E.164 format
       :raises ValueError: if the parameter is not in E.164 format

    .. method:: start_rental(group_id)

       Rents a new number from a specified phone number group.

       .. code-block:: python

          >>> dtmf.start_rental("us-mobile")
          {'e164': '+1234567891',
           'group_id': 'us-mobile',
           'sms': true,
           'cost_per_minute': 13,
           'cost_per_inbound_message': 705,
           'assignment_start': '2018-01-02T01:01:01.000000',
           'sms_forwarded_to': null,
           'messages': []}

       :param str group_id: the phone number group to rent a number from (the :code:`id` key from the objects returned by the :func:`~dtmf.DTMF.groups` call)

    .. method:: end_rental(e164)

       Ends the rental of a specified phone number.

       .. code-block:: python

          >>> dtmf.end_rental("+1234567891")
          True

       :param str e164: the phone number to end the rental of, in E.164 format
       :raises ValueError: if the parameter is not in E.164 format

    .. method:: set_sms_action(e164, action, destination)

       Sets the action to be taken when a specified phone number receives an SMS.

       To take no action other than storing the SMS to be retrieved using the API or website:

       .. code-block:: python

          >>> dtmf.set_sms_action("+1234567890", None, None)
          True
       
       To forward the SMS to another number (+44123456789 in this example):

       .. code-block:: python

          >>> dtmf.set_sms_action("+1234567890", "forward", "+44123456789")
          True

       To call an HTTP webhook when this number receives an SMS:

       .. code-block:: python

          >>> dtmf.set_sms_action("+1234567890", "webhook", "https://example.org/webhook")
          True
       
       The webhook will receive an HTTPS POST with a JSON body structured like this:

       .. code-block:: javascript

          {'id': 1234, 'e164': '+1234567890', 'sender': '+1234', 'content': 'SMS text'}

       If the webhook responds with a successful (2xx) HTTP response and a non-empty body, then the body will be translated to ASCII preserving as much meaning as possible, truncated to 160 characters, and then sent as a reply to the sender of the message that triggered the webhook. If the HTTP response code is not in the 2xx range or the body is empty, no reply will be sent.

       :param str e164: the phone number to set the SMS action for, in E.164 format. it must be a phone number that is currently rented by your account.
       :param str action: either 'forward', 'webhook' or None
       :param str destination: the phone number to forward SMS to, for the 'forward' action; the webhook HTTP URL to call, for the 'webhook' action; or None
       :raises ValueError: if any parameter has invalid format

    .. method:: send_sms(from_e164, to_e164, content)
     
       Sends an SMS from a phone number that you have rented to another phone number.

       .. code-block:: python

          >>> dtmf.send_sms("+1234567890", "+1234", "this is the content of the SMS")
          True

       :param str from_e164: the phone number to send the SMS from, in E.164 format. it must be a phone number that is currently rented by your account.
       :param str to_e164: the phone number to send the SMS to, in E.164 format
       :param str content: the text content of the SMS. non-ASCII characters will be translated to ASCII preserving as much meaning as possible. the maximum length is 160 characters.