# Customer interruption tuning

## Scope and release

The voice media, speech detection and playback are handled by Retell, not by Laravel.
Profiles can pin interruption sensitivity, response speed and adaptive response timing.
This does not prove that a live call's missed interruption is caused by these parameters.
There is no automatic change to noise processing, prompts, global defaults or existing
published agents.

Deploy the migration `2026_09_09_100000_add_interruption_sensitivity_to_ai_call_profiles.php`
and `2026_09_10_100000_add_response_timing_to_ai_call_profiles.php` before serving the
updated backend and built frontend. There is no data backfill and
no automatic bulk sync. Existing null profiles retain the server fallback (normally 0.3).

In AI Appointment → AI Agent → Profiles (or the CRM's AI Profiles), edit **Customer
interruption sensitivity**. Values are percentages: 70 becomes Retell's 0.7. Blank
means the server fallback, NOT Retell's default of 1. **Save & Sync publishes immediately**;
use an internal-only test profile first. A failed publish must be resolved before testing.

The CRM is the source of truth for a pinned value. If tuning in the Retell dashboard,
use Pull before the next CRM Sync to adopt it. Pull also overwrites the other supported
profile fields: review the existing pull workflow before using it on an edited profile.
The settings snapshot records the configured override, not an independent measurement
of the provider's effective setting. Legacy null profiles do not snapshot the env fallback.

## Response timing and publication verification

- **Response speed** (`responsiveness_pct`, 0–100): lower waits longer before replying;
  higher responds sooner. This is separate from interruption sensitivity. Zero is a valid
  speed setting, not a switch disabling interruptions. Null omits the update, preserving
  Retell's current setting; a new agent inherits its template's speed. Clearing an override
  does NOT reset the remote value: set an explicit baseline to change it back.
- **Adaptive response timing** (`dynamic_responsiveness`, null/true/false): on lets Retell
  adjust reply timing using the customer's speech rate and earlier turn-taking. Off sends
  an explicit false; null preserves an existing agent's setting (new agents default off).
  Compare manual timing and adaptive timing separately; do not treat them as additive fixes.
- **Save & Sync read-back**: after publishing, Sync fetches `latest_published` with the same
  account key. It requires the expected Agent ID, published version and LLM ID, plus matching
  interruption sensitivity and any explicitly pinned response-timing fields. Only then does
  it record `retell_verified_at` and mark the sync successful. This is a point-in-time
  configuration check, not a guarantee of later provider state or live audio performance.
- **Uncertain publication**: a failed publish response, timeout, unreadable result or mismatch
  records an error, clears the synced/verified claim and makes the profile unavailable to new
  app-initiated calls, including browser **Test Audio** in both CRM and AI Appointment.
  The browser endpoint rejects an unsynced profile before creating a call record or contacting
  Retell. Legacy synced profiles do not need a verification timestamp to keep testing.
  Retell may already be serving the new version; existing calls are not
  stopped or rolled back. Agent/LLM/KB IDs are retained so Retry Sync updates the same agent.
  Neither the old nor new KB is deleted on this path. Unreferenced retained KBs may need manual
  cleanup after an operator verifies no live agent uses them; never delete them on uncertainty.
- **Import/Pull and legacy rows**: remote response settings are imported, but this does not
  count as verifying a CRM publication. They show no verified timestamp until a successful
  Save & Sync. Editing behavior also clears the verification stamp.

## Internal A/B procedure

1. Identify a failing call's actual agency, agent ID and published agent version. AI
   Appointment uses that agency's verified caller connection, not necessarily the CRM's
   platform Retell account. Do not copy API keys into tickets or logs.
2. Use an internal-only profile not referenced by a running customer workflow. Record its
   prompt, opening, voice, sensitivity, responsiveness, denoising mode and language. Keep
   everything but sensitivity constant; do not change the deployment-wide fallback.
3. Establish the current baseline, then compare 70% and 80%. These are trial values, not
   provider recommendations or guaranteed optimal settings. If already at 100%, investigate
   audio/recognition before attributing the symptom to the code's 30% fallback.
4. After each Save & Sync, require a successful published-configuration check on the profile.
   On failure, inspect the same agent in the agency's Retell account or retry; do not assume
   it rolled back. Confirm the test call actually used the verified agent/version, since the
   profile check alone does not prove which profile a workflow selected for a particular call.
5. Run the same short script on an internal phone: interrupt during the opening and during
   a pitch with "wait", "no", "not convenient", and equivalent Chinese/Malay phrases. Include
   low volume, short replies and a longer question, then repeat with background conversation.
   Include coughs and background-only speech to measure false interruptions. Keep the required
   AI disclosure; a short opener reduces collisions without suppressing the whole call.
6. Where recording storage is enabled and permitted, use Retell's multi-channel recording
   and logs to measure customer speech onset → AI audio stopping (median and tail), missed
   intentional interruptions, false stops, and whether the next reply answers the customer's
   latest question. Ordinary end-to-end response latency is NOT the same as interruption-stop
   latency. Record call IDs and scores in the approved internal location, not customer audio
   or public recording links in this repository.
7. Select a setting only after it improves missed interruptions without an unacceptable rise
   in false stops. Repeat one representative test after any voice/language/noise-setting change.

If customer speech is audible but absent from the transcript, investigate recognition and
denoising. Compare normal noise cancellation with no denoising in a quiet controlled test;
aggressive background-speech removal can suppress the intended speaker. If the AI stops but
resumes before the customer finishes, responsiveness/turn-taking is a separate tuning axis.
Do not automatically change all these parameters together. Compare response speed with
adaptive timing explicitly off, then adaptive timing on using the same speech script.

## Rollback

Set the test profile back to its recorded baseline and Save & Sync, then read back the
published setting. To return to the deployment fallback, clear the field explicitly and
Save & Sync. For response speed/adaptive timing, restore explicit baseline values instead
of clearing them (null leaves provider settings unchanged). Merely reverting code or dropping the column does NOT revert a published
Retell agent. Restore provider settings before any schema rollback that would lose overrides.

## Provider references

- [Agent parameters and interruption direction](https://docs.retellai.com/api-references/update-agent)
- [Background noise and speech handling](https://docs.retellai.com/build/handle-background-noise)
- [Call recordings, transcripts and diagnostic logs](https://docs.retellai.com/api-references/get-call)