How to Build Client Payment Reminders using Twilio, Notion, and Python

How to Build Client Payment Reminders using Twilio, Notion, and Python

Running a business requires payment handling. It doesn't matter whether you are a freelancer or a big corporation, sometimes clients forget to pay their pending dues. If you have a huge list of clients, it makes for a tedious experience to go through the records daily and send them reminders. To solve this issue, you can automate the entire reminder workflow.

In this tutorial, you’ll learn to use Twilio’s WhatsApp API with the Notion API and Python to send payment reminders to your clients at regular intervals. You will use Notion for storing data, Twilio for sending WhatsApp messages, and Python to implement the business logic. We will create three reminders that will be sent 7 days before, 3 days before, 1 day before, and each day after the payment is due.

Prerequisites

To follow this tutorial you need the following items:

• Python 3.6 or newer. If your operating system does not provide a Python interpreter, you can go to python.org to download an installer.
• A Twilio account. If you are new to Twilio click here to create a free account.
• A Notion account. If you don't have one, click here to create a free account.
• A smartphone with an active WhatsApp account, to test the project.

The entire code for this repository is available in this GitHub repository.

Creating a Notion Database

The first thing you need to do is to create a Notion database.

To do so, open your Notion account, click on Add a page, and select Table under the databases.

Once the table is created, select the data source as a New database and give your database a name like “Clients”.

Every database table in Notion has a set of fields in which you can store your data. Add the following three fields after the Name field to your table:

1. Pending Amount (Number) - for specifying the amount to be paid by the client.

1. Due Date (Date) - for specifying the payment’s due date.

1. Phone No. (Phone) - a phone number of the client.

After creating your database, you need to add some test clients to it. For the sake of this tutorial, you can add the details of your family members and add the phone numbers that you can access. Make sure to add the phone numbers in E.164 format as recommended by Twilio otherwise you might get some errors while sending messages.

Your Notion database is now set up. Next, you need to query the data in Notion using the Notion API in your Python application.

Getting Notion API Token

To use the Notion API, you need to create a Notion integration and get an API access token.

To do so, visit https://www.notion.so/my-integrations and create a new integration. Give it a name “Payment Reminder”, and upload a logo if you want to.

Next, set its Content Capabilities to Read Content only and Comment Capabilities to None, and User Capabilities to No user information only and click Submit.

Once the integration is created, you will be presented with a secret API token. Copy and keep it safe as you will be using it later while writing the Python application.

By default, Integrations don't have access to pages or databases in Notion. So, you need to share the specific page or database that you want to query with the Notion API with your integration.

To do so, open your database in Notion. Click on the Share button and use the selector to find your integration by its name, and click Invite.

With that, you can now access your Notion database using the Notion API in your Python application.

Setting Up Python Project

First, open your terminal, navigate to a path of your choice, create a project directory called “payment-reminders”, and set up a virtual environment by running the following commands in your terminal:

For this project, you need to install the following PIP dependencies:

• twilio - Twilio’s Python SDK client for Twilio API.
• requests - Used to make HTTP requests.
• python-dotenv - Used for reading environment variables from the .env file.

Next, install the above-listed PIP dependencies by running the following command in your terminal:

Connecting to Notion API and Check Service Status

Now is the time to write some code. Firstly, you want to connect to the Notion API and fetch the entries in your database. Once you have the entries, you can loop over them and check their status by sending a GET request.

To do so, first create a src directory at the project’s root directory. In the src directory, create a main.py file and add the following code to it:

In the above code:

1. In the get_client_details function, you connect to the Notion API and query your Notion database to get the data stored in it. The POST request to https://api.notion.com/v1/databases/{NOTION_DATABASE_ID}/query returns the following response:

1. As the response is pretty big and you don’t need all of the data, you reduce the response by creating a new list of clients that have the following structure:

1. In the is_due function, you check whether the due_date is due or not. Since in this tutorial the objective is to send a reminder before seven days, three days, one day before the due date, and each day after the due date, this function checks the same.
2. In the main function, you call the get_client_details function and for the clients that have a pending due date, you call the send_reminder function, which you will write in the next section.

Next, create a .env file in the project’s root directory and add the following two environment variables to it:

To get your database ID, check out the URL structure for a Notion page - https://www.notion.so/{workspace_name}/{database_id}?v={view_id}. The part that corresponds to {database_id} in the URL is your database’s ID. It is a 36-character long string.

If your Notion database is not within a workspace, or if it simply doesn’t match the URL shown above, it probably looks like this: https://www.notion.so/{database_id}?v={view_id}.

Sending WhatsApp Notifications

Sending reminders is the main objective of this tutorial. For sending reminders, you can use the Twilio WhatsApp API to perform this task.

To do so, first, log in to your Twilio account and visit the Twilio console. On the console, look out for the Account Info section and obtain the Account SID and Auth Token.

Next, activate your Twilio Sandbox to send and receive WhatsApp messages.

Next, add the Account SID and Auth Token as environment variables to your .env file:

Next, update the main.py by adding the twilio library at top of the file and and the send_reminder function before the main function:

In the above code, you define the send_reminder function that takes client as input. It uses Twilio Python SDK (Client) to send a WhatsApp message from a Twilio Sandbox phone number to the client’s phone number to_whatsapp_number. The body of the message contains the client’s name, pending amount, and the due date.

Finally, execute the Python application by running the following command in your terminal:

If there are any empty rows or fields in your Notion database, the application might throw an index error. Otherwise, if there are any clients with due dates, then the application will send some WhatsApp notifications:

Automating Sending Reminders

The final step is to automate the process of running the Python code on a regular basis to keep checking for new due dates. There are a lot of ways which you can automate the script execution, for example - host your script on Heroku and use Heroku Scheduler, use Crontab on a self-hosted machine, or use Github Actions. For this tutorial, you will use Github Actions.

To do so, first, create a directory path .github/workflows in your project’s root directory. In .github/workflows, add a main.yml file and add the following code to it:

The above Github Action is scheduled to run every day at 00:00 UTC as specified by the line cron: "0 0 * * *". Depending upon your requirement, you can change the frequency at which the code runs. With workflow dispatch, you can run the action manually whenever you want.

Next, create a requirements.txt file to list all of the dependencies used by your Python application by running the following command in your terminal:

Next, create a new Github repository. Go to Settings > Secrets > Actions.

Next, add the following secrets and their respective values as repository secrets:

Next, initialize a Git repository in your local project by running the following command in your terminal:

Next, create a .gitignore file in your project’s root directory and add the following files and directories to it to prevent them from being pushed to the upstream repository:

Finally, commit and push the changes to your upstream repository by running the following commands in your terminal:

Testing

To verify all of your work till now, visit the Actions tab and run the workflow manually.

Wait for the workflow to complete and check for any notifications on your WhatsApp:

And with that, you have successfully implemented the payment reminders for your clients.

Conclusion

Congratulations! In this tutorial, you learned to send payment reminders using Twilio, Notion, and Python. You used Notion to store the client’s data, Python for logic, Twilio for WhatsApp notifications, and GitHub Actions for automation.

Let me know if this project helped you or just say Hi! by reaching out to me over email! The entire code for this repository is available in this GitHub repository.

Ravgeet is a remote, full-time, full-stack developer and technical content writer based in India. He works with and writes about React, Vue, Flutter, Strapi, Python, and Automation. He can be reached via email ravgeetdhillon[at]gmail.com, LinkedIn, and Github.