Listening profiles

A listening profile is a per-agent preset for how the voice runtime listens to the user: when speech starts and stops, whether the user can interrupt the assistant, and how to handle the first message.

You can keep one profile per agent and call it good, or maintain a small catalog (Default, Patient, Fast, Phone) and assign different profiles to different users.

What a profile controls

Knob	Meaning
vad_confidence	Silero VAD confidence threshold (0–1). Higher = stricter speech detection.
vad_start_secs	Voiced seconds required before triggering speech start.
vad_stop_secs	Silence seconds before considering the user done.
vad_min_volume	Minimum normalised volume to count as speech.
interruption_policy	always, never, or min_words.
min_words_before_interrupt	When min_words, words required before barge-in is allowed.
first_message_interruptible	When false, the agent’s opening turn is not interruptible.
noise_suppression	off, rnnoise, or auto (wire-protocol reserved; processor wiring deferred).
audio_gate_enabled	Drop user audio while the assistant is speaking (deferred).
soft_timeout_override	Per-profile override of the agent’s stack-level soft timeout.

Defaults match the runtime’s turn_eagerness="normal" mapping, so an agent with no profile catalog still behaves like the MVP voice runtime.

Resolution cascade

For a given conversation between an agent and a user, the runtime picks a profile in this order:

1. The (agent_id, user_id) listening assignment, if one exists.
2. The agent’s default profile (is_default = true in the catalog).
3. The built-in DEFAULT_VOICE_TUNING constant.

Exactly one profile per agent should be marked default. The dashboard enforces this when you set a new default through POST /workspaces/{ws}/agents/{agent_id}/listening-profiles/{id}/set-default.

Manage profiles from the dashboard

Open the agent’s Listening tab. The page shows the catalog, the default flag, and any per-user assignments. Create / edit / archive profiles inline.

Manage profiles through the API

# List
curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/listening-profiles" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

# Create
curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/listening-profiles" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "patient",
    "name": "Patient",
    "description": "Slower listener for users who pause mid-sentence.",
    "voice_tuning": {
      "vad_stop_secs": 0.9,
      "interruption_policy": "min_words",
      "min_words_before_interrupt": 5,
      "first_message_interruptible": false
    }
  }'

# Set default
curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/listening-profiles/$PROFILE_ID/set-default" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

# Assign per user
curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/listening-assignments" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "user_...", "profile_id": "lp_..." }'

Picking values

• Phone agents typically want higher vad_confidence, slightly longer vad_stop_secs, and first_message_interruptible: false so callers don’t talk over the greeting.
• Web agents with good microphones can tolerate lower thresholds and interruption_policy: "always".
• Older or distracted callers benefit from interruption_policy: "min_words" (3–5 words) so a single “uh” doesn’t drop the turn.
• The voice profile (under Voices) controls audio-stack settings; the listening profile controls how the runtime decides when the user is talking. Don’t conflate the two.

What to watch in traces

When tuning, look at observability for:

• The gap between the user finishing and the assistant starting (your vad_stop_secs is too long).
• Mid-sentence assistant cut-offs (your interruption_policy is too eager, or the user has background noise).
• First-message barge-ins on phone calls (set first_message_interruptible: false).