Complete USSD Playground Tutorial: From Setup to Production

WIGAL: GET params with pipe-delimited response

HUBTEL: Hubtel-specific format

CUSTOM: Configure your own format

Request Method:

• POST: Most common (data in body)
• GET: Required for WIGAL, data in URL params

Section 3: Session & Testing

Session Mode:

• IMPLICIT: Server manages state, each request independent
• EXPLICIT: Client manages state, tracks user journey
• HYBRID: Combines both (recommended for flexibility)

Default Phone Number:

Example: +233540000000
Used for testing, can be changed in simulator

Network:

• MTN
• Vodafone
• AirtelTigo
• Glo
• Other (custom network)

Click "Create Project"

Your project is created and you're redirected to the simulator!

Using the Phone Emulator

Understanding the Interface

The simulator has three main sections:

1. Phone Emulator (Left): Realistic phone interface
2. Controls Panel (Right Top): Session controls and settings
3. Logs Viewer (Right Bottom): Request/response logs

Starting a Session

1. Enter phone number (or use default)
2. Click "Start Session" or dial your USSD code
3. The phone screen shows your USSD menu
4. Type your selection and press "Send"
5. Continue interacting until session ends

Phone Emulator Features

Screen Display:

• Shows current USSD message
• Displays "CON" or "END" indicator
• Shows step number

Input Area:

• Type your selection (e.g., "1" or "2")
• Press "Send" to submit
• Press "Cancel" to end session

Status Indicators:

• Green: Session active
• Red: Session ended
• Step counter shows progress

Understanding Session Logs

What Logs Show

Each log entry displays:

• Step Number: Position in session flow
• Timestamp: When request occurred
• Request Payload: Data sent to your endpoint
• Response Data: What your endpoint returned
• Parsed State: Whether session continues or ends

Expanding Log Details

Click any log entry to see:

Request:
{
  "sessionId": "sess_abc123",
  "phoneNumber": "+233540000000",
  "text": "1*2",
  "serviceCode": "*123#"
}

Response:
{
  "message": "Enter amount:",
  "continueSession": true
}

Parsed:
- Message: "Enter amount:"
- Should Continue: true
- Step: 3

Using Logs for Debugging

1. Check Request Format: Verify your endpoint receives correct data
2. Inspect Response: Ensure your app returns proper format
3. Track Session Flow: Follow user journey step by step
4. Identify Errors: Spot where things go wrong
5. Verify Session Control: Confirm CON/END logic works

Testing Different Scenarios

Happy Path Testing

Test the expected user journey:

1. Dial *123#
2. See main menu
3. Select option 1
4. See submenu
5. Complete action
6. See confirmation
7. Session ends

Error Scenario Testing

Test edge cases:

• Invalid Input: Enter "abc" when number expected
• Out of Range: Select option 9 when only 1-3 exist
• Empty Input: Press send without typing
• Back Navigation: Test going back to previous menu
• Session Timeout: Wait without input (30-90 seconds)

Multiple Network Testing

Change network in controls panel to test:

• MTN-specific behavior
• Vodafone compatibility
• AirtelTigo integration

Debugging Common Issues

Issue: "Session ended unexpectedly"

Possible Causes:

• Your endpoint returned END instead of CON
• continueSession set to false
• Session timeout occurred
• Network error

Solution:

1. Check logs for last response
2. Verify session control logic
3. Ensure proper CON/END prefix or boolean
4. Check endpoint error handling

Issue: "Menu not displaying correctly"

Possible Causes:

• Missing newline characters (\n)
• Message too long (>182 characters)
• Special characters not escaped

Solution:

1. Add \n between menu items
2. Shorten message or split into multiple screens
3. Test with simple text first

Issue: "User input not received"

Possible Causes:

• Endpoint not parsing text field correctly
• Session ID mismatch
• Request format mismatch

Solution:

1. Check request logs for text field
2. Verify sessionId consistency
3. Confirm endpoint format matches project settings

Issue: "Endpoint not responding"

Possible Causes:

• Endpoint URL incorrect
• Server not running
• Firewall blocking requests
• SSL certificate issues

Solution:

