Keep-Alive

A Pulse STT WebSocket is closed by the server after a period with no inbound frames. In a live conversation, audio arrives continuously and you never hit that limit. In a paused one - the caller is on hold, your agent is waiting on a slow tool call, the user stepped away - you need a way to say “still here” without sending audio.

That is what the keep-alive control frame is for. It is a JSON text frame, it resets the inactivity timer, and it carries no audio.

Sending a keep-alive

Send a JSON text frame with a type of ping:

1
{ "type": "ping" }

The server replies on the same socket with:

1
{ "type": "pong" }

Three aliases behave identically to ping, so you can reuse whatever your client already emits: keepalive, keep_alive, keep-alive.

What it does and does not do

Because the frame never reaches the model, a keep-alive is not a substitute for audio. It holds the connection open; it does not hold the model session open indefinitely. See Limits.

Example

1
import asyncio, json, websockets
2
3
URL = "wss://api.smallest.ai/waves/v1/stt/live?model=pulse&language=en&sample_rate=16000&encoding=linear16"
4
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
5
6
async def keepalive(ws, stop, every=30):
7
    """Ping every `every` seconds while no audio is flowing."""
8
    while not stop.is_set():
9
        await asyncio.sleep(every)
10
        await ws.send(json.dumps({"type": "ping"}))
11
12
async def main(audio_source):
13
    stop = asyncio.Event()
14
    async with websockets.connect(URL, additional_headers=HEADERS) as ws:
15
        pinger = asyncio.create_task(keepalive(ws, stop))
16
        try:
17
            async for chunk in audio_source:      # binary frames
18
                await ws.send(chunk)
19
            await ws.send(json.dumps({"type": "close_stream"}))
20
        finally:
21
            stop.set()
22
            pinger.cancel()
23
24
asyncio.run(main(audio_source))

A 30-second interval is a good default: comfortably inside every limit below, and cheap enough to run unconditionally rather than tracking whether audio is currently flowing.

Limits

Three separate limits apply to a streaming session. Only the first is affected by keep-alives.

On inactivity timeout the server sends {"status":"error","message":"Connection timed out after N seconds of inactivity"} and terminates the socket.

Raising the inactivity timeout

Add timeout=<seconds> to the connection URL to raise the inactivity limit, up to a maximum of 3 hours (10800 seconds):

1
url.searchParams.append("timeout", "3600"); // 1 hour of inactivity tolerated

Values above the maximum are clamped rather than rejected. Keep-alives and timeout solve the same problem from two directions - prefer keep-alives, because they also give you a pong you can use to detect a half-open connection, which a raised timeout does not.

Cost

Pulse STT is billed on audio duration - the amount of audio you actually send - not on how long the WebSocket stays open. A connection held open with keep-alives and no audio accrues no charge: there is no connection fee and no minimum session duration.

This means suppressing silence is a real lever. If your client already runs voice activity detection, you can stop sending frames during long pauses, hold the socket with keep-alives, and resume when speech starts. Two things to watch when you do:

• Send a little pre-roll. Resume streaming ~200 ms before detected speech onset so the first word is not clipped.
• Finalize explicitly. Pulse’s automatic finalization is driven by trailing silence in the audio. If you stop sending audio, that trailing silence never arrives - send {"type":"finalize"} to flush the pending transcript.

Related

• Finalize Control - the finalize and close_stream control messages.
• Endpointing - trailing-silence finalization, and why it stops when audio stops.
• Real-time Troubleshooting - connection drops and timeouts.
• Pulse STT WebSocket reference - full parameter and control-message reference.