# Utility bill payment agent (API) (/docs/examples/utility-bill-payment)
> Build an outbound voice agent that handles utility bill payments, sends payment reminders, and manages customer interactions.
Build an outbound payment-reminder voice agent end to end with the
OmniDimension Python SDK. The agent verifies accounts, collects
payments, and runs bulk reminder campaigns from a CSV.
### Get your API key [#get-your-api-key]
Get an API key from the OmniDimension dashboard, in the API section.
### Create the payment assistant [#create-the-payment-assistant]
Start by creating your voice agent with payment-specific configuration.
```python
from omnidimension import Client
client = Client("your_api_key_here")
payment_agent = client.agent.create(
name="BillBot - Payment Assistant",
welcome_message="Hello! This is BillBot calling about your utility bill. How can I help you today?",
context_breakdown=[
{
"title": "Payment Options",
"body": """PAYMENT METHODS:
- Online: www.pay.com
- Phone: 1-800-PAY-BILL
- Auto-pay: Available for all accounts
- Card Fee: $2.95 per transaction
PAYMENT DEADLINES:
- Bills due: 21st of each month
- Late fee: $25 after 10 days
- Disconnection: 30 days past due"""
},
{
"title": "Account Information",
"body": "1. Verify account number 2. Check current balance 3. Confirm payment method 4. Process payment 5. Send confirmation"
},
{
"title": "Payment Policies",
"body": "We accept all major credit cards, bank transfers, and cash payments. Auto-pay customers receive a 2% discount. Payment plans available for qualifying accounts."
}
],
call_type="Outgoing",
voice={
"provider": "eleven_labs",
"voice_id": "EXAVITQu4vr4xnSDxMaL"
},
model={
"provider": "anthropic",
"model": "gpt-4o-mini",
"temperature": 0.4
}
)
agent_id = payment_agent["json"]["id"]
print(f"Payment agent created with ID: {agent_id}")
```
**Key components:**
* `welcome_message`: professional greeting for payment-related calls
* Payment options: comprehensive payment methods and deadlines
* Account information: step-by-step workflow for payment processing
* Payment policies: clear guidelines for payment options
* Voice configuration: professional, trustworthy voice
### Process bulk payment reminders [#process-bulk-payment-reminders]
Send payment reminders to multiple customers from a CSV file.
```python
import csv
import json
from datetime import datetime
def send_payment_reminders(customer_file):
"""Send payment reminders to customers from CSV file"""
with open(customer_file) as f:
reader = csv.DictReader(f)
for row in reader:
context = json.dumps({
"account": row["account"],
"name": row["name"],
"balance": row["balance"],
"due_date": row["due_date"]
})
response = client.call.dispatch_call(
agent_id=agent_id,
to_number=row["phone_number"],
call_context=context
)
print(f"Reminder sent to {row['name']}: {response['json']['id']}")
# Example customer data
customers = [
["phone_number", "account", "name", "balance", "due_date"],
["+15551234567", "5001234567", "John Smith", "125.50", "2024-03-21"],
["+15551234568", "5001234568", "Mary Jones", "89.75", "2024-03-15"]
]
# Save customer data
with open("customers.csv", "w") as f:
writer = csv.writer(f)
writer.writerows(customers)
# Send reminders
send_payment_reminders("customers.csv")
```
### Handle payment calls [#handle-payment-calls]
Your agent is now ready to handle payment-related calls. When customers
receive a call, the agent will:
* Greet customers with the welcome message
* Verify account information for security
* Present payment options based on customer preferences
* Process payments through the preferred method
* Send confirmation with payment details
* Schedule follow-up if needed
### Monitor performance and analytics [#monitor-performance-and-analytics]
Track your payment agent's performance.
```python
def get_payment_analytics(agent_id, days=7):
"""Get comprehensive analytics for payment agent"""
# Get recent call logs
call_logs = client.call.get_call_logs(agent_id=agent_id, page_size=100)
calls_data = call_logs.get('data', [])
# Calculate metrics
total_calls = len(calls_data)
successful_calls = sum(1 for call in calls_data if call.get('status') == 'completed')
average_duration = sum(call.get('duration', 0) for call in calls_data) / total_calls if total_calls > 0 else 0
# Generate report
analytics_report = {
"period_days": days,
"total_calls": total_calls,
"successful_calls": successful_calls,
"completion_rate": f"{(successful_calls/total_calls*100):.1f}%" if total_calls > 0 else "0%",
"average_call_duration": f"{average_duration:.1f} seconds",
"recent_calls": calls_data[:5] # Last 5 calls
}
return analytics_report
# Get weekly performance report
weekly_report = get_payment_analytics(agent_id, days=7)
print("Payment Agent Performance Report")
print(f"Total Calls: {weekly_report['total_calls']}")
print(f"Successful Calls: {weekly_report['successful_calls']}")
print(f"Completion Rate: {weekly_report['completion_rate']}")
print(f"Average Call Duration: {weekly_report['average_call_duration']}")
```
### Update agent configuration [#update-agent-configuration]
Modify your agent settings as needed.
```python
def update_agent_details(agent_id, **kwargs):
"""Update agent configuration"""
response = client.agent.update(agent_id, **kwargs)
print(f"Agent updated successfully")
return response
# Update welcome message for payment deadline
update_agent_details(
agent_id,
welcome_message="Hello! This is BillBot. Your utility bill payment is due in 3 days. Would you like to make a payment now?"
)
# Switch back to outgoing calls
update_agent_details(
agent_id,
call_type="Outgoing"
)
```
### Complete setup [#complete-setup]
Here's the complete setup for a production-ready payment agent.
```python
from omnidimension import Client
import base64
import csv
import json
class UtilityBillPaymentAgent:
def __init__(self, api_key):
self.client = Client(api_key)
self.agent_id = None
def setup_complete_payment_agent(self):
"""Set up a complete utility bill payment voice agent with all features"""
# Create the main agent
agent = self.client.agent.create(
name="BillBot - Utility Payment Assistant",
welcome_message="Hello! This is BillBot from City Utilities. I'm calling about your utility bill. How can I assist you today?",
context_breakdown=[
{
"title": "Complete Payment Options",
"body": """
PAYMENT METHODS:
- Online: www.cityutilities.com/pay
- Phone: 1-800-PAY-BILL (1-800-729-2455)
- Auto-pay: Available for all accounts with 2% discount
- Mobile App: Available on iOS and Android
- Mail: P.O. Box 12345, City, State 67890
- In-person: 123 Main Street, City, State 67890
PAYMENT DEADLINES:
- Bills due: 21st of each month
- Grace period: 5 days
- Late fee: $25 after 10 days
- Disconnection warning: 20 days past due
- Disconnection: 30 days past due
- Reconnection fee: $50
"""
},
{
"title": "Customer Service Guidelines",
"body": "Always be professional and helpful. Listen carefully to customer concerns. Offer payment plans when appropriate. Verify identity before discussing account details. Provide clear payment instructions."
},
{
"title": "Operational Details",
"body": "Call center hours: 8 AM - 8 PM weekdays, 9 AM - 5 PM weekends. Payment processing time: Immediate for online/phone, 1-2 business days for mail. Auto-pay enrollment available during call. Payment plans require supervisor approval for balances over $500."
}
],
call_type="Outgoing",
voice={
"provider": "eleven_labs",
"voice_id": "EXAVITQu4vr4xnSDxMaL"
},
model={
"provider": "anthropic",
"model": "gpt-4o-mini",
"temperature": 0.4
}
)
self.agent_id = agent["json"]["id"]
print(f"Payment agent created: {self.agent_id}")
return self.agent_id
def get_performance_summary(self):
"""Get a quick performance summary"""
if not self.agent_id:
return "No agent configured"
calls = self.client.call.get_call_logs(agent_id=self.agent_id, page_size=50)
total_calls = len(calls.get('data', []))
return {
"agent_id": self.agent_id,
"total_calls_handled": total_calls,
"status": "Active and ready for payment processing!"
}
def send_bulk_payment_reminders(self, customer_file):
"""Send payment reminders to customers from CSV file"""
if not self.agent_id:
print("Please create agent first")
return None
results = []
with open(customer_file) as f:
reader = csv.DictReader(f)
for row in reader:
context = json.dumps({
"account": row["account"],
"name": row["name"],
"balance": row["balance"],
"due_date": row["due_date"]
})
try:
response = self.client.call.dispatch_call(
agent_id=self.agent_id,
to_number=row["phone_number"],
call_context=context
)
results.append({
"name": row["name"],
"status": "success",
"call_id": response["json"]["id"]
})
except Exception as e:
results.append({
"name": row["name"],
"status": "failed",
"error": str(e)
})
return results
# Initialize and deploy payment agent
payment_agent = UtilityBillPaymentAgent("your_api_key_here")
agent_id = payment_agent.setup_complete_payment_agent()
print("\nYour utility bill payment voice agent is now live!")
print(f"Agent ID: {agent_id}")
```
## Key features [#key-features]
### Payment management [#payment-management]
* Multiple payment methods and options
* Automated payment reminders
* Payment processing through conversation
* Payment confirmation and receipts
### Call handling [#call-handling]
* Outbound payment reminder calls
* Natural conversation flow
* Professional payment service experience
* Secure account verification
### Analytics and monitoring [#analytics-and-monitoring]
* Call volume tracking
* Call completion rates
* Average call duration
* Detailed call logs and history
### Agent management [#agent-management]
* Update agent configuration anytime
* Modify welcome messages and context
* Real-time agent performance monitoring
* Easy payment option updates