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

.. 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.

       .. 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 `id` key from the objects returned by the `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'}

       :param str e164: the phone number to set the SMS action for, in E.164 format
       :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