> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getusertrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebRTC-Based Voice Agents

> Test custom voice agents through WebRTC API endpoints

Test your custom voice agents by hosting them in a sandbox environment with WebRTC support. UserTrace will interact with your voice agent using WebRTC protocols for real-time voice communication.

## API Requirements

Your sandbox must expose a WebRTC-compatible endpoint, plus a health check endpoint.

### 1. WebRTC Voice Endpoint

**Endpoint:** `WebSocket: wss://your-domain.com/voice`

**Connection Handshake:**

```json theme={null}
{
  "type": "start_call",
  "user_id": "sim_user_abc123",
  "session_id": "session_xyz789",
  "metadata": {
    "scenario_id": "customer_support",
    "persona": "frustrated_customer",
    "audio_config": {
      "codec": "opus",
      "sampleRate": 48000
    }
  }
}
```

**Response Format:**

```json theme={null}
{
  "type": "call_ready",
  "session_id": "session_xyz789",
  "call_id": "call_456def",
  "webrtc_offer": {
    "type": "offer",
    "sdp": "v=0\r\no=- 123456789 123456789 IN IP4..."
  },
  "metadata": {
    "agent_ready": true,
    "audio_codec": "opus",
    "estimated_setup_time": "2s"
  },
  "evaluation_metadata": {
    "connection_quality": "excellent",
    "setup_success": true,
    "audio_path_established": true
  }
}
```

### 2. Health Check Endpoint

**Endpoint:** `GET /health`

**Request:**

```bash theme={null}
curl -X GET https://your-sandbox.com/health
```

**Response Format:**

```json theme={null}
{
  "status": "healthy",
  "timestamp": "2024-01-21T10:30:00Z",
  "version": "1.0.0",
  "webrtc_status": "operational"
}
```

## Advanced Configuration

### Optional Parameters

**user\_id** and **session\_id** are optional in requests. If your agent doesn't require session management, you can omit them.

**metadata** is optional and can contain any scenario or context information your agent needs.

**Request with minimal parameters:**

```json theme={null}
{
  "type": "start_call",
  "audio_config": {
    "codec": "opus"
  }
}
```

**Request with full parameters:**

```json theme={null}
{
  "type": "start_call",
  "user_id": "sim_user_abc123",
  "session_id": "session_xyz789",
  "metadata": {
    "scenario_id": "customer_support",
    "persona": "frustrated_customer",
    "context": {
      "issue_type": "billing",
      "urgency": "high",
      "customer_tier": "premium"
    }
  }
}
```

## Implementation Guide

### 1. Set Up Your Sandbox

Deploy your voice agent to a publicly accessible WebSocket endpoint with WSS (secure WebSocket) support.

**Required Headers:**

* `Sec-WebSocket-Protocol: voice-agent`
* `Authorization: Bearer <your-api-key>` (best practice for security)

### 2. Test Your Endpoints

**WebRTC Connection Test:**

```bash theme={null}
curl --include \
     --no-buffer \
     --header "Connection: Upgrade" \
     --header "Upgrade: websocket" \
     --header "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
     --header "Sec-WebSocket-Version: 13" \
     --header "Sec-WebSocket-Protocol: voice-agent" \
     wss://your-sandbox.com/voice
```

**Health Check Test:**

```bash theme={null}
curl -X GET https://your-sandbox.com/health
```

### 3. Configure in UserTrace

1. **Add your sandbox URL** in the UserTrace dashboard
2. **Set authentication** if required (API keys, tokens)
3. **Configure audio settings** (codec preferences, quality settings)
4. **Test connection** using the built-in connectivity checker

## Best Practices

<CardGroup cols={2}>
  <Card title="Performance" icon="zap">
    **Response Optimization**

    • Target \< 200ms audio latency
    • Support 100 concurrent connections
    • Implement proper error handling
    • Add connection quality monitoring
  </Card>

  <Card title="Security" icon="shield">
    **WebRTC Security**

    • Use WSS (secure WebSocket) only
    • Implement DTLS for media encryption
    • Validate all signaling messages
    • Use secure TURN servers
  </Card>
</CardGroup>

## Error Handling

Your API should return appropriate WebSocket close codes and error messages:

**Connection Errors:**

```json theme={null}
{
  "type": "error",
  "error": {
    "code": "connection_failed",
    "message": "Failed to establish WebRTC connection",
    "details": "ICE connectivity check failed"
  }
}
```

**Audio Errors:**

```json theme={null}
{
  "type": "error", 
  "error": {
    "code": "audio_error",
    "message": "Audio stream initialization failed",
    "details": "Unsupported codec: G.722"
  }
}
```

## Voice Processing Support

For agents that handle voice conversations, your response should include both the voice interaction results and conversation metadata:

**Voice Response Example:**

```json theme={null}
{
  "type": "conversation_update",
  "session_id": "session_xyz789",
  "call_id": "call_456def",
  "transcript": {
    "user": "Hi, I need help with my billing issue",
    "agent": "I'd be happy to help you with your billing. Can you provide your account number?"
  },
  "metadata": {
    "audio_quality": "excellent",
    "response_time_ms": 1800,
    "confidence_score": 0.94
  },
  "evaluation_metadata": {
    "understood_intent": true,
    "appropriate_response": true,
    "tone": "professional",
    "next_action": "gather_account_info"
  }
}
```

## Common Integration Patterns

* **Speech Recognition**: Real-time transcription with confidence scores
* **Voice Synthesis**: Text-to-speech with natural voice generation
* **Intent Detection**: Understanding user requests from voice input
* **Context Management**: Maintaining conversation state across turns
* **Quality Monitoring**: Real-time audio quality and connection metrics

## Troubleshooting

**Common Issues:**

* **Connection not establishing**: Check WebSocket endpoint and SSL certificates
* **Audio not flowing**: Verify WebRTC signaling and ICE connectivity
* **Poor audio quality**: Optimize codec settings and network configuration
* **High latency**: Review server location and network routing

<Note>
  **Need help with WebRTC implementation?** Our team can assist with technical setup and optimization. Contact [support@getusertrace.com](mailto:support@getusertrace.com).
</Note>