Skip to main content

​
Overview

This quickstart guide will help you set up VoicePact and create your first voice-powered contract with automated escrow in under 10 minutes.
What you’ll build: A complete contract workflow from voice recording to SMS confirmation to escrow setup.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.11+ installed
  • Node.js 18+ installed
  • Redis server running
  • An Africa’s Talking Sandbox account
  • ngrok installed (for webhook tunneling)

​
Step 1: Clone and Setup Backend

1

Clone the repository

git clone https://github.com/mutuiris/voicepact.git
cd voicepact
2

Navigate to server directory

cd server
3

Create and activate virtual environment

python -m venv venv
source venv/bin/activate
4

Install dependencies

pip install -r requirements.txt
This installs all required packages including:
  • fastapi - Async web framework
  • africastalking - Africa’s Talking SDK
  • sqlalchemy - Database ORM
  • redis - Caching and sessions
  • cryptography - Ed25519 signatures
5

Configure environment variables

Create a .env file in the server directory:
.env
# Africa's Talking Configuration
AT_USERNAME=sandbox
AT_API_KEY=your_api_key_here
AT_VOICE_NUMBER=+254XXXXXXXXX
AT_PAYMENT_PRODUCT_NAME=VoicePact
AT_USSD_SERVICE_CODE=*483#

# Database Configuration
DATABASE_URL=sqlite:///./voicepact.db
REDIS_URL=redis://localhost:6379/0

# Security Configuration
SECRET_KEY=your_secret_key_here
SIGNATURE_PRIVATE_KEY=your_ed25519_private_key_here

# Webhook Configuration
WEBHOOK_BASE_URL=https://your-ngrok-url.ngrok.io

# Application Settings
ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=INFO
Replace your_api_key_here with your actual Africa’s Talking API key from the sandbox dashboard.

​
Step 2: Start Redis

Redis is required for caching and session management. 
brew services start redis

​
Step 3: Setup Webhook Tunnel

Africa’s Talking needs to send callbacks to your local server. Use ngrok to create a public URL:
1

Start ngrok tunnel

ngrok http 8000
2

Copy the HTTPS URL

ngrok will display a URL like https://abc123.ngrok.io. Copy this URL.
3

Update your .env file

Update the WEBHOOK_BASE_URL in your .env file:
WEBHOOK_BASE_URL=https://abc123.ngrok.io

​
Step 4: Start the Backend Server

1

Start the FastAPI server

From the server directory with your virtual environment activated:
uvicorn main:app --reload --port 8000
You should see output like:
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000
2

Verify the server is running

Open a new terminal and test the health endpoint:
curl http://localhost:8000/health
You should receive a response with status "healthy":
{
  "status": "healthy",
  "services": {
    "database": "healthy",
    "redis": "healthy"
  },
  "timestamp": 1234567890.123
}

​
Step 5: Create Your First Contract

Now let’s create a manual contract to test the system:
1

Create a test contract using the API

curl -X POST http://localhost:8000/api/v1/contracts/create/manual \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Maize (White)",
    "quantity": "50",
    "unit": "bags",
    "unit_price": 3500,
    "total_amount": 175000,
    "currency": "KES",
    "delivery_location": "Nairobi Market",
    "delivery_deadline": "2026-03-15",
    "quality_requirements": "Grade A, moisture content < 13%",
    "parties": [
      {
        "phone": "+254712345678",
        "role": "seller",
        "name": "John Kamau"
      },
      {
        "phone": "+254798765432",
        "role": "buyer",
        "name": "Jane Wanjiku"
      }
    ],
    "contract_type": "agricultural_supply"
  }'
2

View the contract response

You’ll receive a response containing your contract details:
{
  "contract_id": "VP-AGR-1234567890",
  "status": "pending",
  "created_at": "2026-03-06T10:30:00",
  "total_amount": 175000.0,
  "currency": "KES",
  "parties": [
    {
      "phone_number": "+254712345678",
      "role": "seller",
      "name": "John Kamau"
    },
    {
      "phone_number": "+254798765432",
      "role": "buyer",
      "name": "Jane Wanjiku"
    }
  ],
  "contract_hash": "blake2b_hash_here"
}
SMS confirmation messages are automatically sent to both parties in the background.
3

Check contract status

Query the contract status to see signature progress:
curl http://localhost:8000/api/v1/contracts/VP-AGR-1234567890/status
Response:
{
  "contract_id": "VP-AGR-1234567890",
  "status": "pending",
  "signatures": [
    {
      "phone_number": "+254712345678",
      "status": "pending",
      "signed_at": null
    },
    {
      "phone_number": "+254798765432",
      "status": "pending",
      "signed_at": null
    }
  ],
  "progress": {
    "signed": 0,
    "total": 2,
    "complete": false
  }
}
4

Simulate party confirmation

In a real scenario, parties would reply to the SMS. For testing, confirm manually:
curl -X POST "http://localhost:8000/api/v1/contracts/VP-AGR-1234567890/confirm?phone_number=%2B254712345678"
Repeat for the second party:
curl -X POST "http://localhost:8000/api/v1/contracts/VP-AGR-1234567890/confirm?phone_number=%2B254798765432"
After both parties confirm, the contract status changes to "confirmed".

​
Step 6: Setup the Client Dashboard (Optional)

The Next.js client provides a web interface for managing contracts.
1

Navigate to client directory

cd ../client
2

Install dependencies

npm install
3

Configure environment

Create .env.local in the client directory:
.env.local
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_WEBSOCKET_BASE=ws://localhost:8000
NEXT_PUBLIC_FEATURE_LOW_DATA_MODE=true
NEXT_PUBLIC_FEATURE_ESCROW_TIMELINE=true
NEXT_PUBLIC_FEATURE_ROLE_AWARE_DASHBOARD=false
4

Start the development server

npm run dev
Visit http://localhost:3000 to see the dashboard.

​
Next Steps

Installation Guide

Complete installation and configuration reference

API Reference

Explore all available API endpoints

Voice Processing

Learn about voice-to-contract workflows

Escrow Integration

Understand automated payment escrow

​
Troubleshooting

Ensure Redis is running:
redis-cli ping
Should return PONG. If not, start Redis using the instructions in Step 2.
  • Verify your API key is correct in the .env file
  • Check you’re using the correct username (sandbox for sandbox mode)
  • Ensure your ngrok URL is updated in WEBHOOK_BASE_URL
The database is automatically created on first run. If you encounter issues:
rm voicepact.db  # Remove old database
# Restart the server - it will create a fresh database
In sandbox mode, SMS only works with numbers registered in your Africa’s Talking sandbox. Add test numbers in the sandbox settings.

​
What You’ve Learned

You’ve successfully:
  • ✅ Set up the VoicePact backend with FastAPI
  • ✅ Configured Africa’s Talking integration
  • ✅ Created your first contract via API
  • ✅ Tested the SMS confirmation workflow
  • ✅ (Optional) Set up the web dashboard
You’re now ready to explore advanced features like voice processing, automated escrow, and USSD integration!

Build docs developers (and LLMs) love

Get started for freeTalk to us