Skip to main content

​
Overview

VoicePact’s voice contract feature transforms spoken agreements into legally binding contracts. Users can have a natural conversation about their agreement, and the system automatically transcribes the audio, extracts contract terms, and generates a formal contract document.

Voice Conference

Create multi-party voice calls where all participants negotiate terms verbally

Auto Transcription

AI-powered speech-to-text converts the entire conversation into written transcript

Term Extraction

Intelligent parsing identifies key contract terms like price, quantity, and delivery

Audio Upload

Upload pre-recorded audio files for processing into contracts

​
How It Works

1

Initiate Voice Conference

Start a voice call with all contract parties. The system supports multiple participants and automatically records the conversation.
POST /api/v1/voice/conference/create
2

Negotiate Terms

Parties discuss the agreement naturally. Mention key details like:
  • Product or service being exchanged
  • Quantity and units
  • Price and payment terms
  • Delivery location and deadline
  • Quality requirements
3

Process Recording

After the call, the system processes the audio to extract a transcript and identify contract terms.
POST /api/v1/voice/process
4

Review & Sign

All parties receive the generated contract via SMS for review and digital signature.

​
Creating a Voice Conference

To create a voice conference between contract parties: 
import httpx

response = httpx.post(
    "https://api.voicepact.com/api/v1/voice/conference/create",
    json={
        "parties": [
            "+254712345678",  # Buyer
            "+254723456789"   # Seller
        ],
        "contract_type": "agricultural_supply",
        "expected_duration": 600  # 10 minutes
    }
)

conference = response.json()
print(f"Conference ID: {conference['conference_id']}")
print(f"Recording URL: {conference['recording_url']}")
print(f"Status: {conference['status']}")

​
Response Format

{
  "conference_id": "conf_abc123xyz",
  "recording_url": "https://recordings.africastalking.com/...",
  "status": "active",
  "webhook_url": "/api/v1/voice/webhook",
  "parties": ["+254712345678", "+254723456789"]
}

​
Processing Voice Recordings

Once a recording is available, process it to generate the contract: 
response = httpx.post(
    "https://api.voicepact.com/api/v1/voice/process",
    json={
        "audio_url": "https://recordings.africastalking.com/rec_123.mp3",
        "parties": [
            {
                "phone": "+254712345678",
                "role": "buyer",
                "name": "John Kamau"
            },
            {
                "phone": "+254723456789",
                "role": "seller",
                "name": "Mary Wanjiku"
            }
        ],
        "contract_type": "agricultural_supply"
    }
)

contract = response.json()
print(f"Contract ID: {contract['contract_id']}")
print(f"Confidence: {contract['confidence_score']}")
print(f"\nTranscript:\n{contract['transcript']}")
print(f"\nTerms:\n{contract['terms']}")

​
Processing Response

{
  "contract_id": "AG-2024-001234",
  "transcript": "John: I need 100 bags of maize. Mary: I can supply 100 bags at 3500 shillings per bag...",
  "terms": {
    "product": "Maize",
    "quantity": 100,
    "unit": "bags",
    "unit_price": 3500,
    "total_amount": 350000,
    "currency": "KES",
    "delivery_location": "Nakuru Market",
    "delivery_deadline": "2024-03-15",
    "quality_requirements": "Grade A, moisture content below 13%"
  },
  "contract_hash": "a7f5c3d8e9...",
  "contract_summary": "Supply of 100 bags of Maize for KES 350,000",
  "processing_status": "completed",
  "confidence_score": 0.92,
  "created_at": "2024-03-06T10:30:00Z"
}

​
Uploading Audio Files

You can also upload pre-recorded audio files: 
with open("contract_negotiation.mp3", "rb") as audio_file:
    files = {"file": audio_file}
    data = {
        "contract_type": "agricultural_supply"
    }
    
    response = httpx.post(
        "https://api.voicepact.com/api/v1/voice/upload",
        files=files,
        data=data
    )

result = response.json()
print(f"Transcript: {result['transcript']}")
print(f"Terms: {result['terms']}")
print(f"Confidence: {result['confidence_score']}")

​
Supported Audio Formats

  • WAV (.wav)
  • MP3 (.mp3)
  • M4A (.m4a)
  • OGG (.ogg)

​
Checking Recording Status

Monitor the processing status of a voice recording: 
recording_id = "conf_abc123xyz"
response = httpx.get(
    f"https://api.voicepact.com/api/v1/voice/recordings/{recording_id}"
)

status = response.json()
print(f"Status: {status['status']}")
print(f"Duration: {status['duration']} seconds")
print(f"Recording URL: {status['recording_url']}")

​
Webhook Integration

VoicePact automatically receives webhook notifications when recordings are ready: 
# Webhook payload received at /api/v1/voice/webhook
{
  "sessionId": "conf_abc123xyz",
  "phoneNumber": "+254712345678",
  "recordingUrl": "https://recordings.africastalking.com/rec_123.mp3",
  "duration": 425,
  "status": "completed"
}
The system automatically updates the recording status and triggers contract generation when all recordings are complete. See voice.py:224 for webhook handler implementation.

​
Contract Confirmation Flow

After processing, each party receives an SMS notification: 
VoicePact Contract Created:
Supply of 100 bags of Maize for KES 350,000
Delivery: Nakuru Market by 2024-03-15

Reply YES-AG-2024-001234 to confirm
Parties can confirm by:
  1. SMS Reply: Send “YES-” to confirm
  2. USSD Menu: Dial the service code and select the contract
  3. API Call: Use the signatures endpoint

​
Confidence Scoring

The voice processing system provides confidence scores for transcription accuracy:
  • 0.9 - 1.0: High confidence - terms clearly stated
  • 0.7 - 0.9: Medium confidence - some ambiguity
  • Below 0.7: Low confidence - manual review recommended
Low confidence contracts are flagged for human review before parties are asked to sign.

​
Best Practices

Speak clearly and state key terms explicitly. For example:
  • “The price is three thousand five hundred shillings per bag”
  • “Delivery deadline is March fifteenth”
  • “Quality must be Grade A with moisture below thirteen percent”
Ensure good call quality:
  • Use a quiet environment
  • Avoid background noise
  • Check network signal strength
  • Allow 2-3 seconds between statements
Follow a logical flow:
  1. Identify parties and their roles
  2. State the product/service
  3. Agree on quantity and price
  4. Confirm delivery terms
  5. Discuss quality requirements
  6. Agree on payment terms
Always review the generated contract:
  • Check extracted terms match what was discussed
  • Verify amounts and dates are correct
  • Confirm delivery locations are accurate
  • Request corrections if needed

​
Error Handling

Common errors and how to handle them: 
try:
    response = httpx.post("/api/v1/voice/process", json=payload)
    response.raise_for_status()
except httpx.HTTPStatusError as e:
    if e.response.status_code == 400:
        # Bad request - check audio_url or parties format
        print(f"Invalid request: {e.response.json()['detail']}")
    elif e.response.status_code == 500:
        # Processing failed - check audio quality or try again
        print("Processing failed, please retry")

​
Technical Implementation

The voice contract system integrates:
  • Africa’s Talking Voice API: Multi-party calling and recording
  • Speech Recognition: Audio transcription engine
  • NLP Engine: Contract term extraction from transcript
  • Contract Generator: Structured contract document creation
See the implementation:

​
Next Steps

SMS Verification

Learn how parties confirm contracts via SMS

Digital Signatures

Understand the cryptographic signature system

USSD Integration

Access contracts via USSD menu

Mobile Money

Integrate escrow payments

Build docs developers (and LLMs) love

Get started for freeTalk to us