DTMF API Client for Python

class dtmf.DTMF(token)

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

>>> from dtmf import DTMF
>>> dtmf = DTMF("your token")
Parameters:token (str) – An active API token associated with your account on DTMF.io
account()

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

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

Gets your active Bitcoin deposit addresses for adding funds to your account.

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

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

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

Gets all possible phone number groups of a given type.

>>> 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},
 ...
]
Parameters:group_type (str) – The type of phone number groups to return, ‘mobile’ or ‘local’
Raises:ValueError – if group_type has an invalid value
numbers()

Gets all phone numbers currently rented by your account.

>>> 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},
               ...
              ]},
 ...
]
number(e164)

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

>>> 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}
Parameters:e164 (str) – the phone number to return details about, in E.164 format
Raises:ValueError – if the parameter is not in E.164 format
start_rental(group_id)

Rents a new number from a specified phone number group.

>>> 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': []}
Parameters:group_id (str) – the phone number group to rent a number from (the id key from the objects returned by the groups call)
end_rental(e164)

Ends the rental of a specified phone number.

>>> dtmf.end_rental("+1234567891")
True
Parameters:e164 (str) – the phone number to end the rental of, in E.164 format
Raises:ValueError – if the parameter is not in E.164 format
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:

>>> dtmf.set_sms_action("+1234567890", None, None)
True

To forward the SMS to another number (+44123456789 in this example):

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

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

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

{'id': 1234, 'e164': '+1234567890', 'sender': '+1234', 'content': 'SMS text'}
Parameters:
  • e164 (str) – the phone number to set the SMS action for, in E.164 format
  • action (str) – either ‘forward’, ‘webhook’ or None
  • destination (str) – 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