This is the follow-up article in a series about about SMS notifications using Africas Talking and GitHub Actions.
Please find the first entry here detailing how to get started with Africas Talking and GitHub Actions.
Introduction
In this article we'll dig deeper into the GitHub Actions workflow and how to use the Africas Talking API to send SMS notifications. We'll also explore different scenarios and implement them in our workflow(s).
These scenarios include:
- Using the Python SDK (feel free to substitute with your preferred language) inside a existing workflow.
- Using the Python SDK (feel free to substitute with your preferred language) inside a new workflow.
- Using the AfricasTalking Github action inside a new workflow.
- Using the AfricasTalking Github action inside a existing workflow.
- Sending an SMS notification to multiple recipients.
Prerequisites
- A GitHub account with a repository (Alternatively create a new repo).
- An Africas Talking account and API keys.
The diagram below shows a high-level overview of the workflow(s) we will be creating:
Getting Started 🤩
Steps 🚶
The steps below assume you have a GitHub account and a repository. If you don’t have a repository, you can create one by following the steps here. Once you have a repository, follow the steps below to get started.
- Get Africas Talking API keys 🔑:
- Sign up on AfricasTalking.com
- Get your username and API key from the SMS dashboard. Note you will be prompted for your password. Once the key is created and displayed copy and paste it elsewhere as they usually create a new one each time.
- Add secrets to GitHub repository(We will use these secrets in our workflow):
- In your repo, go to Settings > Secrets > Actions
- Add a secret
AT_USERNAME
with your username. - Add a secret
AT_API_KEY
with your API key. - Add a secret
toPhoneNumber
with the phone number you want to send the SMS to. (Format: +2547XXXXXXXX)
Once you have added the secrets, your secrets page should look like this:
Scenario 1: Using the Python SDK inside a existing workflow
In this scenario we will be using the Africas Talking Python SDK inside a existing workflow. We will be using the Africas Talking python SDK to send an SMS notification to a phone number of your choice.
Here we'll create a additional step inside a existing workflow to send the SMS notification. Below is an example workflow that tests our code against different python versions. We will add a step to send the SMS notification after the tests have passed.
name: Python package
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [ 3.8, 3.9, "3.10"]
steps:
- uses: actions/checkout@v2
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install flake8 pytest
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
- name: Test with pytest
run: |
pytest .
Now lets add a step to send the SMS notification after the tests have passed. We will be using the Africas Talking python SDK to send the SMS notification.
name: Python package
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [ 3.8, 3.9, "3.10"]
steps:
- uses: actions/checkout@v2
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install flake8 pytest
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
- name: Test with pytest
run: |
pytest .
- name: Install Africa's Talking SDK
run: pip install africastalking
- name: Send SMS notification
if : github.event_name != 'pull_request'
env:
TO: ${{ secrets.toPhoneNumber }}
run: |
from africastalking.SMS import SMS
sms = SMS(username=${{ secrets.AT_USERNAME }}, api_key=${{ secrets.AT_API_KEY }})
response = sms.send(message="GitHub workflow completed!", recipients=[TO])
Scenario 2: Using the Python SDK inside a new workflow
In this scenario we will be using the Africas Talking python SDK inside a new workflow. We will be using the Africas Talking python SDK to send an SMS notification to a phone number of your choice.
NOTE: The general steps outlined should be similar to other languages. Feel free to substitute with your preferred language.
- Create a new workflow:
If you are on the GitHub website, navigate to your repository and click on the Actions tab. Then click on New workflow. This will open a new page with a list of workflow templates. Select Python package. This will open a new page with the workflow code.
If you are working in your IDE e.g. VSCode, navigate to the .github/workflows directory. Create a new file and name it
send_sms.yml
. Add the following code:
name: Send SMS Notification
on: [push]
jobs:
send_sms:
runs-on: ubuntu-latest
steps:
- name: Install Africa's Talking SDK
run: pip install africastalking
- name: Send SMS notification
env:
TO: ${{ secrets.toPhoneNumber }}
AT_USERNAME: ${{ secrets.AT_USERNAME }}
AT_API_KEY: ${{ secrets.AT_API_KEY }}
run: |
from africastalking.SMS import SMS
sms = SMS(username=${{ AT_USERNAME }}, api_key=${{ AT_API_KEY }})
response = sms.send(message="GitHub workflow completed!", recipients=[TO])
The code above is similar to the code we used in the first scenario. The only difference is that we are using a new workflow.
Scenario 3: Using the Africas Talking Github action inside a new workflow
We are now switching gears and using the Africas Talking github action inside a new workflow. This isn't new especially if you read part one of this series. Feel free to skip this section if you are already familiar with this approach.
- Create a new workflow:
If you are on the GitHub website, navigate to your repository and click on the Actions tab. Then click on New workflow. This will open a new page with a list of workflow templates. Select Python package. This will open a new page with the workflow code.
If you are working in your IDE e.g. VSCode, navigate to the .github/workflows directory. Create a new file and name it
send_sms.yml
. Add the following code:
name: Send SMS Notification
on: [push]
jobs:
send_sms:
runs-on: ubuntu-latest
steps:
- name: Send SMS notification
- name: SMS Notification
uses: alphaolomi/actions-africastalking@main
with:
fromPhoneNumber: 'INFO' # or ${{ secrets.fromPhoneNumber }}
toPhoneNumber: ${{ secrets.toPhoneNumber }}
message: ${{ github.event_name }} on ${{ github.repository }} by ${{ github.actor }} has ${{github.event.workflow_run.conclusion}}. Check it out at ${{ github.event.workflow_run.url }}
env:
AT_API_KEY: ${{ secrets.AT_API_KEY }}
AT_USERNAME: ${{ secrets.AT_USERNAME }}
Lets break down the code above:
-
name
is the name of the workflow. You can name it anything you want. -
on
is the event that triggers the workflow. In this case, we want the workflow to be triggered when code is pushed to the main branch. -
jobs
is a collection of steps that run sequentially. In this case, we have one job calledsend_sms
. -
runs-on
is the type of machine the job runs on. In this case, we are using the latest version of Ubuntu. -
steps
is a collection of tasks that will be executed as part of the job. In this case, we have two steps. -
name
is the name of the step. You can name it anything you want. -
uses
is the action that will be used by the step. In this case, we are using the AfricasTalking Github action. -
with
is the input variables that will be used by the action. In this case, we are passing thefromPhoneNumber
,toPhoneNumber
andmessage
variables. -
env
is the environment variables that will be used by the action. In this case, we are passing theAT_API_KEY
andAT_USERNAME
variables.
Inside the message variable we are using the following variables:
-
${{ github.event_name }}
- The name of the webhook event that triggered the workflow. -
${{ github.repository }}
- The owner and repository name. -
${{ github.actor }}
- The name of the person or app that initiated the workflow. -
${{github.event.workflow_run.conclusion}}
- The conclusion of the workflow run. -
${{ github.event.workflow_run.url }}
- The URL of the workflow run.
Read more about the variables here.
Scenario 4: Using the Africas Talking Github action inside a existing workflow
Here the approach is similar to scenario 3. The only difference is that we are using a existing workflow. This refers to adding the action as a step to an existing workflow.
Lets add the action as a step to the workflow we created in scenario 1.
name: Python package
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [ 3.8, 3.9, "3.10"]
steps:
- uses: actions/checkout@v2
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install flake8 pytest
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
- name: Test with pytest
run: |
pytest .
- name: SMS Notification
uses: alphaolomi/actions-africastalking@main
with:
fromPhoneNumber: 'INFO' # or ${{ secrets.fromPhoneNumber }}
toPhoneNumber: TO
message: ${{ github.event_name }} on ${{ github.repository }} by ${{ github.actor }} has ${{github.event.workflow_run.conclusion}}. Check it out at ${{ github.event.workflow_run.url }}
env:
AT_API_KEY: ${{ secrets.AT_API_KEY }}
AT_USERNAME: ${{ secrets.AT_USERNAME }}
TO: ${{ secrets.toPhoneNumber }}
Scenario 5: Sending an SMS notification to multiple recipients
In this scenario we will be sending a notification to multiple recipients. We will be using the Africas Talking Python SDK to send an SMS notification to multiple phone numbers of your choice. This is useful if you want to send a notification to multiple people.
NOTE: The general steps outlined should be similar to other languages. Feel free to substitute with your preferred language.
First add the req phone numbers to the toPhoneNumbers
secret. The phouiredne numbers should be separated by a comma. The format should be as follows: +2547XXXXXXXX,+2547XXXXXXXX,+2547XXXXXXXX etc.
This prevents you from having to change the code each time you want to send a notification to multiple recipients. As well keeping the numbers prevents exposing them in the code.
- Create a new workflow:
- If you are on the GitHub website, navigate to your repository and click on the Actions tab. Then click on New workflow. This will open a new page with a list of workflow templates. Select Python package. This will open a new page with the workflow code.
- If you are working in your IDE eg VSCode, navigate to the .github/workflows directory. Create a new file and name it
send_sms.yml
. Add the following code:
name: Send SMS Notification
on: [push]
jobs:
send_sms:
runs-on: ubuntu-latest
steps:
- name: Install Africa's Talking SDK
run: pip install africastalking
- name: Send SMS notification
env:
TO: ${{ secrets.toPhoneNumbers }}
AT_USERNAME: ${{ secrets.AT_USERNAME }}
AT_API_KEY: ${{ secrets.AT_API_KEY }}
run: |
from africastalking.SMS import SMS
sms = SMS(username=${{ AT_USERNAME }}, api_key=${{ AT_API_KEY }})
for number in TO.split(','):
response = sms.send(message="GitHub workflow completed!", recipients=[number])
Here the code is similar to the code we used in scenario 2. The only difference is that we are using a for loop to send the SMS notification to multiple recipients. You could use a a csv file to store the phone numbers and read them in the code. Feel free to experiment with different approaches.
Conclusion
In this article we explored different scenarios and implemented them in our workflow(s). We also explored how to use the Africas Talking API to send SMS notifications. Feel free to experiment with different approaches and let me know how it goes.
Resources
Next Steps
In the next article we'll go through how to implement error/failure notification from specified workflows using Africas Talking and GitHub Actions.
Thanks for reading! Free free to leave a comment below if you have any questions, suggestions or clarifications. You can also reach out to me on Twitter. or LinkedIn If you found this article helpful feel free to share it with others.
Buy me a coffee here.
Top comments (0)