SMS Notifications using Africas Talking and GitHub Actions

New month, New Tutorial 🚀. In the next few weeks, I will be writing a series of tutorials on how to send SMS notifications using Africas Talking and GitHub Actions. This is the first tutorial in the series.

Introduction 💫

GitHub Actions allows you to create workflows that automate your CI/CD process. Africas Talking provides a simple and reliable API to send SMS notifications to your users.

This tutorial I will show you how to send SMS notifications using Africas Talking and GitHub Actions. We will be using the Africas Talking SMS API to send SMS notifications to a phone number of your choice. We will be using GitHub Actions to automate the process of sending the SMS notifications.

The diagram below shows a highlevel overview of the workflow we will be creating:

Workflow diagram

Benefits 🦸

Get real-time SMS alerts for workflow results.
No need to constantly check GitHub for status.
SMS is more convenient compared to email notifications.

Prerequisites

A GitHub account with a repository (Alternatively create a new repo).
An Africas Talking account and API keys.

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

Methods of running code on GitHub Actions 🐙

There are two ways to we can accomplish running our code on GitHub Actions. We can either:

create a new workflow.
use an existing workflow and add the code as a step.

Lets explore both methods.

Method 1: Create a new workflow

Create a new workflow:
If you are using the GitHub website:
In your repo, go to Actions > New Workflow
Select Set up a workflow yourself
Name your workflow

If you are working in your IDE eg VSCode
In your GitHub repository, create a .github/workflows directory if it doesn't already exist.
Inside the .github/workflows directory, create a YAML file (e.g., sms-notification.yml) to define your GitHub Actions workflow.
Add the following code:

name: Send SMS Notification
on: [push]
branches: [main]
jobs:
  send_sms:
 runs-on: ubuntu-latest
 steps:
   - name: Send 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 one step called Send SMS Notification.
uses is the action that will be executed. In this case, we are using the alphaolomi/actions-africastalking action.
with is the input parameters for the action. In this case, we are passing the fromPhoneNumber, toPhoneNumber and message parameters.
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.
secrets is the GitHub secrets that will be used by the action. In this case, we are passing the toPhoneNumber, AT_API_KEY and AT_USERNAME secrets.
Commit the changes and push to GitHub. This should trigger the workflow.

There is however a different way to add the code for sending the text. This involves using the Africas Talking SDKs. The SDKs are available in different languages including: Python, Node, PHP etc. You can find the SDKs here.

Now lets look at an example using the Python SDK 🐍:

name: Send SMS Notification
on: [push]
branches: [main]
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 }}
  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])

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.
run is the code that will be executed as part of the step. In this case, we are installing the Africas Talking SDK.
env is the environment variables that will be used by the action. In this case, we are passing the TO variable.
run is the code that will be executed as part of the step. In this case, we are using the Africas Talking SDK to send the SMS notification.

This approach allows for more flexibility and customization as needed.

Method 2: Use an existing workflow:

This method involves adding the code to an existing workflow. This is useful if you want to add the SMS notification to an existing workflow.

If you are using the GitHub website:

In your repo, go to Actions > Workflows
Select the workflow you want to add the code to.
Click on Edit.

If you are working in your IDE eg VSCode
In your GitHub repository, go to the .github/workflows directory.
Open the YAML file of the workflow you want to add the code to.
Add the following code:


- name: Send 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 }}

Commit the changes and push to GitHub. This should trigger the workflow.

Now lets look at an example using the Python SDK:


- name: Send SMS Notification
  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])

Commit the changes and push to GitHub. This should trigger the workflow.

If everything went successful you should a successful run as seen below:

Workflows

Conclusion🚧

In this tutorial, we have seen how to send SMS notifications using Africas Talking and GitHub Actions. We have also seen two methods of running code on GitHub Actions. In the next tutorial, we will look at further customization of the code depennding on the use case and SMS notifications.

Resources

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.

Next time

Getting Started with SMS Notifications using Africas Talking and GitHub Actions

Table of contents