Media connection warning and give-up timeout

:::caution Next — unreleased This reference describes SCRUM-700, implemented in platform PR #523, with a related prompt-preparation refactor in platform PR #534. Documentation review #44 links the implementation and acceptance evidence (platform repository access required). Local acceptance does not establish deployment or carrier/browser acceptance. Do not assume this feature is present in a released version. :::

The gateway monitors incoming RTP packets on the caller leg, starting when that leg connects. A caller who is quiet but continues sending RTP is not a media failure. Bot response timeouts, STT silence/endpointing and caller speech mute are separate controls.

Defaults and valid range

Platform administrators configure the mediaConnection setting. The UI displays seconds; API and stored values use integer milliseconds.

Field	Default	Validation
warningAfterMs	10000 (10 seconds)	Integer, 1000–300000 ms, subject to the gap below
disconnectAfterMs	30000 (30 seconds)	Integer, 1000–300000 ms, subject to the gap below
warningText	“There seems to be a problem with the audio connection. Please stay on the line while we wait for it to recover.”	Trimmed, non-empty, at most 500 characters
warningLanguage	en-US	Valid canonical language tag, non-empty, at most 100 characters

disconnectAfterMs - warningAfterMs must be at least 5000 ms. Consequently, the effective maximum warning time is 295000 ms and the effective minimum disconnect time is 6000 ms. Zero does not disable the watchdog. The disconnect deadline is measured from connection/last observed media, not from the end of the warning: defaults mean a warning at 10 seconds and disconnect at 30 seconds, not 40 seconds.

Configuration scope

• Platform: owns both timing values and the default warning text/language.
• App / Flow Designer app settings: can override only mediaConnectionWarningText and mediaConnectionWarningLanguage. Set both together; set both to null to inherit platform text/language. Omitting both leaves the existing override unchanged. An app cannot override the timings.
• Active calls: use a settings snapshot resolved when their monitor starts. Saving settings is not a live timeout update for existing calls. These platform-owned fields cannot be overridden by managed-bot runtime configuration.

Gateway announcements use the selected speech language and configured speech provider. Translation uses the platform translation LLM, not the conversational bot. If announcement preparation fails, the failure is logged and the timeout still applies; audible delivery is not guaranteed when the media path is broken.

Recovery and hold

An observed increase/change to a positive caller RTP receive counter resets the missing-media timer. If the call recovers after a warning, warning playback stops and the prepared recovery announcement can play. A later gap starts a new warning window. A counter reset to zero alone is not recovery.

Recognized SIP hold suspends missing-media termination; unhold starts a fresh timer. Failed or invalid RTP-statistics reads are logged and retried, not treated as proof that zero RTP packets arrived. Monitoring stops on call teardown or a committed terminal action.

Termination reasons

Situation at the give-up deadline	Persisted detail / SIP Reason text	Category	SIP cause	Q.850 cause
No incoming RTP has ever been observed	no_media	Media	408	102
Incoming RTP was observed, then stopped for the deadline	media_connection_broken	Media	408	102

For the default no-RTP case the SIP BYE contains Reason: SIP;cause=408;text="no_media" and Reason: Q.850;cause=102. Use the full call ID to correlate SIP signaling and the persisted conversation end reason. Do not classify an STT transcription failure or a slow bot as no_media without RTP evidence.

Verified acceptance and limits

The local SIPp no-RTP report, linked from documentation review #44, records call scrum700-no-rtp-1789471629572: all 56 independent receive-counter samples were zero; the gateway BYE arrived 30.683 seconds after ACK with SIP 408, Q.850 102 and no_media; the persisted end reason also matched. This proves the local no-RTP deadline/signaling path, not carrier acceptance or every recovery, hold, browser and speech-provider scenario. Platform review and current staging checks remain separate prerequisites for integration.

See also call handling properties.