Getting Started with SMS Notifications using Africas Talking and GitHub Actions Part 2

This is the follow-up article in a series 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 an 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 an 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:

Workflow diagram

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.

Settings page

Add secrets to the 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:

Secrets dashboard

Scenario 1: Using the Python SDK inside an existing workflow

In this scenario, we will be using the Africas Talking Python SDK inside an 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 an additional step inside an existing workflow to send the SMS notification. Below is an example workflow that tests our code against different Python versions. We will do 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 let's 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 the 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 AfricasTalking Github action inside a new workflow

We are now switching gears and using the AfricasTalking 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 the 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 called send_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 the fromPhoneNumber, toPhoneNumber and message variables.
env is the environment variables that will be used by the action. In this case, we are passing the AT_API_KEY and AT_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.

Scenario 4: Using the AfricasTalking Github action inside an existing workflow

Here the approach is similar to scenario 3. The only difference is that we are using an existing workflow. This refers to adding the action as a step to an existing workflow.

Let's 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 phone 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 the 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.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 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! Feel 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.

Next time