DTMF API Client for Python

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

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.

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

>>> 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'}

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.

Parameters:
  • e164 (str) – 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.
  • 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

send_sms(from_e164, to_e164, content)

Sends an SMS from a phone number that you have rented to another phone number.

>>> dtmf.send_sms("+1234567890", "+1234", "this is the content of the SMS")
True
Parameters:
  • from_e164 (str) – 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.
  • to_e164 (str) – the phone number to send the SMS to, in E.164 format
  • content (str) – 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.