Skip to main content

​
Overview

This guide walks you through setting up your development environment for the Africa’s Talking AI Integration Course. Proper environment configuration is crucial for secure API key management and smooth development workflow.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.8 or higher installed
  • An Africa’s Talking account with API credentials
  • A Google Cloud account for AI services (Gemini/Vertex AI)
  • A text editor or IDE for editing configuration files

​
Creating the .env File

1

Navigate to Project Root

Open your terminal and navigate to the project root directory:
cd Google-Africastalking-AI-Course
2

Create .env File

Create a new .env file in the root directory:
touch .env
The .env file should never be committed to version control. Ensure it’s listed in your .gitignore file.
3

Add Required Environment Variables

Open the .env file in your text editor and add the following variables:
# Flask Configuration
FLASK_ENV=development
PORT=9000

# Ngrok Configuration (for tunneling)
NGROK_AUTHTOKEN=your-ngrok-auth-token-here

# Africa's Talking API Credentials
AT_USERNAME=your-AT-username-here
AT_API_KEY=your-AT-api-key-here
AT_VOICE_NUMBER=your-voice-enabled-phone-number
AT_SHORTCODE=8995

# Google Cloud AI Configuration
PROJECT_ID=your-gcp-project-id
GEMINI_API_KEY=your-gemini-api-key
VERTEX_API_KEY=your-vertex-api-key

​
Environment Variables Explained

​
Flask Configuration

VariablePurposeExample ValueRequired
FLASK_ENVSets the Flask environment modedevelopment or productionYes
PORTPort number for the Flask server9000 (default: 5000)No
Use development mode during development for automatic reloading and detailed error messages. Switch to production for deployment.

​
Tunneling Configuration

VariablePurposeExample ValueRequired
NGROK_AUTHTOKENAuthentication token for ngrok2abc...xyzYes (if using ngrok)
You’ll need this to expose your local server to the internet for receiving webhooks from Africa’s Talking.

​
Africa’s Talking Credentials

VariablePurposeExample ValueRequired
AT_USERNAMEYour Africa’s Talking usernamesandbox or your app nameYes
AT_API_KEYYour Africa’s Talking API keyatsk_abc123...Yes
AT_VOICE_NUMBERYour voice-enabled phone number+254711000000For Voice API
AT_SHORTCODEYour SMS shortcode8995For two-way SMS
Never share your API keys publicly! These credentials grant access to your Africa’s Talking account and can incur charges.

​
Getting Africa’s Talking Credentials

1

Create an Account

Visit Africa’s Talking and sign up for an account.
2

Create a Team and App

  • After logging in, create a new team
  • Inside the team, create a new app
  • Choose whether to use the sandbox (for testing) or production
3

Get API Credentials

  • Navigate to your app settings
  • Find your Username (usually “sandbox” for sandbox apps)
  • Generate or copy your API Key
  • Store these securely in your .env file
4

Request Product Access

For production use, request access to the services you need:
  • SMS
  • Voice (includes a voice-enabled phone number)
  • Airtime
  • USSD

​
Google Cloud AI Configuration

VariablePurposeExample ValueRequired
PROJECT_IDYour Google Cloud project IDmy-project-123For Vertex AI
GEMINI_API_KEYAPI key for Gemini AIAIza...For Gemini API
VERTEX_API_KEYAPI key for Vertex AIAIza...For Vertex AI

​
Getting Google Cloud Credentials

1

Create Google Cloud Account

Visit Google Cloud Console and create an account if you don’t have one.
2

Get Gemini API Key

  • Go to Google AI Studio
  • Create a new API key
  • Copy the key to your .env file as GEMINI_API_KEY
3

Set Up Vertex AI (Optional)

  • Create a new project in Google Cloud Console
  • Enable the Vertex AI API
  • Note your project ID and add it to PROJECT_ID

​
Environment Best Practices

​
Security Guidelines

Critical Security Practices:
  • Never commit .env files to Git
  • Don’t share API keys in chat, email, or screenshots
  • Rotate API keys regularly
  • Use different credentials for development and production
  • Restrict API key permissions to only what’s needed

​
File Permissions

On Unix-based systems (Linux/macOS), restrict access to your .env file: 
chmod 600 .env
This ensures only you can read and write the file.

​
Using .env.example

Create a .env.example file to document required variables without exposing secrets: 
# .env.example
FLASK_ENV=development
PORT=9000
NGROK_AUTHTOKEN=your-ngrok-auth-token-here
AT_USERNAME=your-AT-username-here
AT_API_KEY=your-AT-api-key-here
AT_VOICE_NUMBER=your-voice-enabled-phone-number
AT_SHORTCODE=8995
PROJECT_ID=your-gcp-project-id
GEMINI_API_KEY=your-gemini-api-key
VERTEX_API_KEY=your-vertex-api-key
Commit .env.example to your repository as a template for other developers. They can copy it to .env and add their own credentials.

​
Verifying Environment Variables

You can verify your environment variables are loaded correctly: 
import os
from dotenv import load_dotenv

load_dotenv()

print(f"AT_USERNAME: {os.getenv('AT_USERNAME')}")
print(f"PORT: {os.getenv('PORT')}")
print(f"FLASK_ENV: {os.getenv('FLASK_ENV')}")
The project uses python-dotenv to automatically load environment variables from the .env file when the Flask app starts.

​
Environment-Specific Configuration

​
Development Environment

FLASK_ENV=development
PORT=9000
AT_USERNAME=sandbox
AT_API_KEY=your-sandbox-api-key
Characteristics:
  • Uses sandbox credentials
  • Debug mode enabled
  • Detailed error messages
  • Auto-reload on code changes

​
Production Environment

FLASK_ENV=production
PORT=5000
AT_USERNAME=your-production-username
AT_API_KEY=your-production-api-key
Characteristics:
  • Uses production credentials
  • Debug mode disabled
  • Minimal logging
  • Optimized for performance
Always test thoroughly in the sandbox environment before deploying to production. Production API calls incur real charges.

​
Troubleshooting

​
Environment Variables Not Loading

Problem: Your application can’t find environment variables. Solutions:
  1. Verify the .env file is in the project root directory
  2. Check that dotenv is installed: pip install python-dotenv
  3. Ensure load_dotenv() is called before accessing variables
  4. Check for typos in variable names

​
API Authentication Failures

Problem: Getting authentication errors from Africa’s Talking or Google Cloud. Solutions:
  1. Verify your API keys are correct (no extra spaces)
  2. Check if you’re using sandbox vs. production credentials correctly
  3. Ensure API keys haven’t expired or been revoked
  4. Verify you have access to the requested services

​
Port Already in Use

Problem: Error message: “Address already in use” Solutions:
  1. Change the PORT variable in .env to an unused port
  2. Stop any other applications using the same port
  3. On Unix systems, find and kill the process: 
    lsof -ti:9000 | xargs kill -9

​
Next Steps

Now that your environment is configured:
  1. Set up tunneling to expose your local server
  2. Configure webhooks in the Africa’s Talking dashboard
  3. Test your endpoints to ensure everything works

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us