PyTill: A Python Package for Till Mobile

Published in

manifoldco

4 min readSep 11, 2018

Building SMS and Voice applications is hard, Till Mobile is on a mission to make that easy by providing a simple interface for building SMS and Voice applications. In order to make this even easier, we built an open source Python client PyTill (available on pypi for pip install).

To get started with PyTill lets take a look at how to implement two-factor authentication in just 8 lines of code:

Let’s get started with Manifold and Till

Till is simple — you can send messages, you can receive messages or ask questions, you can get results from those questions/received messages, and you can monitor the stats of your Till/SMS usage.

We recommend you use the Manifold CLI (get started here) as the best way to provision services like Till to securely and efficiently manage credentials.

Create your Till account

You can provision a free Till resource using the CLI as follows:

manifold create --project till-project --product till --plan free

Then you can inject your credentials as environment variables:

manifold run --project till-project -— python your-till-app.py

Without Manifold you would manually specify your API key and username:

export USERNAME=<your_till_username>
export API_KEY=<your_till_key>

Install and import PyTill

We can add PyTill to our Python project by using pip to install the package:

pip install pytill

Then import pytill to your application:

from pytill import pytill

Sending Messages

To send a text message it’s as simple as providing a number and the message you would like to send:

pytill.send_message(['19024880000'], 'I am sending a till message isnt that cool!')

Receiving Messages; Asking Questions

We ask a question to enable two-way communication with Till, and receive responses through the defined web hook.

question = pytill.make_question('How cool is Till mobile?', 'my-question', 'my.webhook/listens/here')pytill.send_question(['19024441111', '16139094888'], [question], 'my-project')

Getting Results

We use get_results to retrieve results for a specific question:

print(pytill.get_results(question_tag=’my-question’))

Sample output:

{'meta': {'limit': 20, 'next': None, 'offset': 0, 'previous': None, 'total_count': 1}, 'objects': [{'created': '2018–08–27T19:07:35.423855', 'guid': '252cd98f-5969–44c9-a955–7bb54e6f0d19', 'origin_phone_number': '+16508668969', 'participant_guid': '883c8f57–74b9–43cb-bb72-c7634b97651a', 'participant_phone_number': '+19024000158', 'project_launch_guid': '80262aea-a77e-4a0c-911f-23b959aea6da', 'project_launch_participant_guid': '8a23ee27–4841–4f2b-83d5–2a59a05825b8', 'project_tag': 'my-project', 'question_display_order': '0', 'question_guid': '8c8c168f-87d5–454d-8bae-09781312c097', 'question_tag': 'my-question', 'question_text': 'How cool is Till mobile?', 'result_answer': 'really cool!', 'result_guid': '252cd98f-5969–44c9-a955–7bb54e6f0d19', 'result_response': 'really cool!', 'result_timestamp': '2018–08–27T19:07:35.423855', 'updated': '2018–08–27T19:07:35.423884'}]}

Reading Stats

Using get_stats we can obtain stats about our usage:

print(pytill.get_stats())

Building 2FA with PyTill

In 8 lines of code we can build a random code generation module and send it to sms as a component to 2FA.

# 2fa.py
import random
import stringfrom pytill import pytillif __name__ == "__main__":
    code = ''.join(random.choices(string.ascii_letters +     string.digits, k=6))
    pytill.send_message(['19025555555'], 'Verification code is {}'.format(code))

We execute the code generation and send sms with manifold run

manifold run -p till-project -- python 2fa.py

To make it even more accessible lets send the verification as a voice message:

# 2fa_voice.py
import random
import stringfrom pytill import pytillif __name__ == "__main__":
    code = ' '.join(random.choices(string.ascii_letters +     string.digits, k=6))
    pytill.send_message(['19025555555'], 'Verification code is {}'.format(code), voice=True)

Notice that I added a space in the code string to ensure the letters and numbers are read individually.

Lets run it and send a text-to-voice call over to send the verification code:

manifold run -p till-project —- python 2fa.py

So there we have it, an easy way to use Python and Till to implement two-factor authentication in any application.

Check out PyTill on GitHub

Feel free to check out the source code as well as open any issues on the PyTill GitHub repository:

manifoldco/pytill

Python package for Till Mobile. Contribute to manifoldco/pytill development by creating an account on GitHub.

github.com

Till is your two-way SMS & Voice Microservice, now available. Use code TILL to get a $25 credit.