Getting Started with SMS Notifications using Africas Talking and GitHub Actions🐙
Tags: tutorial, githubactions, devops, opensource
Published: 2023-09-11 12:37:49


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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xrf9ciqpz253glukdslb.png)

## 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](https://help.github.com/en/github/getting-started-with-github/create-a-repo). Once you have a repository, follow the steps below to get started.

- Get Africas Talking API keys 🔑:

1. Sign up on [AfricasTalking.com](https://africastalking.com/)
2. 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9t49hj51ar2p5n79ho9m.png)

- Add secrets to GitHub repository(We will use these secrets in our workflow):

1. In your repo, go to **Settings > Secrets > Actions**
2. Add a secret `AT_USERNAME` with your username.
3. Add a secret `AT_API_KEY` with your API key.
4. 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4l5cu3gnqklcyq087qtw.png)

## Methods of running code on GitHub Actions 🐙

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

1. create a new workflow.

2. 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:

```yaml
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.](https://developers.africastalking.com/sdks)

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

```yaml
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:

```yaml

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

```yaml

- 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w06d1zezwkd1fvmcccvl.png)

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

- [GitHub Actions](https://docs.github.com/en/actions)
- [Africas Talking](https://africastalking.com/)
- [Africas Talking SMS API](https://developers.africastalking.com/docs/sms)
- [Africas Talking SDKs](https://developers.africastalking.com/sdks)
- [Africas Talking GitHUb Actions](https://github.com/alphaolomi/actions-africastalking)

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.](https://twitter.com/KenMwaura1) or [LinkedIn](https://www.linkedin.com/in/kennedy-mwaura/) If you found this article helpful feel free to share it with others.

![Next time](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/diajdqtjfsq60kke6kcn.gif)