1. Verify URL is accessible (test with cURL)
2. Check server logs
3. Ensure HTTPS for production
4. Test with ngrok for local dev

Advanced Features

Using Custom Gateway Builder

For non-standard providers:

1. Select "CUSTOM" as endpoint format
2. Click "Configure Custom Gateway"
3. Set up field mappings
4. Configure response parsing
5. Add authentication if needed
6. Test with test harness

See our Custom Gateway Builder Guide for details.

Testing with Demo Project

Try the pre-configured demo:

1. Click on "Demo Banking USSD" project
2. Explore the banking menu
3. Test balance check, transfers, etc.
4. Review logs to understand flow
5. Use as reference for your project

Editing Project Settings

To modify your project:

1. Go to Dashboard
2. Click "Edit" on project card
3. Update any settings
4. Click "Update Project"
5. Changes apply immediately

Best Practices for Production

1. Thorough Testing

• Test all menu paths
• Verify error handling
• Test with different networks
• Simulate timeouts
• Load test with multiple sessions

2. Optimize Performance

• Keep menus simple (5-7 options max)
• Minimize external API calls
• Cache frequently accessed data
• Use efficient database queries
• Implement proper session management

3. Error Handling

• Validate all user inputs
• Provide clear error messages
• Handle network timeouts gracefully
• Log errors for debugging
• Implement fallback mechanisms

4. User Experience

• Use clear, simple language
• Provide navigation options (Back, Home)
• Show progress indicators
• Confirm important actions
• Keep messages under 160 characters

5. Security

• Validate session IDs
• Implement rate limiting
• Sanitize user inputs
• Use HTTPS for all endpoints
• Don't expose sensitive data in logs

Deploying to Production

Pre-Deployment Checklist

• ✅ All features tested thoroughly
• ✅ Error handling implemented
• ✅ Performance optimized
• ✅ Security measures in place
• ✅ Monitoring and logging set up
• ✅ Backup and recovery plan ready
• ✅ Documentation complete

Deployment Steps

1. Deploy your endpoint: Use reliable hosting (AWS, Heroku, DigitalOcean)
2. Configure production URL: Update project with production endpoint
3. Test in production: Use USSD Playground with production URL
4. Register with USSD provider: Submit your USSD code and endpoint
5. Provider testing: Work with provider to test integration
6. Go live: Provider activates your USSD code
7. Monitor: Watch logs and analytics

Post-Deployment

• Monitor error rates
• Track user behavior
• Gather user feedback
• Iterate and improve
• Keep testing with USSD Playground

Tips and Tricks

Keyboard Shortcuts

• Enter: Send input (in phone emulator)
• Esc: Cancel session
• Ctrl/Cmd + K: Clear logs

Quick Actions

• Double-click log entry: Copy to clipboard
• Right-click phone screen: Copy displayed text
• Click step number: Jump to that step in logs

Testing Efficiency

• Save common test scenarios
• Use realistic test data
• Test incrementally as you build
• Keep a testing checklist
• Document edge cases

Getting Help

Resources Available

• Help & Docs: Comprehensive documentation
• Blog: Tutorials and guides
• Feedback: Report bugs or request features
• Demo Project: Working example to learn from

Common Questions

Q: Can I test locally?
A: Yes! Use ngrok or similar tools to expose your localhost.

Q: Are there usage limits?
A: Free tier includes 10 steps per session, 30 requests/minute.

Q: Can I test multiple projects?
A: Yes! Create unlimited projects.

Q: Is my data secure?
A: Yes! All data is encrypted and private to your account.

Q: Can I share projects with my team?
A: Team features coming soon!

Next Steps

Now that you know how to use USSD Playground:

1. Create your first project with your actual endpoint
2. Test thoroughly using the simulator
3. Debug with logs to perfect your flow
4. Explore advanced features like custom gateway builder
5. Deploy to production with confidence

Conclusion

USSD Playground makes USSD development faster, easier, and more reliable. With features like:

• Real-time phone emulator
• Comprehensive logging
• Multiple gateway support
• Custom gateway builder
• No setup required

You can build and test USSD applications efficiently without needing physical devices or live network connections.

Ready to start building? Create your first project now and experience the easiest way to develop USSD applications!