Getting Started with SMS Notifications using Africas Talking and GitHub Actions Part 2
Tags: tutorial, githubactions, devops, automation
Published: 2023-09-16 13:16:09

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](https://dev.to/ken_mwaura1/getting-started-with-sms-notifications-using-africas-talking-and-github-actions-5de0) 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:

![Workflow diagram](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xrf9ciqpz253glukdslb.png)

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

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

```yaml

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. 

```yaml

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:

```yaml

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](https://dev.to/ken_mwaura1/getting-started-with-sms-notifications-using-africas-talking-and-github-actions-5de0) 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:

```yaml

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.

Read more about the variables [here](https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context).

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

```yaml

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:

```yaml

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

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

## 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.](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. 

Buy me a coffee [here](https://www.buymeacoffee.com/kenmwaura1).

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