Skip to main content
Test your WhatsApp Business agent by connecting your WhatsApp number to UserTrace. Our simulated users will interact with your agent directly through WhatsApp messages.

​
Getting Started

​
1. Connect Your WhatsApp Number

In the UserTrace dashboard, navigate to Agent Setup and select WhatsApp Integration. Required Information:
  • WhatsApp Business number (with country code)
Example: 
WhatsApp Number: +1-555-123-4567

​
2. Set Evaluation Context

Define your pass and fail criteria for what constitutes successful interactions: Example Pass/Fail Criteria: 
Pass Criteria:
- Responds within 30 seconds
- Uses friendly, conversational tone
- Asks for order number when relevant
- Provides clear solutions or next steps
- Resolves customer issues effectively

Fail Criteria:
- Response time exceeds 60 seconds
- Uses inappropriate or unprofessional tone
- Fails to gather necessary information
- Provides incorrect or unhelpful responses
- Escalates unnecessarily

​
Important Simulation Details

​
Sequential Testing

One at a Time: All simulations run sequentially (one after another) from the same phone number to avoid message conflicts and ensure clean conversation threads.
How it works:
  • Simulation 1 completes entirely before Simulation 2 starts
  • Each simulation appears as a separate conversation thread
  • No message overlap or confusion between different test scenarios

​
Test Number Management

Our Test Number: All simulations will come from a designated UserTrace phone number. This number will:
  • Send messages as different personas
  • Complete full conversation scenarios
  • Reset between simulations for clean testing
Your Setup: Ensure your WhatsApp Business account can receive messages from new numbers without restrictions.

​
Best Practice: Use Sandbox Environment

Recommended Approach: Use your WhatsApp sandbox number instead of your production number to avoid any concerns about triggering real business actions during testing.
If you must use your production WhatsApp number, ensure you prevent the test number from triggering real business actions: Actions to Disable:
  • Booking confirmations - Don’t create real reservations
  • Payment processing - Don’t charge actual money

​
Best Practices

Response Timing

Natural Conversation Flow• Respond within 30 seconds for best results • Use typing indicators if available
• Handle message bursts gracefully

Message Handling

WhatsApp Features• Support media messages (images, voice) • Handle quick reply buttons • Use structured messages when appropriate

​
Testing Process

​
Inbound Agent Testing

For agents that respond to incoming messages:
  1. Our test number sends the first message to your WhatsApp
  2. Your agent responds based on the scenario
  3. The conversation continues until completion
  4. Results are analyzed and scored

​
Outbound Agent Testing

For agents that initiate conversations (outbound messaging):
  1. UserTrace sends a webhook request to your system
  2. Your agent initiates the conversation by sending the first message
  3. Our simulated user responds according to the scenario
  4. The conversation continues until completion
  5. Results are analyzed and scored
Webhook Format for Outbound Agents: 
{
  "trigger": "start_simulation",
  "scenario_id": "delivery_followup",
  "target_number": "+1-555-TEST-NUM",
  "metadata": {
    "persona": "busy_customer",
    "context": "late_delivery_followup"
  }
}

​
2. Between Simulations

  • 30-second delay between different scenarios
  • New conversation thread starts fresh
  • Previous context is cleared

​
3. View Results

Each simulation provides:
  • Complete conversation transcript
  • Response time analytics
  • Success/failure against your criteria
  • Persona-specific behavior analysis

​
Common Scenarios

Customer Service Examples:
  • “My order is late, where is it?”
  • “I want to cancel my subscription”
  • “The food was cold when delivered”
  • “I was charged twice for my order”
Sales Examples:
  • “What’s your most popular dish?”
  • “Do you deliver to my area?”
  • “I have food allergies, what can I eat?”
  • “What are your hours today?”

​
Troubleshooting

Common Issues:
  • Messages not delivering: Check WhatsApp Business API status
  • Slow responses: Optimize your webhook response time
  • Test actions triggering: Verify blacklist implementation
  • Conversation mixing: Ensure proper thread management
Need help with WhatsApp setup? Our team can assist with Business API configuration and testing best practices. Contact [email protected].Next Steps: Create test scenarios for your WhatsApp agent and run simulations to validate performance.