Introduction

brisvox is a Rust-native, open-source engine for real-time voice agents: a phone call or a browser session in which a caller talks, the agent listens, thinks (an LLM, with tools) and answers in a synthesised voice, and the caller can interrupt at any moment.

It is built to beat Pipecat on three axes, with the same speech and language providers:

• Latency. Voice-to-voice latency is the time from the end of the caller's speech to the first sound of the answer. brisvox keeps its own share of that to well under a millisecond per stage and takes work off the critical path: connections are prewarmed, the speech-to-text Finalize runs in parallel with the end-of-turn model, the LLM can start speculatively, and the first clause of the answer goes to the voice after one word.
• Density. One process hosts many calls. Every call is an isolated session; a panic or a provider failure in one never touches another. Model inference runs on a dedicated pool, never on the async workers.
• Correctness. Interruptions and tool calls are where voice agents silently break. brisvox numbers every user turn (a turn epoch) and drops stale frames everywhere; after a barge-in the LLM sees only the text that was actually played; side-effecting tools never run speculatively and never run twice within a call's turn (the exact scope is in the Tools chapter: a second call or a later turn is not covered, so keep your own idempotency key for "once per order, ever"). Behaviour is proven by deterministic, paused-time simulation, not by hope.

Status. The engine, the transports, the provider adapters, the server binary and both agent SDKs are implemented and tested against mocks and recorded protocol fixtures. Live runs against the real providers, and the head-to-head comparison with Pipecat, are pending: see Benchmark results for exactly what has been measured so far and on what.

How the book is organised

The configuration, telephony, operations and reference chapters are the repository's docs/ files, included as they are, so there is one source of truth: the same text is on GitHub and in this book. References in those files to source paths (crates/..., docs/..., bench/results/...) name files in the repository.

Where to start

• To see it work: Run the server with an example agent.
• To put your own application logic behind a call: Write an agent with the SDK.
• To understand why it behaves the way it does: The pipeline.

License

Dual-licensed under Apache-2.0 or MIT, at your option. The speech test fixtures in fixtures/ (Google FLEURS / FLORES) are CC BY-SA 4.0; see the repository's fixtures/NOTICE.

Quickstart

Four ways in, from smallest to most complete:

1. Run the server with an example agent. Build brisvox-server, point it at examples/agents/support-en.toml, set three provider keys, and talk to it over the websocket protocol.
2. Write an agent with the Python or TypeScript SDK. The server runs the call (audio, speech recognition, turn taking, LLM, speech synthesis) and connects out to your process, which holds your tools and your application logic.
3. Docker and compose. The container image and deploy/compose.yaml: a websocket agent and a Twilio phone agent from one image.
4. A fully local assistant. sherpa-onnx, Ollama and Kokoro on your own machine, no API key, talked to from a browser page.

What you need in all cases:

• Rust (the toolchain is pinned in rust-toolchain.toml; rustup picks it up) for a source build, or Docker for the image.
• API keys for one provider per stage (none for the local assistant). The examples use Deepgram (speech to text), OpenAI (LLM) and Cartesia (text to speech). Keys are read from the environment, never from a file in the repository, and the server does not read a .env file: export them in the shell (or use --env-file with Docker).
• For the browser example (examples/web-assistant) a server built with the webrtc feature, which also needs a C compiler and cmake.

Without keys you can still run everything that does not call a provider: the deterministic simulations and the benchmark harness run on mock providers (cargo run --release -p brisvox-bench -- v2v --sim, see Benchmark results).

Run the server with an example agent

brisvox-server loads one agent definition and serves every call with it. This page builds the server, runs it with examples/agents/support-en.toml (Deepgram + OpenAI + Cartesia) and plays a recorded utterance at it.

1. Build

git clone https://github.com/bilal07karadeniz/brisvox && cd brisvox
cargo build --release -p brisvox-server --features all-providers,smart-turn-ort,demo-tools
python3 scripts/models/fetch_models.py     # the Smart Turn model, SHA-256 pinned, into models/

• all-providers compiles every STT/LLM/TTS adapter. The default build has none; a definition that names a provider whose feature is off is refused at startup with the feature to turn on.
• smart-turn-ort loads the Smart Turn v3.2 end-of-turn model (the example agent uses the adaptive turn policy). The ONNX Runtime binaries are downloaded at build time.
• demo-tools adds a canned lookup_order tool so the example runs without an application. Never ship it to callers. Your own tools come from an SDK agent or from brisvox_server::tools::AppTools in a small Rust binary of your own (examples/rust-tools).

The Silero voice-activity model is compiled into the binary.

2. Run

Check the agent file first. check runs the server's own loader without starting anything (no sockets, no network), so a typo in a key, a missing environment variable, a provider the binary was built without or a tool nothing provides shows up now, with the line and column, instead of when the server starts:

export DEEPGRAM_API_KEY=...  OPENAI_API_KEY=...  CARTESIA_API_KEY=...
export BRISVOX_AGENT_FILE=examples/agents/support-en.toml
target/release/brisvox-server check "$BRISVOX_AGENT_FILE" --require-secrets

It exits 0 when the file is valid and 1 when it has errors; without --require-secrets a variable that is not set is only a warning (use that where the keys are not present, such as a build job). Then start the server:

target/release/brisvox-server

With no other listener configured the server listens for the websocket protocol on 127.0.0.1:8080 and for health probes on 0.0.0.0:8081 (GET /healthz, GET /readyz, and GET /metrics unless BRISVOX_METRICS turns it off; off a loopback address /metrics needs BRISVOX_METRICS_TOKEN). The websocket listener has no authentication of its own: it refuses to bind a non-loopback address without BRISVOX_SESSION_SECRET or BRISVOX_WS_TOKEN (see Security), and a TLS-terminating proxy belongs in front of it.

curl -i http://127.0.0.1:8081/readyz

3. Talk to it

One websocket connection is one call: binary frames carry audio, text frames carry JSON (start, started, clear, mark, stop, ...). Any client that follows the protocol works. The repository ships two ways to try it without writing one:

• The benchmark harness plays a recorded utterance in real time and reports how long the agent took to answer (this needs the three keys, because the providers are real):

  cargo run --release -p brisvox-bench -- v2v --url ws://127.0.0.1:8080/ \
      --fixtures en_two_utterances --runs 1
  

• The browser assistant in examples/web-assistant (one static HTML file) talks to the server over WebRTC with your microphone. It needs a server built with the webrtc feature and BRISVOX_WEBRTC_ADDR; see its README.

4. Change the agent

The agent file is the whole configuration: prompt, language, which tools the LLM may call, the turn and interruption settings, and one provider per stage. Copy support-en.toml, edit it, and restart. examples/agents/ also has a Turkish support agent, a telephony agent and a provider failover agent, each as TOML and as YAML. Every key is documented in Configuration; every server setting (BRISVOX_* environment variables: listeners, admission limits, metrics, recording) in Operations.

Next

• Write an agent with the SDK to put your own tools behind the call.
• Telephony to answer real phone calls.

Write an agent with the Python or TypeScript SDK

The SDKs implement the agent protocol. The split:

• The server runs the call: audio, voice-activity detection, speech recognition, turn taking, the LLM, speech synthesis, interruptions.
• Your agent process holds the application logic: the tools the LLM can call, the prompt per call, commands such as "say this", "transfer the call" or "hang up", and the events you want to react to (what the caller said, what the bot said, turns, errors).

The server connects out to your agent over a WebSocket, one connection per call, so your process is a plain WebSocket server you can run anywhere the brisvox server can reach. Set BRISVOX_AGENT_URL (ws:// or wss://) on the server; BRISVOX_AGENT_TOKEN is sent as a bearer token. Without BRISVOX_AGENT_URL, calls run on the agent file alone.

Python

Python 3.11 or newer, one dependency (websockets).

pip install brisvox-agent          # from PyPI (`pip install brisvox` installs it too, under the short name)
pip install ./sdk/python             # or from a checkout of the repository

from brisvox_agent import Agent, Session, UserText

agent = Agent("luigi", system_prompt="You are Luigi's host.", greeting="Hi, Luigi's here!")

@agent.tool                                   # JSON schema from the type hints
async def opening_hours(day: str) -> str:
    """Opening hours of the restaurant on a weekday."""
    return "12:00 to 22:00"

@agent.on_user_text
async def heard(session: Session, event: UserText) -> None:
    if "bye" in event.text.lower():
        await session.end("Goodbye!")         # speaks the farewell, then ends the call

agent.run(port=8765)

Tools default to read_only; mark a tool that changes the world with @agent.tool(kind="side_effect"). The server never runs those speculatively and never twice for one call id of a call (the tool context carries an idempotency key). That key does not see a second phone call or a later turn: for "one refund per order, ever" derive your own key from the business data (the order id) and enforce it in your store or with the downstream API's Idempotency-Key. More in sdk/python/README.md; a larger, tested example is examples/booking-agent.

TypeScript

Node 20 or newer, one runtime dependency (ws).

npm install @brisvox/agent              # from npm (`npm i brisvox` re-exports it; the browser client is `brisvox/web`)
# or from a checkout of the repository:
cd sdk/typescript && npm ci && npm run build

import { Agent, s } from "@brisvox/agent";

const agent = new Agent({ name: "luigi", systemPrompt: "You are Luigi's host.", greeting: "Hi, Luigi's here!" });

agent.tool({
  name: "opening_hours",
  description: "Opening hours of the restaurant on a weekday.",
  parameters: s.object({ day: s.enum(["mon", "tue", "wed", "thu", "fri", "sat", "sun"]) }),
  handler: async ({ day }) => (day === "mon" ? "Closed on Monday." : "12:00 to 22:00."),
});

agent.onUserText(async (session, event) => {
  if (event.text.toLowerCase().includes("bye")) {
    await session.end({ say: "Goodbye!" });
  }
});

await agent.run({ port: 8765 });

More in sdk/typescript/README.md. The TypeScript SDK mirrors the Python one.

Connect the server to it

Start the agent, then the server (the same build and keys as in Run the server with an example agent):

python sdk/python/examples/minimal.py        # listens on ws://127.0.0.1:8765
BRISVOX_AGENT_URL=ws://127.0.0.1:8765 \
BRISVOX_AGENT_FILE=examples/agents/support-en.toml \
  target/release/brisvox-server

The agent file still names the providers and the turn settings; the agent process adds its tools to the call and may set the prompt per call. An agent that is down, slow or rejects a call never fails the call: it runs on the agent file's own prompt and tools (and the caller hears up to 4 s of silence while the server waits for an unreachable agent, with the default timeouts). The wire format, version negotiation, error codes and limits are in Agent protocol; tools in general are in Tools.

Docker and compose

The repository has a multi-stage Dockerfile and deploy/compose.yaml, which runs two services from one image:

• agent-ws, a websocket agent for browsers and apps (the websocket protocol);
• agent-twilio, a phone agent behind Twilio Media Streams with Twilio call control (transfer, DTMF, hang-up).

cp deploy/ws.env.example deploy/ws.env              # fill in DEEPGRAM_API_KEY, OPENAI_API_KEY, CARTESIA_API_KEY
cp deploy/twilio.env.example deploy/twilio.env      # keys, Twilio settings and BRISVOX_TWILIO_STREAM_SECRET (required)
docker compose -f deploy/compose.yaml up --build
# or just one service:
docker compose -f deploy/compose.yaml up --build agent-ws

Every release also publishes the image, so nothing has to be built: set BRISVOX_IMAGE to ghcr.io/bilal07karadeniz/brisvox-server:vX.Y.Z (or :latest) and start with up --no-build:

BRISVOX_IMAGE=ghcr.io/bilal07karadeniz/brisvox-server:latest \
  docker compose -f deploy/compose.yaml up --no-build agent-ws

agent-twilio does not start until BRISVOX_TWILIO_STREAM_SECRET (at least 32 random bytes, for example openssl rand -base64 48) has a value in deploy/twilio.env; the same secret goes to your voice webhook, which answers each call with a signed per-call stream URL (examples/phone-receptionist/twiml_server.py is one; see Twilio Media Streams), and the proxy in front must route the per-call path /twilio/stream* (Deploying in a container).

Check that the websocket agent is up:

curl -i http://127.0.0.1:8081/readyz

As written, both services publish their ports on 127.0.0.1 only. The generic websocket listener has no authentication of its own (compose runs it with BRISVOX_INSECURE_LISTENERS=1 because its port is loopback-only; set BRISVOX_SESSION_SECRET before publishing it) and Twilio needs a public wss:// URL, so for anything beyond your own machine put a TLS-terminating reverse proxy in front. The container runs as a non-root user with a read-only root filesystem, no capabilities and a tmpfs /tmp; it drains on SIGTERM (the compose file's stop_grace_period: 45s is longer than the drain).

The image bakes in the Smart Turn model and two reference agent definitions (deploy/agents/web.toml, deploy/agents/phone.toml); mount your own over /etc/brisvox/agent.toml to change the agent.

Everything about the image (build arguments and feature sets, size, health checks, TLS and reverse-proxy notes, Kubernetes probes) is in Deploying in a container; every setting is in Operations.

To add your own tools, run an SDK agent next to the container and set BRISVOX_AGENT_URL (and BRISVOX_AGENT_TOKEN) on the service.

A fully local assistant

A voice assistant that never leaves your machine: no API key, no cloud. Speech recognition is sherpa-onnx (on the CPU), the language model is Ollama, the voice is Kokoro (Kokoro-FastAPI, on the GPU when you have one), and you talk to it from a browser page that brisvox-server serves itself. The agent is examples/agents/local/local-en.toml.

What runs where:

browser (microphone) --WebSocket--> brisvox-server --ws--> sherpa-onnx   :6007  (STT, CPU)
                                           |------http--> Ollama         :11434 (LLM)
                                           '------http--> Kokoro-FastAPI :8880  (TTS, GPU or CPU)

The brisvox server and Kokoro (published with -p 127.0.0.1:8880:8880) bind 127.0.0.1, and Ollama does by default. sherpa-onnx's streaming_server.py does not: it has no bind-address flag and listens on all interfaces (its source passes host="" to websockets.serve, checked 2026-10-14). The three helper servers have no authentication, so on a machine that other computers can reach, block port 6007 (6006 for Turkish) from outside with the host firewall, or run the script inside a container that publishes the port only on loopback (-p 127.0.0.1:6007:6007). Nothing in this setup needs a key or an account.

This page is verified in parts: the server, sherpa-onnx (English and Turkish models) and Kokoro were each run on WSL2 (Ubuntu 24.04) with an NVIDIA RTX 5070, and the whole stack was exercised in a browser call. The project gives no memory or disk figure for the stack; plan for a few GB of downloads (the models, the Kokoro image, an Ollama model) and check what your GPU can hold. Tool calling through Ollama was measured on five local models and works reliably with one of them (step 2); the example agent itself defines no tools.

1. Build the server

git clone https://github.com/bilal07karadeniz/brisvox && cd brisvox
cargo build --release -p brisvox-server \
  --features provider-sherpa-onnx,provider-openai-compatible,provider-openai-speech,smart-turn-ort,webrtc
python3 scripts/models/fetch_models.py     # the Smart Turn model, SHA-256 pinned, into models/

The server looks for that model in BRISVOX_MODELS_DIR, whose default models is relative to the directory the server is started from, not to the binary. Start it from the repository root as the commands below do, or set an absolute path in step 3 (export BRISVOX_MODELS_DIR="$PWD/models"); check warns when the file is not found.

The repository pins its Rust toolchain in rust-toolchain.toml; rustup installs it on the first build. Why each feature:

• provider-sherpa-onnx, provider-openai-compatible, provider-openai-speech are the three adapters this agent names (all-providers turns every adapter on instead).
• smart-turn-ort loads the end-of-turn model. The agent uses the default, adaptive turn policy; without this feature and the model file the server logs a warning and every turn ends at a 3 second fallback deadline, which feels broken. Keep it.
• webrtc is what serves the browser page: the page, its signaling and the WebSocket audio path live in the WebRTC listener. It compiles libopus, so you need a C compiler and cmake (sudo apt install build-essential cmake on Debian and Ubuntu). If you talk to the server with your own websocket client instead, leave it out and use BRISVOX_WS_ADDR (protocol).

2. Start the three helper servers

Each in its own terminal. These are the commands of the projects themselves, as in the header of the agent file.

Speech recognition: sherpa-onnx on port 6007 (English).

git clone https://github.com/k2-fsa/sherpa-onnx          # for python-api-examples/
pip install sherpa-onnx websockets numpy
wget https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-streaming-zipformer-en-2023-06-26.tar.bz2
tar xvf sherpa-onnx-streaming-zipformer-en-2023-06-26.tar.bz2
M=./sherpa-onnx-streaming-zipformer-en-2023-06-26
python3 ./sherpa-onnx/python-api-examples/streaming_server.py \
  --tokens  $M/tokens.txt \
  --encoder $M/encoder-epoch-99-avg-1-chunk-16-left-128.int8.onnx \
  --decoder $M/decoder-epoch-99-avg-1-chunk-16-left-128.onnx \
  --joiner  $M/joiner-epoch-99-avg-1-chunk-16-left-128.int8.onnx \
  --port 6007

The model prints UPPERCASE text without punctuation; the language model copes with it. For a Turkish assistant use examples/agents/local/local-tr.toml, the seda-v0.1 model and --port 6006 (the commands are in docs/providers/sherpa-onnx.md). The ports are fixed by the two example agents, 6006 for Turkish and 6007 for English, so both stacks can run side by side.

The language model: Ollama.

ollama pull gemma4:12b-it-qat

gemma4:12b-it-qat is the model that called tools correctly in every test run (it needs about 7.7 GB of GPU memory and answers its first sentence in roughly 0.3 s on an RTX 5070). With less room, gemma4:e4b-it-qat (3.1 GB, even faster) speaks well but fumbles tool calls, so give the agent no tools. The example agents set reasoning_effort = "none": the models above think by default, which costs seconds before the first word. If the language model and Kokoro together do not fit in your GPU memory, Ollama puts part of the model on the CPU and the first sentence takes about 1.7 s; the Kokoro CPU image frees the GPU for the language model. The numbers for five models are in Tools ("Local models through Ollama").

The Linux package starts ollama serve as a service; start it yourself only when nothing listens on 127.0.0.1:11434. A model that was idle is unloaded and the next request pays for loading it (OLLAMA_KEEP_ALIVE on the server keeps it resident).

The voice: Kokoro-FastAPI on port 8880.

docker run --gpus all -p 127.0.0.1:8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

On an RTX 50 series card use the tag latest-cu128 (CUDA 12.8). Without a GPU use the image ghcr.io/remsky/kokoro-fastapi-cpu:latest and drop --gpus all. The 127.0.0.1: in -p matters: Kokoro's own examples publish the port on every interface. The first request after a long idle is slower (the model has to warm up), so the agent's kokoro preset warms it in the background at the start of a call.

So the compute is split like this: speech recognition runs on the CPU, the language model and the voice use the GPU when there is one. Turkish needs a different voice server, and the one the project tried (Chatterbox) takes about 3 seconds to the first audio, too slow for a live turn (docs/providers/openai-speech.md, "Live").

3. Check, then run

target/release/brisvox-server check examples/agents/local/local-en.toml

check loads the agent file with the server's own loader and opens no sockets, so a typo, a provider the binary was built without or a missing Smart Turn model shows up now with the line and column. Then start the server with loopback-only settings:

export BRISVOX_AGENT_FILE=examples/agents/local/local-en.toml
export BRISVOX_MODELS_DIR="$PWD/models"        # absolute: the default `models` is relative to the working directory
export BRISVOX_WEBRTC_ADDR=127.0.0.1:8088      # the page and the WebSocket audio path
export BRISVOX_HEALTH_ADDR=127.0.0.1:8081      # the default is 0.0.0.0:8081
target/release/brisvox-server
curl http://127.0.0.1:8081/readyz              # ready

No credentials are needed: listeners on a loopback address start without them. Nothing here reads a .env file; export the variables in the shell that starts the server.

4. Talk to it

Open http://127.0.0.1:8088/demo?force=ws in Chrome or Edge, press Start, allow the microphone and say "Hello". Talk over the assistant to interrupt it.

There are two ways to open the page. /demo (no query) is the default: the page tries WebRTC first, and if the media connection is not up after 4 seconds it falls back to a WebSocket on the same port. /demo?force=ws skips WebRTC and sends the audio over that WebSocket from the start. Use ?force=ws with a browser on the same machine as the server: WebRTC media between a browser and a server on one host needs a real network address (Chrome gathers no loopback candidates), so the WebRTC attempt cannot succeed here and plain /demo only adds the 4 second wait (and a second session token). On a server other people reach over the network, use plain /demo: WebRTC carries the audio there, with the WebSocket as the safety net. The status line says which transport carries the call. The page examples/web-assistant/web/index.html does the same with its own server box if you want a page you can edit.

Notes for Linux, WSL2 and Windows

• Linux. Everything above runs as written, and nothing leaves loopback, so no LAN address or firewall rule is involved.
• WSL2 on Windows. This is what the project's own local runs used (Ubuntu 24.04). Run the server, sherpa-onnx, Ollama and Kokoro inside WSL2. Docker needs the NVIDIA container toolkit for --gpus all (Docker Desktop with the WSL2 backend, or Docker inside the distribution). Open the page from the Windows browser at http://127.0.0.1:8088/demo?force=ws: WSL2 normally forwards loopback ports to Windows, and localhost counts as a secure context for the microphone. If the page does not load, check localhostForwarding in .wslconfig or use WSL's mirrored networking (not tested here).
• Windows without WSL2. The server itself builds on Windows (the project is developed there), but the helper servers and the commands on this page were run on Linux. Use WSL2 for them.
• Any host other than your own machine. A page opened from another computer is not a secure context for the microphone, so it needs HTTPS in front, and the server then needs credentials (BRISVOX_SESSION_SECRET): see Deploying in a container and Security. Do not expose the helper servers beyond loopback (see the sherpa-onnx note at the top of this page).

If it does not work

• check says a provider's feature is off. The binary was built without the adapter it names; rebuild with the --features of step 1.
• The first turn is empty or answered late. Look at the server log for the STT connection (ws://127.0.0.1:6007 must be the port sherpa-onnx runs on) and at smart-turn-ort in the build line. The sherpa-onnx notes ("First-turn check" in sherpa-onnx) explain the padding the adapter sends.
• Long silence before the first answer after a break. Ollama loading the model or Kokoro warming up; see the notes in step 2.
• Settings and keys of the agent file: Configuration.

The pipeline

A call is one session. The production pipeline (brisvox-engine, run_call) is a chain of stages connected by bounded queues; each call has its own chain, so calls share nothing but the inference pool and the provider connections' budgets.

transport -> AudioIn -> VadWorker -> SttStage -> TurnDriver -> LlmRunner -> SegmenterStage -> TtsStage -> TransportOut -> transport

A speech-to-speech model can replace everything between AudioIn and TransportOut with one stage; see Speech-to-speech models.

Rules the pipeline lives by

• No heavy work on async workers. Anything heavier than about 50 microseconds (VAD, the end-of-turn model, resampling in bulk) runs on the dedicated brisvox-inference pool.
• Every queue is bounded and has a documented overflow policy. Audio on the way in is lossy and counted (drop-oldest); control events are lossless; audio towards the caller applies backpressure.
• Every network wait has a timeout and every task is cancellable. Cancellation leaves state consistent.
• Time comes from an injected clock. That is what makes the simulations deterministic: a whole call runs on a paused clock, with mock providers, in milliseconds of real time.
• Latency is a budget, and it is measured. The engine's own added time is budgeted at 3 ms (turn end to LLM request), 2 ms (TTS audio to transport) and 1 ms (barge-in decision to Clear applied), at p95. See Benchmark results for the measured values.

Read more: Production pipeline design (stage by stage, with the queues and the failure policy) and Architecture (crates, frame flow, routing).

Turns and interruptions

Turns and epochs

Every user turn gets a number, its epoch. The turn driver is the only component that advances it. Bot-side frames (LLM text, TTS audio, playback marks) carry the epoch they were produced for; every stage on the bot side drops frames from a stale epoch. This is the one mechanism that keeps a late audio chunk, a late LLM token or a late tool result from leaking into the next turn.

Deciding that the caller has finished

A pure state machine (TurnMachine) with injected time decides when a turn ends. The policies:

• Adaptive (default). When the VAD sees the caller fall silent, two things start at once: the STT Finalize, and the Smart Turn model (an on-device end-of-turn classifier, run on the inference pool). If the model says the utterance is complete, the turn ends as soon as the STT final has arrived; if it says the caller is not done, the turn waits, with a fallback deadline (fallback_silence_ms) so an undecided pause cannot hang the call.
• Fixed. The turn ends after a fixed silence.

Because the turn end waits for the STT final (a "finals gate", bounded by a timeout), the added wait is the larger of the two, not their sum.

With speculation enabled, the LLM request is started at a candidate end of turn and committed only when the turn really ends; a read-only tool may run on a speculation, a side-effect tool is held until the commit. What this buys, and what it costs in extra requests, is measured in bench/results/speculation-fixtures.md (summarised in Benchmark results).

Barge-in

When the caller starts speaking while the bot is speaking, the turn driver judges the candidate interruption (the interruption policy: minimum words, backchannel lists such as "yeah" or "uh-huh" per language, an echo guard) and, if it is real:

1. starts the new epoch (an Interrupt always precedes the new UserTurnStarted);
2. sends Clear straight to the transport on a fast path, so queued audio is dropped and the client is told to flush what it buffered;
3. cancels the LLM round, the segmenter and the open TTS contexts;
4. cuts the context to what was actually played (Played-text truncation).

The budget for step 2, decision to Clear applied, is 1 ms at p95. After it, no stale audio reaches the wire.

Read more: "Turn-taking" in Architecture (the state diagram and the policies), sections 2 and 3 of the pipeline design (epoch ownership and the barge-in path step by step), and the interruption keys in Configuration.

Played-text truncation

When a caller interrupts, the LLM has already produced (and the TTS may have synthesised) more text than the caller ever heard. If the context kept the whole answer, the model would believe it had said things the caller never heard, and the next turn would be built on a conversation that did not happen.

brisvox's rule: after an interruption, the LLM context contains only what was actually played.

How it is known what was played

The transport reports what reached the caller:

• Marks. The engine ends every utterance with a mark; the client echoes it when the audio before it has played. A utterance whose end mark came back is kept whole.
• Playback positions. For a cut utterance, the transport reports how much audio it had released to the wire. The heard position is that position minus the client's playback lead (reported by the carrier where it can, e.g. Twilio, else a configured margin).
• Word timestamps. TTS providers that return word timings let the position be mapped to an exact word. For providers without them (for example Deepgram Aura) the engine falls back to a character-rate estimate and the cut is coarser.

The engine waits a short, clock-bounded time for these reports to settle (250 ms by default, counted from the barge-in), then cuts the assistant message at the heard word. Orphaned tool results are removed with the message that requested them, and the result is validated: a context that would break the LLM's message rules is a test failure, not a runtime surprise.

The text that was sent to the TTS is tracked as exact slices of the assistant text, so the cut is byte-accurate against what the LLM wrote, even when the TTS normalised numbers or abbreviations.

Read more: section 5 of the pipeline design (sources of truth and the procedure) and "Played-text truncation" in Architecture.

Tools

A tool is a function the LLM can call during a turn: look up an order, book a slot, transfer the call. brisvox's tool contract is built around the two things that go wrong in voice: a tool that runs when it should not, and a caller who is kept waiting in silence.

Kinds

• read_only tools only look things up. They may run on a speculative LLM start, they are cancelled when the caller interrupts, and running one twice is harmless.
• side_effect tools change the world (book, cancel, transfer, charge). They never run speculatively (they are held until the turn is committed and discarded if the speculation is cancelled), never run twice (the idempotency key is derived from the session, the turn epoch and the call id; a replay of that call returns the recorded result, and an identical call in a later response of the same turn is refused as already_done; a later turn or another call is not covered, so use your own idempotency key for rules such as "one refund per order, ever"), and are not cancelled by an interruption: they complete, are recorded, and the outcome is reported to the LLM on the next turn.

Lifecycle of a call

1. The LLM streams a tool call; the argument deltas are buffered until complete. Partial JSON never executes.
2. The arguments are validated against the tool's JSON Schema. A failure goes back to the LLM as a structured error, with bounded retries and then a spoken fallback.
3. Independent calls run in parallel; results are appended to the context in the order the LLM issued them.
4. If a tool has not answered after a delay (1.2 s by default, or the tool's own filler_after), the agent says a filler phrase so the line is not silent.

Where tools come from

• Built-in telephony tools: transfer_call, send_dtmf, end_call, over the carrier's REST call control (Telephony).
• In-process tools: Rust tools registered through brisvox_server::tools::AppTools; an agent file lists, by name, the ones the LLM may see. Your own binary is one line, brisvox_server::app::run_with_tools(Arc::new(MyTools)); examples/rust-tools is a complete project.
• Remote tools in your own process, through the Python or TypeScript SDK and the agent protocol.

Read more: the Tools reference (the contract, the tool engine, filler and interruption semantics, per-request LLM metrics) and Configuration (the tools key of an agent file).

Agent definitions (configuration)

TOML and YAML. Code: crates/brisvox-server/src/config/. Examples: examples/agents/*.toml and their YAML twins *.yaml (each one is loaded by the test config::tests::the_examples_are_valid, and config::yaml::tests::the_yaml_examples_are_twins_of_the_toml_ones checks that every twin reads into the same definition, so they cannot rot or drift).

One TOML or YAML file describes one agent: who it is (system prompt, language, tools by name), how turns and barge-ins are judged, and one provider per stage (STT, LLM, TTS) with its options. Absent keys keep the engine's and the provider adapters' documented defaults; the defaults live next to the code that uses them (EngineConfig::DEFAULT, XxxConfig::new), not in this file.

Loading

#![allow(unused)]
fn main() {
use brisvox_server::config::{self, ProcessEnv};

// Blocking file read: at startup, or inside spawn_blocking.
let agent = config::load_file(Path::new("examples/agents/support-en.toml"), &ProcessEnv)?;
// Only the tools the definition names (all must be registered): the LLM never sees the rest.
let tools = Arc::new(agent.tool_registry(&server_registry)?);
let engine = agent.engine();                   // EngineConfig, already validated
let stt = agent.stt()?;                        // SttProviderConfig::Deepgram(DeepgramConfig) ...
let llm = agent.llm()?;                        // LlmProviderConfig::OpenAi(OpenAiConfig) ...
let tts = agent.tts(clock, shutdown)?;         // TtsProviderConfig::Cartesia(CartesiaConfig) ...
let builder = agent
    .configure(SessionBuilder::new(engine, clock, timeline, offload, s, l, t)?)
    .with_tools(Arc::clone(&tools), Arc::new(ToolEngine::new(tools, /* ... */)));
}

load_file picks the format by extension: .yaml/.yml (any case) is YAML, anything else is TOML. load_str(text, source_name, &env) does the same for TOML text held in memory, and load_str_as(text, source_name, Format::Yaml, &env) for either format; parse / parse_as read the file format only (no cross-field checks, no secrets). Env is the secret source: ProcessEnv in production, a BTreeMap/HashMap in tests.

Loading has three steps:

1. Syntax and types. Every table rejects unknown keys (deny_unknown_fields): a typo is an error, never a silently ignored setting. Values are type- and range-checked while they are read. The first such error stops reading.
2. Cross-field checks (all reported together, in file order), see below.
3. Secrets. Each api_key_env names an environment variable; its value is read into a brisvox_core::Secret<String> (Debug/Display print [REDACTED]). A missing, empty or non-UTF-8 variable is an error naming the variable and the key, never a value. Surrounding whitespace (the trailing newline of an env-file or a mounted secret file) is trimmed; whitespace or control characters inside the value are an error. A key pasted into api_key_env by mistake (longer than 32 bytes, containing -, or mixing lower-case letters and digits) is never echoed: messages show its first 4 characters and its length, with a hint.

After that the mapped EngineConfig goes through EngineConfig::validate as a last net.

Errors

Every problem names the file, the line and column, the key path and what is wrong (the same key paths and messages for TOML and YAML; positions refer to the file as written):

invalid agent definition agents/tr.toml (3 problems)
  agents/tr.toml:4:12: `agent.language`: Deepgram Aura has no voice for `tr` (it speaks en, es, de, fr, nl, it, ja); use Cartesia or ElevenLabs for this language
  agents/tr.toml:21:15: `tts.sample_rate`: Deepgram Aura does not deliver PCM16 at 44100 Hz (8000, 16000, 24000 or 48000)
  agents/tr.toml:25:16: `tts.api_key_env`: environment variable `DEEPGRAM_API_KEY` (named by tts.api_key_env) is not set; secrets are read from the environment, never from the file

ConfigError { source_name, issues: Vec<Issue> }, Issue { key, position: Option<(line, column)>, message }; columns count characters, not bytes. The key path of a read error is found by walking the parsed document for the most specific key or value whose span contains the error position (toml's own error carries the span but does not expose its key path). The YAML reader tracks the key path itself while it reads. An api_key literal gets the hint to use api_key_env in both formats.

Checking a file

brisvox-server check <agent-file> [--require-secrets] validates a definition offline, before a deploy or inside CI. brisvox-server check --env does the same for the definition the environment names (BRISVOX_AGENT_DEFINITION, or the file BRISVOX_AGENT_FILE names). It runs the same loader the server runs at startup, so it reports every problem the server would refuse the file for, each with its key path and line and column. It opens no sockets, starts no runtime and makes no network call.

$ brisvox-server check agents/support.toml
error: agents/support.toml:17:1: `stt.deepgram.endpointing_msx`: unknown field `endpointing_msx`, expected one of ...
FAILED: agents/support.toml has 1 error

$ brisvox-server check agents/support.toml
warning: agents/support.toml:31:15: `llm.api_key_env`: environment variable `OPENAI_API_KEY` is not set; ...
OK: agent "support" (stt deepgram, llm openai, tts cartesia) (1 warning)

$ brisvox-server check agents/support.toml
error: agents/support.toml:17:10: `agent.tools[0]`: tool `lookup_order` is not registered by this binary, and the server refuses to start with it; ...
FAILED: agents/support.toml has 1 error

The exit status is 0 when the file has no errors (warnings do not count) and 1 when it has any. A wrong command line exits 2. Besides the errors the loader reports (unknown or misplaced keys, values out of range, a language or sample rate the provider does not support, a provider whose cargo feature is not compiled into this binary, with the feature to turn on), check reports:

check answers for the binary it runs in: a server built with fewer provider features than the one you deploy reports errors the deployed one would not, so run it with the build you ship. A binary of your own that embeds the server with its own tools (brisvox_server::app::run_with_tools, docs/TOOLS.md) has the same check command and knows those tools' names. In Rust, brisvox_server::check::check_file returns the report as data (errors, warnings).

Editor support (JSON Schema)

docs/agent.schema.json is a JSON Schema (draft 2020-12) of the agent file. With it an editor completes keys, shows each key's description from this reference, and underlines a typo, an unknown table, a number out of range, a wrong enumeration value or a URL with the wrong scheme while you type, before brisvox-server check runs. The schema is generated from the same Rust types the loader reads (deny_unknown_fields is additionalProperties: false; the ranges of the millisecond, count, real-number and sample-rate settings are minimum/maximum/enum; names, environment variable names, language tags and URLs are patterns). A test keeps the committed file equal to the generated one and every file in examples/ valid against it.

TOML, with Taplo (the "Even Better TOML" VS Code extension, the taplo CLI, Helix, Neovim): put the schema directive on the first line of the file,

#:schema ./agent.schema.json
[agent]
name = "support"

(a path relative to the file, or the URL https://raw.githubusercontent.com/bilal07karadeniz/brisvox/main/docs/agent.schema.json, once published), or bind it to all your agent files once in .taplo.toml:

[[rule]]
include = ["agents/**/*.toml"]
schema.path = "docs/agent.schema.json"

YAML, with the YAML language server (the Red Hat "YAML" VS Code extension, yaml-language-server in Neovim, Helix and others): a modeline comment on the first line,

# yaml-language-server: $schema=./agent.schema.json
agent:
  name: support

or, in VS Code settings.json, "yaml.schemas": {"docs/agent.schema.json": "agents/*.yaml"}.

brisvox-server --print-schema prints the schema of the binary you have, so a copy always matches its version. It needs the schema cargo feature; without it the flag is an error that names the feature. To regenerate the committed file after a change to the config types:

cargo run -p brisvox-server --features schema -- --print-schema > docs/agent.schema.json

What the schema cannot say stays with brisvox-server check, which remains the authority: the cross-field rules (turn.silence_ms is required with fixed_silence, confirm_tools must be listed in tools), the environment variables and the tools of your deployment, and the provider cargo features of the binary. Two small differences: the schema takes no null (the YAML reader treats an empty turn: or silence_ms: ~ as an absent key, and the schema flags it; leave the key out), and its length limits count characters where the loader counts bytes.

YAML

The same file in YAML (examples/agents/support-en.yaml is the twin of support-en.toml): every TOML table is a mapping, every [stt.deepgram] options table is a deepgram: mapping under stt:, and the keys, values, defaults and checks are identical.

agent:
  name: support-en
  language: en
  system_prompt: |
    You are the voice assistant of Example Shop. Answer in one or two short spoken sentences.
  tools: [lookup_order]

stt:
  provider: deepgram
  api_key_env: DEEPGRAM_API_KEY
  deepgram:
    model: nova-3
    endpointing_ms: 300

llm:
  provider: openai
  api_key_env: OPENAI_API_KEY

tts:
  provider: cartesia
  api_key_env: CARTESIA_API_KEY
  voice: replace-with-a-cartesia-voice-id

Rules:

• Scalars follow the YAML 1.2 core schema. true/false, integers (300, +5, 0x1F, 0o17), floats (0.7, 1e3) and null/~/nothing are typed; every other plain scalar and every quoted or block (|, >) scalar is a string. yes/no/on/off are strings, so enabled: yes is an error (invalid type: string "yes", expected a boolean), exactly as enabled = "yes" is in TOML. A voice id that looks like a number must be quoted (voice: "12345"); TOML needs the quotes anyway.
• Null is the same as leaving the key out. An empty turn: is an empty [turn] table; an empty backchannels: keeps the preset's phrase sets ([] turns them off). A required value left empty (voice:) is invalid type: null, expected a string.
• Not supported, each an error at its position: anchors (&x) and aliases (*x), tags (!!str, !x; quote the value instead), a second document (---), keys that are lists or mappings, duplicate keys (reported at the second one), nesting deeper than 16 levels.
• Positions: line and character column of the value (or of the key, for an unknown key or a problem of a whole mapping such as an options table for another provider). A byte order mark and Windows line ends are fine; a lone carriage return (classic Mac line ends) is an error at its position, as in TOML. Reading is linear in the file size, also for one long line.
• Syntax errors read YAML syntax error: <parser message> with the key path of the enclosing value.
• The parser is saphyr-parser (pure Rust, YAML 1.2, MIT OR Apache-2.0) behind the brisvox-server feature yaml, on by default. A build with --no-default-features reads TOML only and rejects a YAML definition with a message naming the feature.

File reference

Durations are whole milliseconds (*_ms). Ranges are inclusive.

[agent] (required)

[turn]

[interruption]

preset ("recommended" default, or "off"), then per-field overrides: min_speech_ms (0..=5000), min_words (0..=20), confirm ("all"/"any"), echo_guard_ms (0..=5000), echo_min_words (1..=20), backchannels (array of "en", "tr"; [] turns them off), backchannel_wait_ms (0..=5000), backchannel_max_speech_ms (0..=10000), vad_hangover_ms (0..=2000). Meanings: InterruptionConfig in crates/brisvox-engine/src/config.rs.

[speculation] and [early_analysis]

[speculation]: enabled (false), on_partial (true), partial_stable_ms (0..=60000, 0; at most max_age_ms: the stable-partial gate, the partial of a VAD stop is offered only after the caller stayed silent and the text did not change for this long), max_per_turn (1..=16, 3), max_age_ms (100..=60000, 5000), max_buffered_events (1..=4096, 256).

[early_analysis]: enabled (false; needs turn.policy = "adaptive"), fall_delay_ms (0..=1000, 64), max_tail_ms (1..=5000, 300), max_per_turn (1..=32, 4). The assembly applies the VAD half itself (SessionBuilder::with_vad).

[audio]

frame_ms (5..=100, 20) must be a whole number of samples at 16 kHz and at call_sample_rate; call_sample_rate (8000, 16000, 22050, 24000, 44100 or 48000; default 16000) is only the fallback for a transport that reports no rate (telephony transports report 8000 themselves).

[filler]

When a slow tool round is announced with a filler phrase (docs/TOOLS.md "Tool UX"): enabled (true), delay_ms (100..=10000, 1200: the same delay for every tool that has a filler), per_tool (false; true takes each tool's own filler_after, 700 ms unless the tool sets another, and cannot be combined with delay_ms). The session default is the fixed 1.2 s (why: docs/TOOLS.md, "Why the default is a fixed 1.2 s"). The phrases and their pre-rendered clips are set in code (SessionBuilder::with_filler_policy, with_filler_clips).

[recording]

What call recording keeps and for how long (docs/PRIVACY.md). Recording itself is switched on by the environment (BRISVOX_RECORDING_DIR; the directory is infrastructure, not an agent setting), and a key set here wins over the matching environment variable. The table without BRISVOX_RECORDING_DIR is a start error: a privacy setting is never silently ignored. TOML and YAML read it identically (recording: in YAML).

[recording]
audio = false
redact_kinds = ["email", "iban", "card", "phone"]
retention_days = 14

The merged result is checked like the environment's alone (something must be recorded; the retention must cover the longest recorded call).

Encryption at rest has no file key: BRISVOX_RECORDING_AGE_RECIPIENTS (age public keys, cargo feature recording-encryption) is environment-only, like the directory, because it belongs to the deployment and not to an agent. With it set, every file the table above governs is written as <name>.age (docs/PRIVACY.md, "Encryption at rest").

[telephony]

What the built-in telephony tools may do (docs/TELEPHONY.md). They exist only in a server with a carrier's call control (BRISVOX_CALL_CONTROL, docs/OPERATIONS.md); an agent lists the ones it uses in agent.tools like any other tool.

[telephony]
warm = true
destinations = [
  { name = "front_desk", number = "+15555550100", description = "the clinic's front desk" },
]

[telephony.voicemail]

For an agent that makes outbound calls (docs/TELEPHONY.md 6). The carrier's answering-machine detector classifies the answer, and the verdict reaches the call as the stream parameter answered_by or as a callback to the callback listener. A machine whose greeting ended is played message, then the call is hung up through the carrier; a person gets the normal conversation. A call that never gets a verdict (an inbound call) is not touched.

[telephony.voicemail]
message = "Hello, this is the clinic. Please call us back tomorrow."
on_unknown = "treat_as_human"

The bot speaks the message through the engine's say input, so it needs the call's engine to take lines: with an out-of-process agent (BRISVOX_AGENT_URL) the link owns that input and a machine verdict can only hang up.

[agent_link] (optional)

Where the out-of-process agent of this definition's calls listens (docs/AGENT_PROTOCOL.md). Without the section the server-wide BRISVOX_AGENT_URL applies.

[agent_link]
url = "wss://agent.internal/ws"       # wins over BRISVOX_AGENT_URL
token_env = "AGENT_TOKEN"             # default: BRISVOX_AGENT_TOKEN
# allow_insecure = true               # accept plaintext ws:// to a host outside the private networks
# caller_identity = true              # tell the agent process who is calling (telephony calls)

[[agent_link.routes]]                 # picked by name in a call's start message
name = "billing"
url = "wss://billing-agent.internal/ws"
token_env = "BILLING_AGENT_TOKEN"     # a route never gets the default token
# caller_identity = true              # a route has its own switch

url and every route url must start with ws:// or wss://. A plaintext ws:// URL whose host is not on a private network (loopback, RFC 1918, link-local, localhost, *.internal, *.local, a single-label service name; a resolver's search list can turn the last into a public name, so it is accepted with a one-time warning) is refused at startup unless allow_insecure = true (on the section, or on one [[agent_link.routes]] entry) or BRISVOX_AGENT_ALLOW_INSECURE=1 is set (docs/AGENT_PROTOCOL.md, "Transport and connection"); route names are 1 to 32 letters, digits, _ or -, each once, at most 32 routes. A named token_env that is not set fails the start. A call picks a route with the websocket start message's metadata key agent_route, or the TwiML parameter agent_route; a start message never carries a URL, and an unknown route falls back to the default process.

caller_identity (default false, or BRISVOX_AGENT_CALLER_IDENTITY=1 when the key is not set) sends the caller's number, the called number and the carrier's call id to the agent process in session.start.call for Twilio, Telnyx and SIP calls (docs/AGENT_PROTOCOL.md, "Caller identity"). A route has its own caller_identity and never inherits the section's or the environment's. The numbers are withheld while the server redacts phone numbers (docs/PRIVACY.md).

[stt], [llm], [tts] (required)

Each stage has provider, api_key_env and an optional options table named after the provider ([stt.deepgram]). An options table for a provider other than the chosen one is an error.

Options tables:

• [stt.deepgram]: model (nova-3), endpointing_ms (0..=10000, 0 = off, 300), utterance_end_ms (1000..=5000), smart_format (true), keyterms (<= 100), region (global/eu/au/india), base_url.
• [stt.assemblyai]: speech_model (universal-3-6-pro), region (edge/us/eu), keyterms (<= 100), format_turns, min_turn_silence_ms, max_turn_silence_ms (>= min), base_url.
• [stt.gladia]: model (solaria-1), region (us_west/eu_west), code_switching, vocabulary (<= 100), endpointing_ms (10..=10000), base_url.
• [stt.sherpa_onnx] (self-hosted, docs/providers/sherpa-onnx.md): base_url (ws://host[:port], default ws://127.0.0.1:6006; any host, no path), path (/), sample_rate (the model's rate, 16000), finalize_timeout_ms (100..=10000, 1500), finalize_padding_ms (0..=5000, 300: silence sent before Done, 0 for the C++ server). The model decides the language. A token (api_key_env) is only allowed over wss:// or to a loopback host.
• [stt.openai_realtime_stt] (docs/providers/openai-realtime-stt.md): dialect (openai, nim, speaches, vllm; default openai), base_url (default per dialect), path_and_query, model (required for speaches and vllm; OpenAI default gpt-live-transcribe), prompt (<= 4096 bytes), punctuation (NIM, true), delta_replaces, min_commit_ms (0..=2000), finalize_timeout_ms (100..=10000, 2000), sample_rate.
• [llm.openai]: model, reasoning_effort (disabled/low/medium/high/xhigh/max), max_output_tokens, parallel_tool_calls, service_tier, base_url.
• [llm.anthropic]: model, max_tokens (1024), effort (low..max), thinking (disabled/adaptive/between_tools/model_default), base_url.
• [llm.gemini]: model, thinking_level (minimal/low/medium/high), max_output_tokens, temperature (0..=2), base_url.
• [llm.openai_compatible] (required for that provider): preset (groq/together/fireworks/vllm/ollama/openrouter), or base_url and model; max_tokens, temperature (0..=2), reasoning_effort (sent as the request field of that name, e.g. none or low for a reasoning model that thinks by default), openrouter_order (OpenRouter provider slugs, sent as provider.order) with openrouter_allow_fallbacks (provider.allow_fallbacks; false = served by the listed provider or refused). Both are OpenRouter-only: setting either one without preset = "openrouter" or a base_url whose host is openrouter.ai (or a subdomain) is a configuration error (brisvox-server check prints it with the line of the key and exits 1), because any other server would silently ignore the pin or refuse the request. A hosted service without a preset is this table with base_url and model. OpenRouter has the preset openrouter (base_url = "https://openrouter.ai/api/v1", default model openai/gpt-6-luna): preset = "openrouter", optionally model = "<author>/<model>" (the id from OpenRouter's model page) and api_key_env naming the variable that holds your OpenRouter key; the full recipe is "OpenRouter" in docs/PROVIDERS.md.
• [tts.cartesia]: model (sonic-3.6), max_buffer_delay_ms (0..=5000), url.
• [tts.elevenlabs]: model (eleven_flash_v2_5), stability, similarity_boost, style (0..=1), speed (0.7..=1.2), use_speaker_boost, url.
• [tts.deepgram_aura]: speed (0.7..=1.5), url.
• [tts.openai_speech] (required for that provider; a local server speaking POST {base_url}/audio/speech, docs/providers/openai-speech.md): base_url (required, with the /v1 prefix; http:// to any host is accepted, but not together with an api_key_env), preset (generic default, kokoro, chatterbox, speaches, vllm_omni; sets the model, the audio format and the request fields), model (required for generic), speed (0.25..=4), format (pcm or wav), first_audio_timeout_ms (500..=120000, default 15000), warm_text (text of the background model warm-up request started at call start, audio discarded; "" = off; default "Hi." for kokoro, off for the other presets), warm_interval_ms (1000..=3600000, 60000: at most one warm-up per interval across all calls). The server delivers 24 kHz: leave tts.sample_rate unset or set it to exactly 24000 (the example agents under examples/agents/local/ set it, which is the same thing written out); any other value is a load error, because only the speaches preset can resample on the server. The engine resamples 24 kHz to the call's rate itself. examples/agents/local-kokoro.toml is a complete agent.

Secondary providers ([stt.secondary], [llm.secondary], [tts.secondary])

Optional. A second provider of the same stage that calls fail over to when the primary is down (the mechanism is described in docs/PIPELINE.md, "Resilience layer"): a circuit breaker per provider is shared by all calls, a failed connect or a session that dies is retried on the other provider within the call's and the process's retry budgets, and an LLM request that failed before any content is re-issued to the secondary. Without a secondary every call still runs behind the breaker, the retry budgets and the TTS idle refresh; it just has nowhere to go.

A secondary table takes the same keys as its stage (provider, api_key_env, the options table named after the provider; voice for TTS), so it can be a different provider or the same one with another key or region. These keys belong to the call and come from the primary's table, so a secondary may not set them: language (STT, TTS), sample_rate (TTS), max_tool_rounds and context_window_tokens (LLM), and secondary itself. A TTS secondary needs its own voice: a voice id belongs to one provider, and the engine's voice id is the primary's. The secondary is checked like a primary against the call's language and rate (for example, a Turkish call cannot name a secondary Deepgram Aura voice, and Aura must deliver the primary's sample_rate).

Its key is read from its own api_key_env at startup: a missing key stops the start like a primary's. Keys are never in the file. examples/agents/failover-en.toml (and .yaml) shows all three:

[stt]
provider = "deepgram"
api_key_env = "DEEPGRAM_API_KEY"

[stt.secondary]
provider = "assemblyai"
api_key_env = "ASSEMBLYAI_API_KEY"

[tts.secondary]
provider = "elevenlabs"
api_key_env = "ELEVENLABS_API_KEY"
voice = "voice-id-at-elevenlabs"

Endpoint overrides are checked while the file is read, at the value's position, with the rule the adapter applies when it is built: Deepgram and AssemblyAI STT base_url and every TTS url are WebSocket URLs (wss://), Gladia STT and every LLM base_url are HTTP URLs (https://). The plain scheme (ws://, http://) is accepted only to a loopback host (localhost, 127.0.0.x, ::1), since the API key would otherwise travel unencrypted. Messages never repeat the URL (it may carry credentials). Path and query rules (some adapters take a base URL without a path) are still checked by the adapter.

Not exposed on purpose: STT/TTS audio encodings (the engine always sends 16 kHz PCM16 to STT and expects PCM16 from TTS, resampling at the edges) and the adapters' internal timeouts and replay settings (their defaults are tuned in the adapters; change them in code if needed).

Language subtags: Deepgram STT receives the tag as written (tr-TR is accepted there); AssemblyAI, Gladia, Cartesia and ElevenLabs receive the primary subtag (tr).

WebRTC reachability (environment variables)

Not part of the agent file ([turn] above is turn-taking, unrelated to TURN relays): these are process environment variables read by brisvox-server with the webrtc feature, next to the BRISVOX_WEBRTC_* ones in docs/OPERATIONS.md. How to choose and deploy: docs/DEPLOY.md "WebRTC: making the server reachable from browsers"; protocol facts and sources: docs/providers/webrtc.md section 11. A bad value refuses to start and names the variable.

Library-level knobs of the server's relay (RelayConfig, no environment variable): max_permissions (8: offer IPs a permission is created for), queue (20 packets per direction, 400 ms of audio, drop-oldest; 8 to 4096), allow_local_peers (false: loopback and link-local offer IPs get no permission; tests only), max_frame (4096: a larger or malformed frame from the TURN server ends that allocation), write_timeout (2 s), release_timeout (1 s: the Refresh of lifetime 0 at call end) and extra_roots (DER certificates trusted next to the compiled-in webpki roots, for a private TURN CA). Counters: relay_* in WebRtcStats (including the queue dwell and slow-write high-water marks). The TURN client crates (turn_client_proto, stun_proto, turn_types) are held at warn whatever RUST_LOG says; BRISVOX_LOG_TURN_CLIENT=1 lifts that (debugging only: at trace they log whole STUN messages with the nonce and the response's integrity HMAC). The SIP stack (rsipstack) is held at warn the same way (it logs whole SIP messages at info, SDES SRTP master keys included); BRISVOX_LOG_SIP_STACK=1 lifts it (docs/TELEPHONY.md, "SIP over TLS and SRTP"). The log writer also removes the key of any SDES a=crypto:... inline:<base64> line, whoever wrote it. The SIPS idle timeout (BRISVOX_SIP_TLS_IDLE_TIMEOUT, seconds, default 300, 0 = off) and the SRTP authentication-failure limit (BRISVOX_SIP_SRTP_AUTH_FAIL_LIMIT, per call and second, default 50, 0 = off) are in docs/OPERATIONS.md; library defaults are SipTlsConfig::idle_timeout and SipConfig::srtp_auth_failure_limit.

Library-level knobs (no environment variable, defaults in WebRtcConfig): turn.cache (60 s, at most half the TTL) and turn.fetch_timeout (5 s) for the credential fetch. POST /whip waits at most 1.5 s for credentials (a provider outage cannot stall an offer: it gets the last credentials that still have a quarter of their life left, or none); GET /whip/ice waits the full fetch timeout.

Which endpoint hands out credentials. The bundled pages read GET /whip/ice before createOffer, because the Link: rel="ice-server" headers of the WHIP 201 arrive after the offer is built (a page that wants them must create a second peer connection). The Link headers are there for standard WHIP clients (RFC 9725 section 4.6).

Security: who may mint relay credentials. Both endpoints issue credentials to whoever asks. Without BRISVOX_WEBRTC_TOKEN or BRISVOX_SESSION_SECRET (allowed only on a loopback address or with BRISVOX_INSECURE_LISTENERS=1), anyone who can reach the signaling port can obtain TURN credentials: for coturn they are computed locally and valid for the whole TTL, and every byte relayed with them is yours (bandwidth cost, abuse as an open relay for that TTL). GET /whip/ice is rate limited per client address (a burst of 5, then one request per 2 s; IPv6 clients by /64; 429 with Retry-After), which bounds minting but does not authenticate it. For coturn a request that carried a session token gets the username <expiry>:<label> with the label the first 16 hex digits of SHA-256 of the token's sid, so relay traffic in coturn's logs traces back to the session your backend issued; without a session token the label is a random id. Cloudflare and Twilio credentials are fetched once and shared by every caller for the cache period (60 s): the provider cannot tell callers apart, and a visitor who copies them can use them until they expire. Use coturn when relay usage must be attributable. When relay traffic costs money, set BRISVOX_WEBRTC_TOKEN (the page then needs the token, so serve it from your own backend), keep the TTL short, and use the provider's usage caps. Behind a reverse proxy every client has the proxy's address: the limiter then applies to all of them together, so put the limit at the proxy as well.

Process environment: security

Authentication and flood limits are infrastructure, not agent settings, so they are environment variables of the server process, not keys of the agent file. They are all described in docs/SECURITY.md and listed in docs/OPERATIONS.md:

A session token's agent and meta claims arrive in the call's metadata (session.agent, session.meta.<key>); the agent file is chosen by BRISVOX_AGENT_FILE as before.

The agent definition from the environment

A host that takes environment variables but no file mount (a one-port PaaS such as Railway) can carry the definition itself in BRISVOX_AGENT_DEFINITION: the text of the TOML file. It goes through the same loader as the file (same 1 MiB limit, same checks and messages; errors say $BRISVOX_AGENT_DEFINITION:LINE:COL), and it is mutually exclusive with BRISVOX_AGENT_FILE (both set is a startup error). BRISVOX_AGENT_FORMAT=yaml says the text is YAML (default toml; the format is named, never guessed). Secrets still do not go into it: the definition names the variables that hold them with api_key_env, and those are variables of their own. The operating system limits one variable well below 1 MiB (about 128 KiB on Linux, about 32 KB on Windows); an agent definition is a few kilobytes.

BRISVOX_AGENT_DEFINITION='
[agent]
name = "demo"
language = "en"
system_prompt = "You are a helpful voice assistant."
[stt]
provider = "deepgram"
api_key_env = "DEEPGRAM_API_KEY"
[llm]
provider = "openai_compatible"
api_key_env = "OPENROUTER_API_KEY"
[llm.openai_compatible]
preset = "openrouter"
model = "openai/gpt-6-luna"
reasoning_effort = "none"
[tts]
provider = "cartesia"
api_key_env = "CARTESIA_API_KEY"
voice = "a-cartesia-voice-id"
'

brisvox-server check --env validates what the server would start with (the variable, or the file BRISVOX_AGENT_FILE names) and prints the same report as check <file>.

Port placeholder in listener addresses

The variables that bind a listener (BRISVOX_WS_ADDR, BRISVOX_TWILIO_ADDR, BRISVOX_TELNYX_ADDR, BRISVOX_RTVI_ADDR, BRISVOX_SIP_ADDR, BRISVOX_SIP_TLS_ADDR, BRISVOX_WEBRTC_ADDR, BRISVOX_WEBRTC_UDP_ADDR, BRISVOX_WEBRTC_TCP_ADDR, BRISVOX_CALLBACK_ADDR, BRISVOX_HEALTH_ADDR) accept the exact token ${PORT}, replaced by the value of the PORT variable that PaaS hosts set: BRISVOX_WS_ADDR=[::]:${PORT}. Nothing else is expanded ($PORT and ${port} are not). If the token is used and PORT is unset or not a number from 1 to 65535, the start fails with a message naming both variables.

Cross-field checks

The provider facts behind these rules come from docs/providers/*.md (fetched 2026-10).

Provider features

brisvox-server features provider-deepgram, provider-assemblyai, provider-gladia, provider-sherpa-onnx, provider-openai-realtime-stt, provider-openai, provider-anthropic, provider-gemini, provider-openai-compatible, provider-cartesia, provider-elevenlabs, provider-deepgram-aura, provider-openai-speech, and all-providers. None is on by default (light builds); a definition naming a provider whose feature is off is rejected with the feature to enable. SttProviderConfig / LlmProviderConfig / TtsProviderConfig have one variant per compiled adapter.

Why TOML is the reference and how YAML is read

TOML came first: the definition types carry toml::Spanned positions for the cross-field checks, so YAML needed its own span story, not just a second from_str. YAML is read like this:

• The serde_yaml successors (checked on crates.io 2026-10-13: yaml_serde 0.10.7 by The YAML Organization, MIT OR Apache-2.0, last release 2026-08; serde_yaml_ng 0.10.0, MIT, last release 2024-05; serde_norway 0.9.42, last release 2024-12; serde_yaml itself 0.9.34+deprecated) are serde-only: a position appears in an error but never on a value, so a cross-field check (Turkish on Aura at agent.language) could not say where the value is. They also cannot fill Spanned.
• saphyr-parser 0.2.1 (MIT OR Apache-2.0, pure safe Rust, YAML 1.2, active: releases 2026-07 to 2026-10) emits events with line and column. config::yaml builds a small tree with byte ranges from them and runs the derived Deserialize of AgentFile over it; Spanned<T> is filled through serde_spanned::de (the same crate toml::Spanned comes from, already in the tree). So both formats produce the same AgentFile, and the cross-field checks, secret lookups and mappings are shared code with shared messages; parity tests load each broken TOML definition next to its YAML form and compare key paths and messages.

Telephony: DTMF, call transfer, answering machines

Protocol facts live in docs/providers/call-control.md (Twilio and Telnyx REST, fetched and fact-checked 2026-10-08). This page is the design and the wiring: what was built, where it lives, how an application connects it, and what is still unverified. Anything marked UNVERIFIED is a provider behavior the documentation does not state; the code handles the possibilities defensively and the live tests settle them.

1. Where the code lives

Decision: a module of the transport crate, not a new crate. It is the same kind of thing as the Twilio media adapter (a provider protocol for a call), it shares the crate's error and feature conventions, and a new crate would add a manifest and nothing else. The agent tools depend only on the TelephonyOps trait object, never on transport; transport depends on agent for the shared vocabulary, which the crate graph allows (agent is below transport). The TLS setup (rustls with ring, webpki roots) is a 15-line copy of brisvox_providers::net::tls_config so transport does not depend on its sibling, the providers crate. If a third consumer appears, move it to core.

2. DTMF in

provider "dtmf" message
  -> WireEvent::Dtmf (transport adapter: Twilio dtmf.digit, Telnyx dtmf.digit)
  -> TransportEvent::Dtmf { digit, at }              (session)
  -> DataFrame::Dtmf(DtmfFrame { epoch: 0, digit, at })   (engine pump, lane "dtmf")
  -> TurnDriver re-tags epoch, forwards downstream
  -> LLM runner: DtmfCollector::push(digit, at)
       -> Collected { digits, reason: Terminator | MaxDigits | Timeout }
       -> context.push(dtmf_message(&digits, language))   // a user message
       -> next LLM round

DTMF never goes through STT. The runner arms a timer for DtmfCollector::next_deadline() on the injected clock and calls poll(now) when it fires, so a half-typed entry is flushed (the engine rule: every wait has a timeout). The note is [The caller pressed the keys: 1 2 3 #] (Turkish: [Arayan şu tuşlara bastı: 1 2 3 #]); digits are the only variable content, so it cannot carry an injection. Whether a key press interrupts the bot is the application's interruption policy; the helpers only shape text. The runner side (feeding the collector, arming the timer) is up to the engine.

Twilio only sends dtmf on bidirectional streams, inbound direction, with no duration or timestamp; whether the tone audio is also in the media payload is UNVERIFIED. Telnyx sends dtmf.digit and an optional occurred_at (order by it; frames may arrive out of order).

Ordering is the transport adapter's job. DtmfFrame carries only at (receive time), not occurred_at, and the collector only sees frames in the order the pump delivers them. The Telnyx media adapter must therefore emit dtmf frames in occurred_at order (a short reorder buffer keyed by occurred_at/sequence_number) and stamp at accordingly; this is an open requirement for that task, not something the agent crate can repair. The collector is robust against a non-monotonic at (it never moves the inter-digit deadline backwards).

A lone terminator is an entry. # (the default terminator) or * pressed with nothing pending ("press # to skip") completes an entry of its own, CollectReason::LoneTerminator, whose only key is the terminator, so a caller who skips or goes back reaches the model. DtmfCollectorConfig::report_lone_terminator = false drops it instead.

3. DTMF out

In-band synthesis of the two-tone waveform as media frames is a documented alternative whose far-end behavior is carrier-dependent and unverified; it is future work (call-control.md 1.4).

send_dtmf tool: SideEffect, digits validated against [0-9A-Da-d*#wW]{1,32} (schema pattern and DtmfString), lowercase a-d normalized, at least one real key. The Debug form of a digit string prints only its length (it may be a PIN).

4. Transfer

Tool

transfer_call { destination, mode?, summary?, reason? }, SideEffect.

Transfer by an out-of-process agent. The agent process of docs/AGENT_PROTOCOL.md sends a transfer command (E.164 number, cold or warm): it is trusted like the operator (it holds the application logic), so the number comes from it and not from the destination list. It runs through the same call binding as the tool (CallOps), including the hand-off after a cold transfer and the warm-transfer gate ([telephony] warm, callback listener); the call gets this binding even when the definition names no telephony tool.

• The model never produces a number. destination is an enum of the names in TelephonyPolicy (sales, duty_manager), each mapped to an E.164 number in configuration. Prompt injection cannot reach a premium-rate number. No destination configured: the tool is not registered. Numbers appear in no prompt, tool result or log (PhoneNumber debug-prints +90******33).
• mode: cold (default) or warm (only offered when TelephonyPolicy::with_warm(true)).
• One transfer per call. A second call is refused while one runs or was accepted. A definite failure (Rejected, Unavailable, InvalidArgument) releases the claim so the model can try another destination; OutcomeUnknown keeps it and tells the model not to repeat it.
• The hand-off sentence is played first. The tool awaits TelephonyOps::settle_speech() (bounded by settle_timeout, default 8 s, on the injected clock), then asks for the transfer. The application implements settle_speech from the engine's play-out marks (TransportEvent::MarkPlayed); BoundCall::with_settle takes the function.
• The tool timeout covers the whole chain. TelephonyPolicy::effective_transfer_timeout() is settle_timeout + provider_budget + 2 s (default 8 + 40 + 2 = 50 s). The provider budget is four sequential requests at the transport's default 10 s deadline, the longest chain (Telnyx: refused conference command, stream stop, repeat, dial; Twilio: park, create agent leg, roll back). Set provider_budget to requests * request_timeout when the REST deadline is changed; an explicit transfer_timeout is used as given (a shorter one can answer the model "timed out, do not repeat" for a transfer that then succeeds).
• The idempotency key (ToolCallCtx::idempotency_key().digest()) reaches every request as the Telnyx command_id; the engine's store replays the recorded result for a repeated call id.
• Result: {status: "initiated", mode, destination, summary_delivered, instruction}. After initiated a cold transfer ends the bot's part of the call.

Cold transfer

• Twilio: update the call with <Response><Dial callerId=".." answerOnBridge="true" timeout="30" action="..">+90..</Dial></Response> (callerId/action only when configured). Twilio ends the call after the <Dial>; the dial outcome reaches only the action URL of the user's HTTP app.
• Telnyx: POST .../actions/transfer with to, optional from, timeout_secs, command_id. If refused with 90045 the binding issues streaming_stop and repeats the command once under the command id ...r1 (the refused one was not applied). The stream is not restarted if the retry fails (stop_stream_on_conflict = false disables the whole retry). A retry that fails after the stop succeeded is Error::StreamStopped { cause } (an unknown outcome as far as the model is concerned): the bot's stream is gone, so the tool must not say "nothing was done, the call continues with you". The transfer tool keeps its claim and tells the model not to repeat; the application hangs the caller up or moves them on. A failing streaming_stop itself is reported as it is (the stream is then still up).
• The host's media adapter must not take the stream that ended because of that streaming_stop for the end of the call. TelnyxConfig::on_stream_stop is a hook (StreamStopHook) called with the call right before the binding sends streaming_stop (once per conflict), so the host can mark that stream as stopped on purpose in the media adapter (the adapter's own API lives in docs/providers/telnyx.md); the binding itself has no dependency on the adapter.

Warm transfer (conference based)

Twilio (TwilioCallControl::transfer_warm), all on one background task (see "Cancellation"):

1. Update the caller's call: <Dial><Conference startConferenceOnEnter="false" endConferenceOnExit="true" beep="false" participantLabel="caller" [waitUrl]>brisvox-<key></Conference></Dial>. The caller waits (hold music or conference_wait_url); the bot's stream ends (UNVERIFIED how, see 7).
2. Create a call to the destination (From = caller_id, required) whose TwiML is only a silent <Pause> of agent_accept_window_secs (default 120, in pauses of at most 60 s). The agent leg is not in the conference and nothing is read to it. StatusCallback events initiated ringing answered completed when configured, and AMD parameters when agent_leg_amd is set (the sync verdict is readable with TwilioCallControl::call_status once the leg is answered, answered_by; with async_amd it arrives at the callback URL).
3. complete_warm is the accept gate. When the application has seen the agent leg answered by a person (AMD verdict, status callback), complete_warm updates the agent leg with [<Say language=..>summary</Say>]<Dial><Conference startConferenceOnEnter="true" endConferenceOnExit="false" ..>brisvox-<key></Conference></Dial>: the agent hears the summary (the caller does not), joins, and the two meet. A voicemail on the agent's phone is never joined to the caller and never hears the summary: if the application does nothing, the leg ends when the pause ends. (A <Gather> accept prompt, as call-control.md 1.5.2 suggests for the no-conference shape, would need a webhook, which brisvox does not serve; the REST step makes the application's decision explicit instead.) The agent leg must be answered: an update of a ringing call is rejected by Twilio.
4. abort_warm (no answer, declined, voicemail) ends the agent leg (Status=completed) and then resumes the caller through ResumeStream; it stops at the first error so a retry repeats it safely, and returns where the caller was left (Resumed, or Parked without a resume stream). The agent leg counts as ended when the update succeeds, when Twilio answers 404, or when it answers another 4xx (not 401/403) and a read of the leg (GET) shows a final status (completed, busy, failed, no-answer, canceled): a leg that already ended on its own (no answer, busy) is the usual case, and the error Twilio gives for updating a finished call is UNVERIFIED, so the leg is read instead of trusting one status code. A queued or ringing leg is ended with Status=canceled (the status Twilio documents for it) after completed was refused. If the leg is still live (or unreadable) the original refusal is returned and the caller is not resumed behind it; every retry repeats the same sequence.
5. If step 2 fails definitively (4xx), the caller is put back on the bot through ResumeStream (resume = warm_failed); Error::WarmFailed says where the caller was left. If its outcome is unknown (timeout, dropped connection, 5xx; also a failed step 1) the caller is not resumed behind a leg that may exist: the error reports Parked and carries a recovery handle (WarmFailed::transfer: the conference, no agent leg) that BoundCall keeps for abort_warm. The possibly existing leg only rings and then ends after its pause (nothing joins it to the empty conference); its SID is unknown, look it up in the console if it matters. The whole TwiML (including the later join, with the summary) is checked against the 4000-character limit and the caller id before step 1, so a bad request touches nothing.

Telnyx (TelnyxCallControl::transfer_warm; needs connection_id and caller_id):

1. POST /conferences with the caller's leg (and hold_audio_url; without it the caller hears silence while waiting): needs data.id in the response (the response shape is not on the fetched pages; a missing id is Error::Protocol). A 90045 here triggers the same stop-and-retry as the cold transfer (tested: conferences, streaming_stop, conferences). If the retry fails after the stop succeeded, the error is WarmFailed { Parked } wrapping Error::StreamStopped, without a recovery handle (no conference id is known): the caller's stream is gone and the application must act.
2. POST /calls (dial) with link_to the caller's leg over connection_id, optional AMD fields. Failure (or a dial answer without a leg id) leaves the caller parked in the conference: WarmFailed { Parked } with a recovery handle (the conference id, no agent leg) that BoundCall keeps.
3. When the application sees call.answered for the agent leg and the AMD verdict says a person, it calls complete_warm, which joins the agent leg to the conference. Until then the agent leg is not in the conference.
4. abort_warm hangs up the agent leg (if there is one) and reports CallerState::Parked always: the stream was stopped to make the conference command possible and cannot be restarted from here, so there is no way back to the bot. The application must hang the caller up (or move them on) itself; the state is returned instead of an Ok(()) that would hide it. An outcome-unknown dial may have created a leg whose id is unknown; it is never joined (the join is explicit), but an answered one stays up until its far end hangs up.
5. The summary cannot be delivered (the speak / playback_start commands were not fetched): the report says Briefing::NotSupported and the tool result summary_delivered: false.

BoundCall and the warm-transfer handle: the REST steps and the recording of their result run on one spawned task, so a tool task that is aborted after the caller was moved cannot lose the handle. BoundCall::warm_transfer() returns it (after a half-failed transfer: the recovery handle). complete_warm() forgets the transfer once the provider accepted the join; abort_warm() forgets it only after the provider confirmed the abort, so after a timeout or a 5xx the call can be repeated, and returns the CallerState. Without a transfer, abort_warm does nothing and reports Unchanged.

Both providers deliver the later events (agent answered, declined, hung up) as callbacks that the transport crate does not serve (scope boundary in twilio.md). The application's HTTP app receives them and calls BoundCall::complete_warm() / abort_warm(); Twilio status callbacks carry CallSid, CallStatus, Telnyx webhooks data.event_type (call.answered, call.hangup, ...), deduplicated on data.id. The server binary serves the endpoints that finish a transfer (section 5, "Warm transfers in the binary"): the application's HTTP app calls them instead of linking BoundCall.

Rules every REST call follows

Deadline on the injected clock around send + body (default 10 s, connect 3 s; a server that sends headers and then stalls, or streams an endless body, ends at the deadline or at the 64 KiB body cap, both tested; a test with a clock that runs 1000 times faster than real time proves the deadline comes from the injected Clock and not from tokio::time); no redirects (a 302/307 answer is an error after exactly one request, tested), no proxy; http:// only on loopback; credentials as Secret, header values sensitive, never in an error or Debug; the request URL (account SID, call id, conference id) is stripped from transport errors (reqwest::Error::without_url), because the error text reaches the model as a tool result and the logs; provider error text is stripped of control characters, cut to 200 characters (tested with a 5000-character reply on both providers) and dropped for 401/403. No automatic retry except the one Telnyx 90045 case: a timeout or a dropped connection may mean the command was applied (Error::outcome_unknown()), and the tool reports "do not repeat". After a Twilio timeout use TwilioCallControl::call_status before anything is repeated.

Cancellation

Warm transfers run their steps on their own tokio task, and BoundCall::transfer records the resulting handle on that task too: dropping the caller's future (the tool engine's backstop, a session end) does not leave the caller half-moved between the REST steps, and does not lose the handle that complete_warm and abort_warm need (a test drops the tool future after step 1 and finds the handle). Every step has a deadline, so the task is bounded. What the REST sequence cannot do is keep the caller off the conference when the whole process dies between steps; that is the application's recovery (the conference name brisvox-<key> is deterministic). SideEffect tools are not dropped by the engine for a timeout or an interruption anyway.

5. Wiring an application

#![allow(unused)]
fn main() {
let control = Arc::new(TwilioCallControl::new(twilio_config, clock.clone())?);
let call = CallRef::new(call_sid)?;                       // CallInfo.metadata["call_sid"]
let bound = Arc::new(BoundCall::new(control, call).with_settle(settle_fn));

let ops: Arc<dyn TelephonyOps> = bound.clone();
let caps = bound.capabilities();
let policy = TelephonyPolicy::new()
    .destination("sales", "+905551112233", "the sales team")?
    .with_warm(caps.warm_transfer)
    .with_dtmf(caps.send_dtmf);             // false for Twilio unless adapter_resumes_session
let mut registry = ToolRegistry::new();
register_telephony_tools(&mut registry, &ops, &policy, &clock)?;

// after each response was played:
if bound.hangup_requested() { /* send TransportCommand::Stop after the farewell mark */ }
// from the HTTP app's callbacks:
bound.complete_warm().await?;                       // the agent is a person: join
let left = bound.abort_warm().await?;               // CallerState::{Resumed, Parked, ..}
}

end_call records the request (hangup_requested()); the model says one goodbye sentence next and the application ends the call after that sentence's utterance-end mark, as in the Twilio adapter's "Hang-up" rule. BoundCall::hangup (REST) is for transports whose stream cannot end the call.

In the server binary

brisvox-server wires all of this itself (cargo feature call-control, brisvox_server::tools::telephony), from BRISVOX_CALL_CONTROL=twilio,telnyx and the definition's [telephony] section (docs/OPERATIONS.md, docs/CONFIG.md):

• Which call. The transport session records the call's Started info (TransportSession::call_started); the tools bind to the carrier call the first time they act (Twilio call_sid, Telnyx call_control_id, chosen by the transport metadata). A call on a listener without a configured carrier (generic websocket, RTVI, SIP) has the same tools: transfer_call and send_dtmf answer Unsupported ("not available on this call"), end_call ends the call through the transport. So a definition's tool set does not depend on the listener.
• settle_speech follows the call's engine events (EngineEvents, the RTVI bridge's ring when it has one): it returns once the bot is not speaking and produced nothing for 1 s, bounded by the policy's settle_timeout (8 s).
• end_call: the runner waits for the end of the next bot speech (the farewell; at most 10 s), hangs up through the carrier when the call has one (bounded at 12 s, abandoned when the session is cancelled; a failure is logged) and stops the call. A farewell the model speaks in the same response as the end_call call counts: the engine reports the end of a response's speech once per response, after its tool loop, so after the tool ran. A response that says nothing ends its speech at once, so a silent end_call hangs up right away.
• send_dtmf is offered only when every configured binding can send tones: Telnyx always, Twilio when the server also hosts the Twilio listener (below).

Streams that end on purpose

Two REST operations end the bot's media stream while the call goes on: Twilio's TwiML update (DTMF and the first step of a warm transfer replace the call's TwiML, which ends the <Connect><Stream>; the new TwiML starts a new stream) and Telnyx's streaming_stop before a transfer retry (error 90045). Left alone, the media adapter reads the old stream's stop or close as the caller hanging up, ends the engine's session and the tool call in flight with it. The binary wires both sides:

• Twilio. HostSettings::stream_links() gives the call control the Twilio listener's StreamResumer (a late-bound cell, filled when the listener binds) and the stream URL, the listener's BRISVOX_TWILIO_PUBLIC_URL as wss://. The Twilio binding then has a ResumeStream (resume parameter dtmf or warm_failed), adapter_resumes_session = true (so send_dtmf is offered) and on_stream_restart, which announces the stream's end to the adapter right before the REST update. The adapter (brisvox_transport::twilio, module docs "Streams that end on purpose and come back"): for 30 s after the announcement a stop, a close frame or a vanished socket of that call is the host's doing; the engine gets no hang-up, its session is parked, and what it says meanwhile (up to a minute of audio) is held for the new stream, a barge-in clear dropping it. A stream of the same callSid whose start carries the resume parameter is handed to the parked session (it may arrive before the old stream finished closing). A session nobody resumed within the announced time (DTMF 30 s; a warm transfer: the agent leg's accept window + ring time + 60 s, at most 15 min) ends as a disconnect; a resume stream nobody expects is refused (1008). The resumed stream passes the same signature check and the same admission gate as any other: at the call limit it is refused like a new call (keep headroom in BRISVOX_MAX_SESSIONS).
• Telnyx. on_stream_stop announces the streaming_stop to the Telnyx listener's StreamStopper (Wiring the Telnyx stream stop, section 7): the close is not a hang-up, the session stays up (at most STOPPED_LINGER, 120 s) and the retried transfer completes.

After a cold transfer returns, the call has left the bot: the runner stops the session without hanging the call up (it would drop the transferred call). The same for a completed warm transfer.

Warm transfers in the binary

[telephony] warm = true in the definition offers transfer_call with mode = "warm", when the callback listener runs (BRISVOX_CALLBACK_ADDR) and every configured binding can do one (Twilio: BRISVOX_TWILIO_CALLER_ID; Telnyx: BRISVOX_TELNYX_CALLER_ID and BRISVOX_TELNYX_CONNECTION_ID); otherwise the server warns at startup and offers cold transfers only. The tool starts the transfer (caller to a conference; receiving party called). The rest is two requests to the callback listener (docs/OPERATIONS.md, "Callback listener"):

• POST /v1/calls/{carrier}/{call}/warm/complete: the receiving party accepted. The listener calls BoundCall::complete_warm (Twilio: the agent leg reads the summary and joins the conference), then the runner stops the bot's session without a hang-up.
• POST /v1/calls/{carrier}/{call}/warm/abort: the receiving party did not answer, declined or is a machine. BoundCall::abort_warm ends their leg; on Twilio the caller goes back to the bot's stream (the parked session continues) and the bot says so (a fixed line in the agent's language, en or tr); on Telnyx there is no way back (CallerState::Parked) and the call is hung up.

The decision to accept belongs to the application: it watches the receiving leg (Twilio BRISVOX_TWILIO_STATUS_CALLBACK, AMD, its own phone logic; Telnyx webhooks) and calls one of the two. A transfer nobody finishes is cleaned up when the call's session ends: the server aborts it and hangs the caller up, so the caller is never left in a conference alone. Telnyx's session survives the missing stream for STOPPED_LINGER (120 s): finish a Telnyx transfer within that.

Caller identity for the agent process

An agent process (docs/AGENT_PROTOCOL.md) can be told who is calling, off by default ([agent_link] caller_identity = true, docs/CONFIG.md; withheld while phone numbers are redacted, docs/PRIVACY.md). Where the server finds each value:

The Twilio start message has no numbers, so the TwiML that opens the stream has to pass them: your voice webhook receives From and To and answers with

<Response><Connect><Stream url="wss://voice.example.com/twilio/stream">
  <Parameter name="from" value="+15551230001"/>
  <Parameter name="to" value="+15551230002"/>
</Stream></Connect></Response>

with the real values filled in per call (the voice webhook of examples/phone-receptionist does exactly this). Stream parameters are not covered by the signature of the stream URL, so treat them as hints, like a caller ID. Without the parameters an opted-in agent still gets the CallSid.

6. Answering machines

(The server binary's handling is at the end of this section.)

Strategy (layers, in order of authority)

1. Provider AMD when brisvox originates the call. Twilio: MachineDetection=DetectMessageEnd (the mode for leaving a message; Enable returns early with machine_start), sync (the call waits for the verdict, about 4 s typical) or AsyncAmd with a callback. Telnyx: answering_machine_detection greeting_end (or detect_beep, premium), results as webhooks. Leaving a message needs the end of the greeting: only Twilio DetectMessageEnd and Telnyx greeting_end / premium send it (AmdConfig::twilio_provides_greeting_end(), telnyx_provides_greeting_end()). Twilio Enable and Telnyx detect end at machine_start / machine; with them use VoicemailPolicy::detect_only() (hang up on machines; with speak_when_greeting_end_uncertain a fixed hint_wait of 6 s instead of waiting out the 30 s greeting timeout). A test feeds a Telnyx detect event to both policies. AmdConfig is the neutral configuration with documented ranges; twilio_params() and telnyx_fields() render it for the originating request (the same is used for the warm-transfer agent leg). The Telnyx mapping of the timing fields is an approximation (UNVERIFIED equivalence, documented on telnyx_fields).
2. Results to the session: parse_twilio_amd_callback(form body) and parse_telnyx_amd_event(json body) return an AnsweredBy; Twilio synchronous AMD can instead put AnsweredBy into a stream <Parameter> (CallInfo.metadata["custom.answered_by"]) so no plumbing is needed in core. Telnyx detection machine maps to MachineStart (greeting still playing); the greeting result (beep_detected / ended) maps to MachineEnd*.
3. In-engine hint voicemail_hint(text, speech_duration) returns a strength: HintStrength::Phrase for voicemail phrases in English and Turkish ("leave a message", "bip sesinden sonra", "mesaj bırakın", "sesli mesaj", ...) and HintStrength::Length for a greeting longer than 3.5 s with more than 5 words (Telnyx's documented thresholds; looks_like_voicemail is the plain yes/no of the two). It is fed to VoicemailDriver::on_voicemail_hint(strength, now) and only ever upgrades toward "machine", but the strengths are not equal, because a live person's "hello, this is the Smith residence, how can I help you" is also long:
   • An Unknown verdict settles as a machine if a hint of either strength came before it.
   • A Human verdict is overridden only by a phrase: when the phrase arrives within VoicemailPolicy::human_upgrade_window (10 s, zero disables) after the verdict, or when it was heard up to that long before the verdict (the speech-to-text final can beat the provider's verdict; Twilio DetectMessageEnd answers human at once for a short greeting that goes on with "leave a message after the beep"). A length hint never changes a Human verdict, in either order.
   • The driver then waits hint_wait (6 s) for the greeting to end and speaks. The window and the phrase specificity are the guard against reading the message to a real person. A machine verdict already given is never reversed. The phrase lists are suggestions, to be tuned on real Turkish voicemail.
4. Fallback VoicemailPolicy::on_unknown (TreatAsHuman by default, as Telnyx advises for not_sure; TreatAsMachine; HangUp) and speak_when_greeting_end_uncertain. TreatAsMachine (an Unknown verdict or the classify timeout) does not speak at once: an Unknown usually is a detection timeout, so the greeting may still be playing. Like the hint path it waits hint_wait (6 s, ends early on a MachineEnd* verdict), then speaks, or hangs up when speak_when_greeting_end_uncertain is off.
5. Future work: an in-engine beep detector (DSP on the callee audio) and greeting-length analysis without provider help; per-country AMD availability and Turkish carrier behavior are UNVERIFIED (live test).

Leave-message flow

voicemail_flow(&VoicemailConfig, registry) builds a Flow with these nodes; the verdicts come from the application, so transitions are applied by FlowManager::transition_to as VoicemailDriver directs, not by tool results.

classify  (respond_immediately off: the bot is silent)
   Human          -> human          (respond_immediately: greets; end_call -> farewell -> EndCall)
   MachineStart   -> wait_greeting  (silent, barge-in off)
   MachineEnd*    -> leave_message  (Reset; pre actions in order:
                                     Custom("barge_in", {"enabled": false}), Say(message), EndCall)
   Fax            -> hang up
   Unknown/timeout-> VoicemailPolicy

The action contract is documented on flows::Action: a node's action list runs strictly in order, Say finishes when its utterance-end mark was played (bounded by the runner), and EndCall hangs up after everything queued before it was played, so EndCall after Say in leave_message hangs up after the message's utterance-end mark (with the runner's own timeout), not immediately. There is no model turn and no tool, so nothing the callee says can change the fixed message. After the mark, call VoicemailDriver::message_played(). VoicemailDriver::deadline() is the instant the runner must call on_timeout at (classification 45 s, greeting 30 s by default). Outcomes for metrics: human, machine_message_left, machine_hangup, fax, unknown.

Compliance: the message is spoken and may be recorded; put nothing in it the callee did not consent to hear on a recording. Voicemail systems cut recordings at an unknown limit; keep it short (20 to 30 seconds).

Voicemail in the binary

An agent with [telephony.voicemail] (docs/CONFIG.md) handles the verdicts of calls the carrier's detector classifies. The binary does not originate calls: the application places the call with the detector on (AmdConfig::twilio_params / telnyx_fields) and points the carrier's stream at the binary. The verdict reaches the call two ways:

1. Stream parameter. Twilio's synchronous MachineDetection answers before the call's TwiML runs; the application's TwiML generator puts the result in the stream: <Parameter name="answered_by" value="machine_end_beep"/> (any Twilio AnsweredBy value). It is read at the call's start (CallInfo.metadata["custom.answered_by"]).
2. Callback. POST /v1/amd/twilio (AsyncAmdStatusCallback: CallSid, AnsweredBy) or POST /v1/amd/telnyx (the webhook), on the callback listener. The call is found by the carrier's call id. An asynchronous detector can answer before the media stream connected: a verdict for a call that is not live waits for it (up to 60 s, at most 256 waiting, answered 202 queued) and is applied when the call starts.

Each call with a verdict gets a VoicemailDriver (no driver for a call without one, so inbound calls are never touched) with the policy of the definition (on_unknown, detect_only; the other timings are the driver's defaults: greeting timeout 30 s, hint_wait 6 s, human upgrade window 10 s). Its steps: a machine whose greeting ended (machine_end_*) -> the bot speaks the message (a line through the engine's say input, cutting anything the bot was saying), and when the speech ended (bounded at 90 s) the call is hung up through the carrier; fax, or a machine with detect_only, or on_unknown = "hang_up" -> hung up at once; a person -> nothing, the conversation goes on. The callee's final transcripts are also fed to voicemail_hint: a voicemail phrase ("leave a message after the beep") upgrades a human or unknown verdict, as in the driver's rules above. A line that cannot be spoken (the engine takes none, as with an out-of-process agent) hangs the call up instead.

Limits: the bot is not silenced while the verdict is pending (the flow's classify node does that in the library, the binary has no flows). Arrange for the verdict to come first (the stream parameter) or make the agent wait for the callee to speak; and the barge-in settings of the definition apply to the message, so a beep that the VAD takes for speech can cut it (the message is spoken after the greeting ended, when the line should be quiet).

7. Unverified, guessed around, and live tests

Items marked here are provider behavior not stated in the fetched documentation. The code is defensive about each.

1. Twilio: effect of a REST update on an active <Connect><Stream> (order of stop, socket close, whether a new stream in the update TwiML is allowed). The DTMF route and warm-transfer rollback depend on it. The Twilio adapter treats a stream ending right after an announced REST update as expected, not as a hang-up: it handles stop, a close frame and a vanished socket alike, and a new stream that arrives before the old one closed. Whether Twilio really starts the new stream, and how soon, is settled by the live test. Update Twiml length limit: the 4000 characters of the Create page are applied.
2. Twilio: <Play digits> tone duration and level at the far end; error codes when updating an ended call (a 404 is mapped to CallGone, anything else is Rejected with the code); AnsweredBy field name in the sync-AMD webhook; whether async AMD may run beside a bidirectional stream; AMD in Turkey.
3. Telnyx: which commands 90045 blocks while streaming; effect of transfer on the stream (stop frame?); the response shape of POST /conferences and POST /calls (data.id, data.call_control_id are assumed and validated); command_id accepted by Dial; hold_audio_url behavior for a lone participant; premium AMD payload schemas.
4. Both: rate limits, billing of parent and child legs, REST error body shapes beyond the documented samples (both Twilio code/message and error_code/error_message are read).

Live checks still pending (need accounts, numbers, a public wss:// URL): DTMF both ways and IVR; cold and warm transfers on both providers, stream interplay; AMD on Turkish carriers, voicemail message flow.

Wiring the Telnyx stream stop

When the Telnyx media adapter and Telnyx call control run in the same process, set TelnyxConfig::on_stream_stop = Some(StreamStopHook::from_stopper(server.stream_stopper())). The 90045 retry path then announces its streaming_stop to the adapter first, so the stream close it causes is neither reported as a caller hang-up nor answered with a REST hang-up (test the_call_control_stop_hook_marks_the_stream_as_stopped_on_purpose). The server binary does this itself (section 5): HostSettings::stream_links() carries the Telnyx listener's StreamStopper to the binding (test telnyx_stream_stop_of_a_transfer_retry_is_not_a_hang_up in crates/brisvox-server/tests/telephony_extras.rs).

8. Security

What an eavesdropper or a stranger can do on each telephony transport, and what the server does about it. (See docs/SECURITY.md for the cross-cutting review.)

• Twilio. The listener is plaintext: terminate TLS in front of it. Every upgrade must carry a valid X-Twilio-Signature (HMAC-SHA1 over the public URL with the account's Auth Token). A fixed URL has one constant signature that can be replayed by anyone who saw it once, so the stream URL is per call: BRISVOX_TWILIO_STREAM_SECRET makes every URL end in a signed, single-use, expiring segment bound to the call's SID (docs/providers/twilio.md, "Per-call stream URLs"). BRISVOX_TWILIO_ALLOW_STATIC_URL=1 is the legacy escape hatch and logs a warning. The used-set of segments is per process: after a restart, or against another instance, a captured signed URL is replayable until its exp (at most 1 h; 120 s for URLs the server mints). Migrating from the fixed URL: see "Migrating from the fixed URL" in docs/providers/twilio.md. start.customParameters are not signed; do not put authority in them.
• Telnyx. Telnyx signs nothing. The path and the optional stream_auth_token are the only checks, so a Telnyx listener bound to a non-loopback address refuses to start without BRISVOX_TELNYX_STREAM_TOKEN (set the same value as stream_auth_token in the stream request); BRISVOX_INSECURE_LISTENERS=1 overrides it with a warning. Keep the path unguessable too (BRISVOX_TELNYX_PATH).
• SIP. UDP and TCP signaling and plain RTP are cleartext, and the digest Authorization protects only who may call, not who can listen. For a trunk across the internet turn on SIPS and SRTP ("SIP over TLS and SRTP" below): BRISVOX_SIP_TLS_ADDR with a certificate and key, and BRISVOX_SIP_SRTP=required. Without them run it on a private trunk, a VPN or behind an SBC that terminates TLS/SRTP toward the carrier. The listener refuses to start without at least one inbound check: BRISVOX_SIP_ALLOWED_SOURCES (a CIDR ACL of the carrier's signaling networks) and/or BRISVOX_SIP_AUTH_USER with BRISVOX_SIP_AUTH_PASSWORD (digest, single-use nonces); this holds for every bind address, loopback included. Use both when the trunk allows it: an ACL alone trusts source addresses, which are spoofable over UDP, and a digest alone leaves the port open to scans.
• Prompt-injected actions. Any carrier's caller can try to talk the model into a transfer or another SideEffect tool. List transfer_call (and any payment or booking tool) in agent.confirm_tools so it runs only after the caller's next reply confirms (docs/TOOLS.md, "Confirmation gate").
• Agent link. Transcripts, the LLM context and tool calls cross the link: plaintext ws:// to a host outside the private networks is refused (docs/AGENT_PROTOCOL.md).

SIP over TLS and SRTP

Turning it on. All of it is in BRISVOX_SIP_* (docs/CONFIG.md):

BRISVOX_SIP_ADDR=0.0.0.0:5060
BRISVOX_SIP_PUBLIC_IP=203.0.113.10
BRISVOX_SIP_ALLOWED_SOURCES=198.51.100.0/24                 # the carrier's signaling networks
BRISVOX_SIP_TLS_ADDR=0.0.0.0:5061
BRISVOX_SIP_TLS_CERT=/etc/brisvox/sips.crt                  # PEM chain, leaf first
BRISVOX_SIP_TLS_KEY=/etc/brisvox/sips.key                   # PEM, read once at startup
BRISVOX_SIP_SRTP=required                                   # off | optional | required

• SIPS. TLS 1.2 and 1.3 only (rustls, ring), no client certificate. The accept loop is Brisvox's own (src/sip/tls.rs), not the stack's, because the stack's TLS listener does the handshake without a deadline and without a limit. Before any SIP is read: the source ACL, then BRISVOX_SIP_TLS_MAX_CONNECTIONS (1024) and BRISVOX_SIP_TLS_MAX_PER_IP (32), then BRISVOX_SIP_TLS_HANDSHAKE_MS (10 s). After the handshake a connection is the same thing as a TCP one: digest, ACL, the admission gate and the call limit apply unchanged. The Contact of a call that came in over TLS is sip:brisvox@ip:5061;transport=tls (sips: when the INVITE's Request-URI was sips:), and the peer's BYE and re-INVITE come back on the same connection. The certificate is read once; there is no hot reload (restart to rotate, a draining restart loses no call). Idle timeout: an established connection that carries no byte in either direction for BRISVOX_SIP_TLS_IDLE_TIMEOUT seconds (default 300, 0 = off) is closed and its slots freed (SipStats::tls_idle_closed); an RFC 5626 CRLF keepalive is a byte and keeps it open. The stack reports no activity, so the TLS endpoint talks to a loopback socket and a relay task (src/sip/tls_relay.rs) copies the bytes to the peer's socket through an AsyncRead/AsyncWrite adapter that notes the time of each transfer; the check runs on the injected clock. Cost: two more descriptors and one task per TLS connection. Keep the ACL on a public address all the same.
• SRTP (SDES, RFC 4568). AES_CM_128_HMAC_SHA1_80 and AES_CM_128_HMAC_SHA1_32 (RFC 3711), keys exchanged in the SDP. The first usable a=crypto line of the offer wins, the answer repeats its tag and suite with Brisvox's own key, each direction has its own key, and every call gets fresh random keys wiped on drop. The packet code (src/sip/srtp.rs) is Brisvox's: AES-128 counter mode from RustCrypto (aes, ctr), HMAC-SHA1 from ring, in place and allocation-free per packet (a few microseconds on the call's task), replay window of 128 packets, tag compared in constant time, a forged packet changes no state. Key schedules wipe themselves on drop (zeroize features of aes and ctr), as do the master and session keys and the IV buffers (ring's HMAC key has no wipe of its own, and the base64 text of a key in an SDP buffer is not wiped either: the places a key outlives its call in memory until the allocator reuses it). A crypto line whose key lifetime is below 2^31 packets (|2^20, |1048576) is ignored: this endpoint neither counts packets per key nor re-keys by itself, so it does not pretend to honour a short lifetime. Packets that fail authentication are counted per call per second: more than BRISVOX_SIP_SRTP_AUTH_FAIL_LIMIT (default 50, 0 = off) ends the call with a log line and SipStats::srtp_flood_hangups (a _32 tag is 32 bits, so a flood is a guessing attack; the price is that whoever can send UDP to the call's RTP port can end the call, which is a cheaper attack than guessing). It is pinned to the RFC 3711 test vectors (appendix B.2 and B.3) and cross-checked against the independent webrtc-srtp crate in both directions across the sequence-number wrap.
• Policy. off: plain RTP only; an RTP/SAVP-only offer gets 488. optional (the default when TLS is configured): SRTP when the offer has a usable crypto line and came in over TLS, otherwise plain RTP; with both on offer SRTP is preferred. required: nothing but SRTP over TLS, everything else is 488 (SipStats::rejected_insecure). SDES keys are never taken from UDP or TCP signaling (RFC 4568 section 7.1: keys need confidentiality and integrity from the signaling), under any policy: such an offer gets 488 and no crypto line is answered. Setting anything but off without the TLS listener is a startup error. The mode of a call is fixed at setup: a re-INVITE cannot turn SRTP off (488, the call stays up). In-dialog requests stay on TLS: the transport of a dialog is recorded from the real connection when the call is set up, never read from a Via (written by the sender); an in-dialog request for a TLS dialog that does not arrive on a TLS connection gets 488 (re-INVITE, UPDATE) or 403 (anything else) before the dialog sees it, with no SDP processed and no key answered (SipStats::insecure_dialog_requests). The ACK of a re-INVITE is delivered by the stack straight to the re-INVITE's transaction without its connection, so a message inspector strips the SDP from an ACK that came in off TLS on a TLS dialog. Re-keying: a peer key that changed is answered with a fresh key of ours and fresh sender and receiver state (a leaked answer exposes nothing older); the same key again (hold, resume, refresh) changes nothing; a suite change must come with a new peer key (a new suite with the old key is refused: the _32 tag is the prefix of the _80 tag, so a receiver started over on the same key would take every earlier _80 packet cut to 4 bytes as new). The answer to an offer we made in a 200 (body-less re-INVITE) keeps the key we offered.
• Outbound. A DialRequest.to of sips:... or ...;transport=tls is called over TLS, the callee's certificate verified against BRISVOX_SIP_TLS_CA (a PEM bundle; there are no built-in roots in the stack, so a public carrier's CA must be listed there). With optional or required a TLS call offers RTP/SAVP with AES_CM_128_HMAC_SHA1_80; an answer that is not SRTP with the offered tag and suite ends the call (BYE, DialError::BadAnswer). required refuses a non-TLS target before anything is sent. With DialRequest::destination (an explicit proxy address) and a callee named by a domain, the connection is made by Brisvox and the certificate is verified for the callee's domain (the stack would verify the proxy's IP, which public CAs do not certify); a live connection verified for the same name is reused, and the handshake follows BRISVOX_SIP_TLS_HANDSHAKE_MS. A callee given as an IP address is verified for that address. Not done: DNS SRV/NAPTR for TLS targets.
• Logs. rsipstack logs every SIP message at info, which on a secure call includes the SDP and with it the SRTP master keys. The server binary therefore holds the target rsipstack at warn whatever RUST_LOG says (like the TURN client crates), and DEFAULT_FILTER names it too. BRISVOX_LOG_SIP_STACK=1 lifts that for debugging only. A host that installs its own subscriber must apply brisvox_core::telemetry::sip_stack_log_allowed. The stack also logs one warning at start about the TLS address entry that is not a listener it can serve (a placeholder that makes it write Via: SIP/2.0/TLS for requests to TLS callees); it is expected. Brisvox's own events, Debug output and errors never contain key material (test key_material_never_reaches_brisvoxs_logs_or_debug_output).

Which trunks were checked (documentation fetched 2026-10-13; nothing was tested live against a carrier; that live run is pending):

Facts about the stack itself (rsipstack 0.7.3 source, read 2026-10-13): its TLS listener has no handshake deadline or connection limit (hence Brisvox's accept loop); TlsConnection::from_server_stream takes a finished stream; the connection type of an outbound request comes from the URI's transport parameter, not from the sips: scheme (Brisvox adds ;transport=tls to a sips: callee); a request's Via transport is chosen from the stack's listener addresses; dropping any TransportLayer clone cancels the whole stack (so connection tasks never hold one); it keeps no trust roots of its own (empty store plus the PEM it is given).

What remains.

• DTLS-SRTP (RFC 5763/5764, a=fingerprint, a=setup) is not implemented; it is what WebRTC peers use, and trunks mostly do not. Not cheap: a DTLS handshake per call plus SRTP key export (whether str0m's DTLS can be reused for it was not evaluated).
• AEAD suites (AEAD_AES_128_GCM/256_GCM, RFC 7714) and the 256-bit CM suites; SRTCP and RTCP (none is sent, the peer's is ignored); MKI; SDES session parameters (KDR, WSH, FEC_*, UNENCRYPTED_*) — lines with them are ignored, never half-honoured; optimistic SRTP (RTP/AVP with a=crypto) is read as plain RTP.
• Mutual TLS (a client certificate from the carrier), certificate hot reload, outbound DNS SRV/NAPTR, a built-in public trust store for outbound TLS. A TLS connection verified for one callee domain and reused for another domain through the same proxy address stays verified for the first name only (the stack caches connections by address).
• Interop against a real carrier or SBC over TLS+SRTP: the tests use a scripted peer that speaks the same RFCs as the implementation, so a shared misreading would not show.

Twilio Media Streams (bidirectional) — telephony transport

Scope: Twilio Media Streams (mu-law 8k; interruption sends the buffer-clear message; playback tracking via marks feeds played-text truncation; TwiML example). Related: docs/providers/g711.md (codec), docs/providers/call-control.md (DTMF, transfer). Researched: 2026-10-08. Every fact below was read from the pages listed under Sources on that date. Anything not confirmed is marked UNVERIFIED. This is a transport, not an STT/LLM/TTS provider: Twilio is the WebSocket CLIENT, brisvox is the WebSocket SERVER.

• Docs: https://www.twilio.com/docs/voice/media-streams/websocket-messages (fetched 2026-10-08); full source list at the bottom. JSON examples below come from the .md rendition of that page (.../websocket-messages.md), where the plain page fetch would only summarize them. Values like MZXXXX... are the docs' placeholders.
• Auth / trust:
  • There is no API key for the stream. Twilio connects to the wss:// URL in the TwiML. The only documented authenticity check is the X-Twilio-Signature header on the WebSocket upgrade request (see "Request validation" below).
  • Brisvox: the TwiML is served by the user's HTTP webhook (not by brisvox core); the WS endpoint must validate the signature with the account's primary Auth Token. Never log the token.
• Endpoint(s) / regions:
  • Brisvox hosts a wss:// endpoint. wss is the only supported protocol and the <Stream url> does not support query string parameters (use <Parameter> instead); a relative or an absolute URL is accepted (stream TwiML page). Error 31923 "Malformed URL" = URL scheme malformed; 31920 "Handshake Error" = server did not answer the upgrade with HTTP 101 (wrong path, no WebSocket support, query string in the URL).
  • Twilio must reach the server on TCP 443 "from any public IP address"; the firewall page lists NO IP ranges, hostnames or other ports. TLS version/certificate requirements: not stated (UNVERIFIED; use a normal publicly trusted certificate). Terminate TLS in front of brisvox (proxy) or in-process; behind a proxy the URL used for signature validation must be the public one.
  • Regions: Media Streams is available in Ireland (IE1) and Australia (AU1); the default region is US1 (media-streams overview). <Connect><Stream> is also stated available in IE1/AU1 (connect TwiML page). Non-US setup follows separate Twilio guides (not fetched: UNVERIFIED details).
• TwiML to start a bidirectional stream (stream TwiML page; <Connect><Stream>):

  <Response>
    <Connect>
      <Stream url="wss://example.com/audiostream" />
    </Connect>
    <Say>This TwiML instruction is unreachable unless the Stream is ended by your WebSocket server.</Say>
  </Response>
  

  • With custom parameters (docs example is for <Start><Stream>; the same <Parameter> noun nests in <Connect><Stream>: the page says <Parameter> is nested in <Stream> and the Start message carries the values; a <Connect> example with <Parameter> is not printed: UNVERIFIED but implied):

    <Response>
      <Start>
        <Stream url="wss://mystream.ngrok.io/example">
          <Parameter name="FirstName" value="Jane" />
          <Parameter name="LastName" value="Doe" />
        </Stream>
      </Start>
    </Response>
    

    Brisvox example (derived, not a doc sample):

    <Response>
      <Connect>
        <Stream url="wss://agent.example.com/twilio/stream" name="brisvox">
          <Parameter name="agent" value="support-tr" />
        </Stream>
      </Connect>
    </Response>
    

  • <Stream> attributes (stream TwiML page): url (required), name (optional, unique per call), track (inbound_track default | outbound_track | both_tracks; unidirectional only, a bidirectional stream "can receive only inbound_track"), statusCallback (absolute URL), statusCallbackMethod (GET|POST, default POST).
  • <Parameter name= value=>: the combined length of each <Parameter> name and value must be under 500 characters (stream TwiML page). No maximum parameter count is stated (UNVERIFIED). Values arrive in start.customParameters (all as strings in the doc example).
  • <Connect><Stream> blocks: Twilio does not execute later TwiML until the server closes the WebSocket (stream TwiML page; overview page says the same). With no further verb the call ends (general <Connect> page: "If there is no further verb, Twilio will end the phone call", stated for the case without an action URL). The Stream resource (REST) cannot start a bidirectional stream.
• Protocol (messages in/out, with field names). All frames are JSON text frames (binary frames are not mentioned: UNVERIFIED).
  • Twilio -> server, in order: connected, then start, then media (repeating) and optionally dtmf/mark, finally stop.

    { "event": "connected", "protocol": "Call", "version": "1.0.0" }
    

    {
      "event": "start",
      "sequenceNumber": "1",
      "start": {
        "accountSid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "callSid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "tracks": [ "inbound" ],
        "mediaFormat": { "encoding": "audio/x-mulaw", "sampleRate": 8000, "channels": 1 },
        "customParameters": { "FirstName": "Jane", "LastName": "Doe", "RemoteParty": "Bob" }
      },
      "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
    

    {
      "event": "media",
      "sequenceNumber": "4",
      "media": { "track": "inbound", "chunk": "2", "timestamp": "5", "payload": "no+JhoaJjpzS..." },
      "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
    

    {
      "event": "stop",
      "sequenceNumber": "5",
      "stop": { "accountSid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "callSid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" },
      "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
    

    { "event": "dtmf", "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "sequenceNumber": "5",
      "dtmf": { "track": "inbound_track", "digit": "1" } }
    

    { "event": "mark", "sequenceNumber": "4", "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "mark": { "name": "my label" } }
    

  • Field notes (from the messages page):
    • connected: protocol ("protocol for the connection's lifetime", example "Call"), version (semantic version, example 1.0.0). First message.
    • start: sent once, immediately after connected. start.tracks array of inbound/outbound; start.mediaFormat.encoding is always audio/x-mulaw, sampleRate always 8000, channels always 1; start.customParameters = the <Parameter>s; streamSid (also repeated at top level of every message). sequenceNumber starts at 1 and increases per message.
    • media.track: inbound or outbound (one of the page's media examples shows "outbound"). For a bidirectional stream only the inbound track is delivered (stream TwiML page / overview page). media.chunk: starts at 1, increments per media message. media.timestamp: "Presentation Timestamp in Milliseconds from the start of the stream". media.payload: raw audio, base64.
    • TYPES: in every doc example sequenceNumber, media.chunk and media.timestamp are JSON STRINGS ("1", "2", "5"), while sampleRate and channels are numbers. The property tables describe them as numbers ("Number used to keep track of message sending order"). Brisvox parser must accept both string and number for these three fields. (Parsing as integer from a string is the safe approach.)
    • dtmf (bidirectional only): dtmf.track is always inbound_track (note: differs from the inbound value used in media.track), dtmf.digit the key. Digit alphabet beyond a single key (0-9, *, #, A-D) is not specified: UNVERIFIED. Outbound DTMF from the server to Twilio is NOT supported (overview page: DTMF only inbound, from Twilio toward your media server).
    • mark (Twilio -> server): bidirectional only; sent when audio the server sent has finished playing (or was cleared), with the mark.name the server chose.
    • stop: sent when the stream stops or the call ends. The messages page says for bidirectional streams "the only way to stop a Stream is to end the call", but the overview page says a bidirectional stream can be stopped "by closing the WebSocket connection from your server or by ending the Call", and error 31921 (paraphrase) says the close stops a bidirectional Stream. Treat server close as stream end.
  • Server -> Twilio (bidirectional streams only, started with <Connect><Stream>). Only media, mark and clear are accepted (errors 31951/31924); anything else, bad JSON, missing or unexpected fields or a streamSid that does not match the active stream is logged as "Invalid Message" (31951).

    { "event": "media", "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "media": { "payload": "a3242sa..." } }
    

    { "event": "mark", "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "mark": { "name": "my label" } }
    

    { "event": "clear", "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
    

    Use the streamSid from the start message (31951 page: never reuse a SID from another call or stream).
• Outbound audio format and chunking:
  • media.payload must be (messages page) "encoded audio/x-mulaw with a sample rate of 8000 and must be base64 encoded" and "should not contain audio file type header bytes" (i.e. no WAV/AU header; raw G.711 mu-law, 8000 Hz, mono, 1 byte per sample = 8000 bytes/s). Error 31924 repeats (paraphrase): send base64-encoded audio/x-mulaw at 8000 Hz without audio file header bytes.
  • Chunk size: "The audio can be of any size." No required or recommended chunk size or send interval is documented (UNVERIFIED claim that 20 ms = 160 bytes frames are ideal: it is arithmetic only, 160 bytes = 20 ms at 8 kHz mu-law; that is a brisvox choice and matches the 20 ms pacer frame in the engine). The same applies to inbound: the docs give no inbound frame duration (UNVERIFIED; examples show timestamp "5" next to chunk "1"/"2", which cannot be used to infer it).
  • Buffering: "The media messages are buffered and played in the order received." So Twilio keeps its OWN jitter/playout buffer on its side; brisvox may send ahead of real time, but anything sent ahead can only be removed with clear (see below) and is invisible to brisvox's pacer unless marks track it.
  • Buffer limit (error 31931 "Media Discarded", a warning logged once per stream): once buffered audio exceeds 10 minutes, Twilio stops accepting more audio for that Stream (page wording paraphrased). Causes listed: sending media faster than it plays, no mark tracking. Docs' remedies: pace outbound media, send a mark after each media message and wait for the matching mark event before sending large amounts of more audio, and clear to empty the buffer before replacement audio.
  • Inbound overflow (error 31930 "Buffer Overflow", warning): if limited bandwidth stops the stream from keeping up, Twilio discards audio (inbound audio is lost; no reconnect documented).
• Mark semantics:
  • Server sends mark after the media it wants to track. Twilio returns a mark event with the same mark.name "when the audio ends (or if there is no audio buffered)" (messages page wording). The page does not use the word "immediately"; an immediate return for an empty buffer is implied (UNVERIFIED as to timing).
  • On clear: the page says it "empties all buffered audio and causes any mark messages to be sent back to your WebSocket server", i.e. Twilio sends back a mark for every remaining (unplayed) mark so you can tell which media will not play (purpose paraphrased, not verbatim). The mark event for a CLEARED mark is indistinguishable from a played one on the wire (same JSON); brisvox must therefore know, locally, that it sent clear and treat any mark arriving after its own clear (until the next audio it sent after the clear) as "dropped" rather than "played". Order and timing of those returned marks relative to the clear are not specified (UNVERIFIED), nor whether a mark covering audio currently being played is returned at clear time or after the buffered sample finishes (UNVERIFIED).
  • Marks carry NO timestamp or played-sample count. A mark only says "everything sent before this mark has been played (or discarded)". Playback position at an arbitrary moment (needed by played-text truncation when the caller interrupts mid-chunk) is therefore not reported by Twilio: UNVERIFIED that no other field exists; none is documented. Granularity of the playback position = granularity of the marks.
  • Name: free string (page: "A custom value"). Maximum length and allowed characters not documented (UNVERIFIED; use short ASCII like a monotonically increasing counter or "<epoch>:<seq>"). Whether two pending marks may share a name: not stated (use unique names).
  • Brisvox design for played-text tracking (a proposal, not a doc claim): send a mark after every N ms of audio (e.g. every 100-200 ms or every TTS frame group) with name encoding (turn epoch, cumulative sample count sent). On a returned mark (not preceded by our own clear) advance the confirmed-played position; at barge-in the played position is confirmed_marks + estimate of the unconfirmed tail (the estimate comes from the local wall clock since the last mark; Twilio's own buffer depth is invisible), and the played text is truncated to that bound. Mark spacing trades accuracy against message count; every mark is one extra WS frame each way.
• Interruption (barge-in):
  • Send {"event":"clear","streamSid":"..."}. Per the page: empties the audio buffered on Twilio's side and returns the pending marks. Brisvox rules: (1) send clear the moment the turn epoch advances (engine rule "Clear-on-epoch-advance"), before any new-epoch audio; (2) stop sending old epoch media; (3) media sent after the clear plays normally (the page implies buffer reuse; not explicitly stated: UNVERIFIED), (4) discard returned marks per the previous section.
  • Race: audio already handed to the phone network before clear arrives still plays. The size of that residual (Twilio-side playout buffer, carrier jitter buffer) is not documented: UNVERIFIED; measure on a live call.
  • The changelog (2020-06-17) introduced Mark and Clear for building barge-in (the caller can interrupt playback; wording paraphrased); the Twilio samples connect-basic and dialogflow-integration are named there.
• Keepalive / timeouts:
  • No keepalive, ping interval, idle timeout, maximum call/stream duration or reconnect behaviour is documented on the pages fetched (UNVERIFIED). Each Media Stream uses one WebSocket connection (error 31921); if the connection drops the stream stops (31921) and there is no documented resume. Brisvox must treat a WS close as the end of the call leg.
  • Brisvox own timeouts apply (engine rule: every network await has an explicit timeout): e.g. time to first start after upgrade, and a stall timer on inbound media (Twilio sends inbound audio continuously while the call is up; the exact cadence is UNVERIFIED so size the stall timer generously and verify live).
  • Closing: closing the WebSocket from the server stops a bidirectional stream and lets the TwiML continue (31921 / stream TwiML page). Ending the call sends stop. Close code/reason Twilio uses on its side: not documented (UNVERIFIED).
• Request validation (X-Twilio-Signature on the upgrade request):
  • Media Streams page: "validate the X-Twilio-Signature header" (firewall page: how your application verifies that a Media Stream is coming from an authentic Twilio source). The Security page adds for voice WSS handshakes only: "try appending a trailing / character to the URL that you pass to the signature validation method" if verification of a WebSocket handshake request (for example Programmable Voice Media Streams) fails.
  • Algorithm (security page, HTTP requests): take the full request URL (scheme through query string); for POST append sorted (case-sensitive) parameter names+values with no delimiters (GET: params are in the query string); HMAC-SHA1 with the PRIMARY Auth Token as key; base64; compare to the X-Twilio-Signature header. A WS upgrade is a GET without params, so the signed string is just the URL (Twilio's own search-summary statement, not a verbatim doc sentence: UNVERIFIED). Because <Stream url> cannot carry a query string, the signed URL is the bare wss://host/path as written in the TwiML. Whether Twilio signs the URL with wss:// or https:// scheme, and whether the port :443 is included, is NOT stated for WSS (UNVERIFIED): the security page says "Voice over HTTPS" drops the port (and username/password in the URL are always dropped). Implementation: try the candidate URL forms (as configured; with/without trailing /; wss/https scheme) and accept if any matches, constant-time compare; test live.
  • Primary Auth Token only (security page: if a secondary token was created, "you still need to use your previous AuthToken until the secondary one has been" promoted to primary). Behind a reverse proxy rebuild the public URL from configuration, not from the Host header you see.
  • Custom parameters (start.customParameters) arrive in a WS message AFTER the handshake and are not part of the signed URL; treat them as untrusted unless the handshake signature validated. (Twilio does not document signing them: UNVERIFIED that they are unsigned.)
  • Helper libs documented: Node validateRequest/validateRequestWithBody; Python/C#/Java/PHP RequestValidator; Ruby Twilio::Security::RequestValidator; Go client.NewRequestValidator (Validate / ValidateBody). No Rust SDK validator was found in these docs; a Twilio blog post "validate Twilio Event Streams webhooks in Rust" appeared in search results but concerns Event Streams, not this (not fetched: UNVERIFIED). Implement HMAC-SHA1 by hand (RustCrypto hmac + sha1, check crates.io for versions/licenses before adding; not researched here).
• Timestamps / interim results / tool-call deltas: not applicable. Relevant timing data: inbound media.timestamp (ms since stream start, string) and chunk counter (gaps = lost inbound audio, 31930). sequenceNumber also counts every message (gaps detectable). Outbound media has no timestamp field.
• Concurrency / rate limits:
  • Bidirectional: only one Stream per Call. Unidirectional: up to four tracks per call, shared with SIPREC, Real-Time Transcription, Answering Machine Detection (the overview page names SIPREC and Real-Time Transcription as examples of forking features sharing the limit; Answering Machine Detection in that list is UNVERIFIED). Each stream = one WebSocket.
  • Per-account concurrent stream / call limits, messages-per-second limit, and pricing: NOT found on the pages fetched (UNVERIFIED). Voice pricing page: https://www.twilio.com/en-us/voice/pricing (not fetched). The overview page links to "Forked Audio Streams" for fork costs (not fetched).
  • Outbound buffer cap: 10 minutes (31931, above).
• Status callbacks (note only; not needed for the core adapter): statusCallback on <Stream> gets an HTTP request (method statusCallbackMethod, default POST) with AccountSid, CallSid, StreamSid, StreamName (defaults to StreamSid), StreamEvent (stream-started | stream-stopped | stream-error), StreamError (detail text), Timestamp (ISO 8601). Useful to debug failed starts (31920). Call-level status callbacks (call completed etc.) are separate Voice webhooks: not researched.
• Turkish support: not applicable to the transport (language-agnostic G.711 audio). Telephony quality note: 8 kHz mu-law narrowband is typically harder for STT; Deepgram etc. accept mulaw @ 8000 directly (see deepgram.md for the exact encoding parameters); Cartesia can output pcm_mulaw @ 8000 directly (see cartesia.md). Whether Turkish <Say> etc. matters is irrelevant (brisvox does TTS).
• Mapping to the brisvox transport trait (crates/brisvox-transport, check the real trait when implementing) — proposal:
  • Inbound: base64-decode media.payload (only track == "inbound") -> G.711 mu-law bytes -> decode via brisvox_audio::codec -> PCM16 8 kHz -> resample (rubato) to the pipeline rate. Drop messages whose streamSid differs from start.streamSid. Handle dtmf -> DTMF event. Handle stop -> end of session. Ignore unknown event values (forward compatibility).
  • Outbound: PCM16 -> resample to 8 kHz -> mu-law encode -> base64 -> media. Prefer 160-byte frames on the engine's 20 ms pacer (a design choice, see chunking above). Keep a reusable String/Vec buffer for base64 and the JSON frame (hot-path no-allocation rule).
  • Barge-in -> clear; marks -> playback position for played-text truncation (see Mark semantics).
• Gotchas found during implementation: see "Brisvox implementation" below.

Brisvox implementation

Code: brisvox_transport::twilio (feature twilio, on by default; needs websocket). Tests: crates/brisvox-transport/tests/twilio.rs (scripted Twilio client over real sockets, local mock of the wire protocol), unit tests in src/twilio/*. Design notes: docs/ARCHITECTURE.md, "Twilio transport".

Setup

1. Run a TwilioServer (its own listener, the same server infrastructure as the generic WebSocket transport: call limit and 503, accept queue, pings, idle and write timeouts, shutdown), behind a TLS-terminating proxy that exposes it as wss://agent.example.com/twilio/stream.

   #![allow(unused)]
   fn main() {
   let mut server = TwilioServer::bind(
       ServerConfig { bind_addr: "127.0.0.1:8081".parse()?, ..ServerConfig::default() },
       TwilioConfig {
           path: "/twilio/stream".into(),
           auth_token: Some(Secret::new(std::env::var("TWILIO_AUTH_TOKEN")?)),
           public_url: Some("wss://agent.example.com/twilio/stream".into()),
           ..TwilioConfig::default()
       },
       clock, &cancel,
   ).await?;
   // then: loop { let link = server.accept(&cancel).await?; TransportSession::open(.., link, ..) }
   }

2. Point the voice webhook of the Twilio number at an HTTP endpoint that answers with TwiML (brisvox does not serve it; any web framework or a Twilio Function will do). The recommended form has a per-call stream URL: the public URL plus a signed single-use segment minted from the call's CallSid ("Per-call stream URLs" below; a runnable webhook that does it, with tests, is examples/phone-receptionist/twiml_server.py, set BRISVOX_TWILIO_STREAM_SECRET on both sides). The TwiML has this shape:

   <?xml version="1.0" encoding="UTF-8"?>
   <Response>
     <Connect>
       <Stream url="wss://agent.example.com/twilio/stream/CAxxxx.1760000120.mac" name="brisvox">
         <Parameter name="agent" value="support-tr" />
       </Stream>
     </Connect>
   </Response>
   

   Legacy (static TwiML Bin, needs BRISVOX_TWILIO_ALLOW_STATIC_URL=1 on the server, replayable signature): the same TwiML with url="wss://agent.example.com/twilio/stream", the fixed public URL. Without a stream secret and without that flag the listener does not start. The URL starts with TwilioConfig::public_url and must not contain a query string (use <Parameter>). The values arrive in CallInfo.metadata as custom.<name> (custom.agent = support-tr). Anything after <Connect> runs only after brisvox closes the socket (engine hang-up), e.g. <Say> or <Dial> for a hand-off.

What the adapter does

CallInfo.metadata: transport=twilio, sample_rate=8000, encoding=mulaw, stream_sid, call_sid, account_sid, tracks, twilio_protocol, twilio_version, peer_addr, custom.<name>; call_id is the callSid. All outbound messages use the streamSid of start.

Audio rates: the adapter converts mu-law <-> PCM16 but does not resample (as the generic adapter): the engine must produce 8 kHz audio for a Twilio call (the output chain resamples). Bot audio at another rate is dropped and reported once per call as a fault. No audio is passed through as mu-law: the core is PCM16 only.

Marks, clear and played-text tracking

• Twilio returns a mark both when audio played and when a clear flushed it, with identical JSON. The adapter tells them apart locally, as the notes under "Mark semantics" require: it keeps the marks in flight (name -> engine id, at most 512) and forgets all of them when it sends clear. An echo that arrives afterwards finds nothing and is dropped. This is more precise than "marks after a clear are dropped until new audio": a mark sent after the clear has a new name and counts. The core reports the engine's unechoed marks as MarkCleared at the same moment.
• The wire name is a letter and a counter (e0, p17), never the engine's id: Twilio documents no length or character limit for names (UNVERIFIED), so ids of any length and content work.
• Progress marks give TwilioStats::max_echo_latency (time from sending a mark to its echo, which is the playout delay plus the audio buffered ahead of it: open item 8) and max_unplayed (the most audio sent but not yet known played).
• Playback tracking for played-text truncation has two signals. The engine's utterance-end marks come back as TransportEvent::MarkPlayed (the utterance was heard whole). Every echoed mark, progress or engine, also yields the audio sent after it (not yet played) and the adapter reports that as WireEvent::Lead, forwarded as TransportEvent::PlaybackLead { lead } (a level; a new report replaces a queued one). For a barge-in in the middle of an utterance the heard position is PlaybackPosition.played - PlaybackLead.lead, never below zero; it replaces the fixed lead_margin guess with what Twilio's buffer actually holds, to within the 200 ms mark spacing (Twilio sends no position inside a mark interval). Status: the transport side is done and tested (a lead report per echoed mark, coalesced to the latest, reset by a clear), brisvox-engine stores it (PlayoutBook::set_client_lead) and PlayoutTruncation reads it: heard = min(released, total_audio) - lead, where a reported lead REPLACES the fixed lead_margin (in both directions: a lead above the margin cuts more, a lead below it cuts less), less the audio of later utterances in the client's buffer; the lead in force when a Clear covered the utterance is the one used, and an uninterrupted response loses no lead. The replace rule is reasoned, not measured. Open risk (RISKS.md R15): a small reported lead (about 50 ms) drops the margin for audio still queued on the engine-to-Twilio path, which the lead (audio sent after the last echoed mark, as Twilio's buffer holds it) may not cover, so one more word than was heard can be kept. The conservative alternative is max(lead, lead_margin); switch to it if a live Twilio measurement (released position against the echo times of progress marks, with the wire queue loaded) shows the engine-side queue is not in the reported lead. clear_hook must be installed for the lead to be tied to its clear.

Ending the call

Closing the socket is the only hang-up, and it is immediate: the adapter does not wait for audio still queued toward Twilio or buffered by Twilio, and the docs do not say whether Twilio plays what it already buffered once the socket is closed (UNVERIFIED, open item 9). A goodbye utterance followed directly by TransportCommand::Stop can therefore be cut off. The engine must send the audio, then an utterance-end TransportCommand::Mark, wait for its TransportEvent::MarkPlayed (with its own timeout, since a mark can also be lost), and only then send Stop.

Request validation

With an auth_token, the upgrade needs X-Twilio-Signature = base64(HMAC-SHA1(token, URL)) or the answer is HTTP 403 (no header, bad base64, wrong token, wrong URL). The HMAC comes from ring (already in the tree through rustls; HMAC_SHA1_FOR_LEGACY_USE_ONLY is the name of the primitive, the algorithm is the one Twilio mandates) with a constant-time compare. Because the signed URL form for wss is not documented (UNVERIFIED, open item 1), the signature may match any of: the configured public_url; the same with https for wss (and http for ws); with the default port :443/:80 added or removed; with a trailing / added or removed (up to 8 forms, all public information). Unit tests pin HMAC-SHA1 to RFC 2202 and the digest to Twilio's published worked example. Requests for any other path get 404 before the signature is looked at. Without an auth token nothing is checked: use that only behind another check. Auth token and public_url are validated together at startup (TwilioConfig::validate); the token is a Secret and never printed. The signature is computed over public_url as configured, so path (the route the listener serves) may differ from the path of public_url: a gateway can serve wss://agent.example.com/voice/twilio and forward to /twilio/stream. The proxy must pass the X-Twilio-Signature header through unchanged.

What the signature does not give: it authenticates the URL, and for a <Stream url> without a query string the URL is the same on every call, so the signature is one constant value. Anyone who has seen it once (a proxy or access log) can open upgrades with it until max_calls is reached. start.customParameters are not signed at all. That is why a signed listener now needs per-call URLs (stream_secret, see "Per-call stream URLs" below) or the explicit legacy flag allow_static_url; the fixed-URL mode described here is the legacy one. Treat custom parameters as untrusted either way.

Per-call stream URLs (review MEDIUM-1)

The signature above covers the URL only, and the URL is the same for every call, so a signed upgrade that was captured once (a proxy or access log) is valid for ever. Brisvox therefore makes the URL different for every call and accepts each URL once.

Sources, read 2026-10-13: https://www.twilio.com/docs/usage/security (the signed string is the full request URL including the query string; for a POST the sorted parameters follow, a WebSocket upgrade is a GET without any; HMAC-SHA1 with the primary Auth Token, base64; "Voice over HTTPS" callbacks drop the port; a trailing slash may be missing; for voice WSS handshakes it says to try a trailing / if validation fails), and https://www.twilio.com/docs/voice/twiml/stream (the url attribute "does not support query string parameters", so per-call data goes either into a custom <Parameter>, which arrives after the handshake and is not signed, or into the URL path, which is signed). Twilio signs the path like any other part of the URL, so a per-call path segment is covered by X-Twilio-Signature with no change to the check. The URL forms tried (signature::candidate_urls: scheme wss/https, with or without :443, with or without a trailing /) apply to the full per-call URL unchanged.

The segment is <callSid>.<exp>.<mac> appended to the base URL (BRISVOX_TWILIO_PUBLIC_URL):

mac = base64url_nopad( HMAC-SHA256( secret, "brisvox-twilio-stream-v1|" + callSid + "|" + exp ) )

callSid is the call's SID (ASCII letters and digits), exp the Unix time in seconds after which the URL is dead (at most one hour ahead), secret is BRISVOX_TWILIO_STREAM_SECRET (at least 32 bytes). The upgrade is accepted only if all hold: the segment parses and its MAC verifies (constant time); exp is in the future on the injected clock; the segment was not used before (a bounded set, entries dropped at their expiry, at most 65 536 live ones, a full set refuses); X-Twilio-Signature matches the full per-call URL; and the start message that follows carries the same callSid (a URL minted for one call cannot open another: close code 1008). The segment is used up only after the signature held, so someone who holds a URL but no signature cannot burn a legitimate call's token. The used-set is per process: a restart empties it and several instances behind a load balancer each have their own, so a captured URL with a valid signature is replayable against another instance (or after a restart) until its exp, at most one hour ahead (120 s for a URL the server mints itself). Keep exp short (the lifetime of the call set-up, not the call) and pin the stream path to one instance if replay matters. Segments the server mints for the same call within one second get consecutive exp values, so each is a distinct token. Everything else is HTTP 403 (404 for a path that is not the base or the base plus one segment).

Who mints it:

• Streams the server restarts itself (DTMF through call control, a failed warm transfer): the server writes the TwiML and signs the URL (StreamUrlSigner, lifetime 120 s).
• The first stream of an inbound call is named by the operator's webhook, which mints the segment with the same secret:

import base64, hashlib, hmac, time

def stream_url(base, secret, call_sid, ttl=120):
    exp = int(time.time()) + ttl
    msg = f"brisvox-twilio-stream-v1|{call_sid}|{exp}".encode()
    mac = hmac.new(secret.encode(), msg, hashlib.sha256).digest()
    mac = base64.urlsafe_b64encode(mac).rstrip(b"=").decode()
    return f"{base.rstrip('/')}/{call_sid}.{exp}.{mac}"

const crypto = require("crypto");
function streamUrl(base, secret, callSid, ttl = 120) {
  const exp = Math.floor(Date.now() / 1000) + ttl;
  const mac = crypto.createHmac("sha256", secret)
    .update(`brisvox-twilio-stream-v1|${callSid}|${exp}`).digest("base64url");
  return `${base.replace(/\/+$/, "")}/${callSid}.${exp}.${mac}`;
}

Known answer (secret 0123456789abcdef0123456789abcdef-secret, call CAabc123, exp 1900000000): CAabc123.1900000000.ixBbTZftQyn5JYCeFPFULx9O_UM1uxv0OZ_JhN6GIm0 (a unit test pins it).

• Legacy: a deployment whose own TwiML cannot do that sets BRISVOX_TWILIO_ALLOW_STATIC_URL=1 (TwilioConfig::allow_static_url): the fixed URL is accepted again (also next to per-call URLs when a secret is set), with the replay risk described above, and the server logs a warning at startup. Without a secret and without the flag the Twilio listener does not start.

Migrating from the fixed URL. (1) Set BRISVOX_TWILIO_STREAM_SECRET (32 bytes or more) and keep BRISVOX_TWILIO_ALLOW_STATIC_URL=1 for the transition, so both forms are accepted. (2) Change the webhook that answers inbound calls to return <Stream url="wss://host/twilio/stream/<segment>"> with a segment minted per call (the snippets above). Outbound calls and server-restarted streams need nothing. (3) Check that calls connect (a refused segment is an HTTP 403 to Twilio). (4) Remove BRISVOX_TWILIO_ALLOW_STATIC_URL; the fixed URL is then refused.

The listener's path is the base: /twilio/stream accepts /twilio/stream/<segment>. A gateway that rewrites the public path must keep the suffix (/voice/twilio/<segment> -> /twilio/stream/<segment>). Not verified live: that Twilio signs the per-call URL in the form the candidates cover (the same open item 1 as for the fixed URL).

Defensive handling of UNVERIFIED points

• Numbers as strings or numbers (sequenceNumber, chunk, timestamp, sampleRate, channels): both parse. The three the adapter does not depend on (sequenceNumber, chunk, timestamp) and connected.protocol / version are read softly: any other type ("1.0", "", a float, an object) reads as absent and never costs the message that carries it. A connected message that cannot be read is skipped. sampleRate and channels are checked, so a malformed one is a protocol error on start. customParameters values that are not strings are kept as JSON text.
• Binary frames from Twilio: ignored. Unknown events and fields: ignored. A missing connected: accepted. A missing track on media: treated as inbound.
• Keepalive: Twilio is not documented to ping or answer pings. The server pings every ping_interval and closes after ping_timeout without any frame; inbound media (every 20 ms while the call is up, UNVERIFIED) counts as life, so set ping_timeout well above a plausible silent gap (default 30 s).
• Chunk size: 160 bytes per outbound message is a brisvox choice, not a documented requirement; TwilioConfig::chunk_bytes changes it.
• Inbound audio loss: skipped media.chunk numbers are counted (inbound_chunks_lost), not reported to the engine.
• A clear while Twilio has nothing buffered is still sent (cheap, and the engine's ordering rule is "clear before new-epoch audio").

Gotchas found while implementing

• tokio-tungstenite's Callback for the upgrade returns the full HTTP response as the error (clippy result_large_err); the adapter implements Callback on a small struct and boxes the refusal internally.
• The accept loop of the generic server is shared by passing the per-connection serve function (ServeFn); TwilioServer wraps a WebSocketServer, so accept, shutdown and the active-call count are the same code.
• A clear must forget the marks in flight before the message goes out; otherwise an echo that races the clear would be taken for a played mark.
• Twilio accepts nothing but media/mark/clear from the server, so there is no way to send an error or a goodbye: faults go to the engine, fatal ones close the socket with a reason.

Open items to settle with a live test (needs a Twilio account, a number and a public wss URL)

1. Exact URL form Twilio signs for the WSS upgrade (scheme, port, trailing slash) and that header name casing is X-Twilio-Signature.
2. Inbound media cadence and frame size (ms per message); behaviour under backpressure (31930).
3. Residual audio heard after clear (ms), order/timing of the marks returned by clear, and whether a mark for the audio currently playing is returned immediately.
4. Whether media sent right after clear plays immediately and whether mark names may repeat or have a length limit.
5. Idle/keepalive behaviour (does Twilio ping? does it close idle sockets?), close codes, and what happens to the call when brisvox closes the WS (TwiML continues).
6. Whether numeric fields are ever sent as JSON numbers; whether binary frames ever occur.
7. Whether <Parameter> inside <Connect><Stream> works exactly as in <Start><Stream> (expected yes).
8. Playback latency Twilio adds between our media and the caller's ear (feeds the LATENCY.md budget).
9. Whether Twilio plays audio it buffered after brisvox closed the WebSocket (decides whether the "wait for the final MarkPlayed before Stop" rule is needed or merely safe), and whether a bounded drain in the adapter is worth adding.
10. Whether PlaybackPosition - PlaybackLead tracks what the caller heard (compare with the barge-in point reported by a test caller) and how stale PlaybackLead is at the 200 ms mark spacing.

Sources (all fetched 2026-10-08)

• https://www.twilio.com/docs/voice/media-streams (and .md)
• https://www.twilio.com/docs/voice/media-streams/websocket-messages (and .md; JSON examples taken from the .md)
• https://www.twilio.com/docs/voice/twiml/stream (and .md; TwiML examples, attributes, <Parameter>, status callback fields)
• https://www.twilio.com/docs/voice/twiml/connect (regions note; <Connect> action behaviour; no <Stream> section)
• https://www.twilio.com/docs/usage/security (and .md; signature algorithm, WSS trailing-slash note, bodySHA256)
• https://static1.twilio.com/docs/global-infrastructure/firewall-configurations/media-streams-configuration (port 443, any public IP, validate signature)
• https://www.twilio.com/docs/api/errors/31920 (WebSocket handshake error), /31921 (close error), /31923 (malformed URL), /31924 (protocol error), /31930 (buffer overflow, inbound), /31931 (media discarded, outbound 10 min), /31951 (invalid message)
• https://www.twilio.com/en-us/changelog/bi-directional-streaming-support-with-media-streams (2020-06-17; introduces Mark and Clear)
• Web search results (summaries, not primary text, used only where labeled UNVERIFIED): chunk size not documented; custom parameters not in the signed URL.
• Not fetched: Twilio sample apps (twilio/media-streams node/connect-basic, dialogflow-integration), the Stream REST resource page (https://www.twilio.com/docs/voice/api/stream-resource), voice pricing.

Fact-checked 2026-10-08: 58 claims checked, 11 corrected. Corrections: (1) outbound payload format quote replaced with the real wording ("encoded audio/x-mulaw with a sample rate of 8000..."; the unfound sentence "Providing header bytes causes the media to be streamed incorrectly" and "raw mulaw/8000" removed); (2) "Audio can be any size" -> "The audio can be of any size."; (3) mark return wording is "or if there is no audio buffered" (no word "immediately"; timing now UNVERIFIED); (4) clear quote replaced with the real wording and the invented "so you know which media was discarded" quote dropped; (5) mark name description is "A custom value", not "a name of your choosing"; (6) secondary Auth Token quote corrected; (7) stop semantics: messages page says only ending the call stops a bidirectional stream, overview page and 31921 say closing the WebSocket does too (both now stated; the old 31921 and "Bidirectional Streams stop only..." quotes removed as non-verbatim); (8) "Only wss is supported"/"Query string parameters are not supported" and other non-verbatim quotes (changelog, 31930, 31931, 31951, "one WebSocket connection") turned into paraphrases; (9) Ruby/Go validator names completed; (10) a media example on the messages page shows track: "outbound", noted; (11) Answering Machine Detection in the shared four-track list marked UNVERIFIED (overview names only SIPREC and Real-Time Transcription).

Telnyx Media Streaming (bidirectional) — telephony transport

Scope: the Telnyx counterpart of the Twilio adapter (verify docs). Twin of docs/providers/twilio.md (read that first for the shared design: mu-law/A-law via docs/providers/g711.md, buffer-clear on interruption, playback tracking via marks feeds played-text truncation). Related: docs/providers/call-control.md (DTMF, transfer). Researched: 2026-10-08. Every fact below was read from the pages listed under Sources on that date. Anything not confirmed is marked UNVERIFIED. This is a transport, not an STT/LLM/TTS provider: Telnyx is the WebSocket CLIENT, brisvox is the WebSocket SERVER (same role as Twilio).

How the facts were obtained: the Telnyx pages were read through a summarizing fetch tool. The authoritative JSON examples and schemas below come from the AsyncAPI 3.0.0 spec (v2.0.0) that Telnyx links from its docs (https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/media-streaming/media-streaming.yml, read raw on 2026-10-08), so field names, types, enums and examples are exact. Prose rules (limits, mark semantics) are quoted/paraphrased from the guide and API reference. The guide's own JSON blocks could not be reproduced by the tool; they were checked only as key lists and agree with the spec.

• Docs: https://developers.telnyx.com/docs/voice/programmable-voice/media-streaming (fetched 2026-10-08); WebSocket spec https://developers.telnyx.com/api-reference/websockets/stream-call-media-over-websocket (fetched 2026-10-08); full source list at the bottom.
• Auth / trust:
  • Starting a stream (REST): Authorization: Bearer <API key> on POST https://api.telnyx.com/v2/.... That is Telnyx's API, not brisvox's; brisvox core does not hold it unless it also hangs up or transfers via REST (see "Ending the call").
  • The WebSocket itself has NO signature (no X-Telnyx-Signature-style header is documented for the upgrade). The only documented authenticity mechanism is an optional shared token: the stream_auth_token field of streaming_start and of dial (string, max length 4000; streaming_start reference: "An authentication token to be sent as part of the WebSocket connection"). When configured, Telnyx sends it as the WebSocket upgrade header x-telnyx-streaming-auth-token AND in the first frame as connected.x-telnyx-streaming-auth-token (spec: "When a streaming auth token is configured, Telnyx includes it in the connected.x-telnyx-streaming-auth-token field and sends it as the x-telnyx-streaming-auth-token WebSocket header"). Brisvox should compare it in constant time and refuse the upgrade (HTTP 401/403) on mismatch. Never log it.
  • stream_auth_token is listed on the Call Control streaming_start reference and on the dial (POST /v2/calls) reference (first ~100k of 168k characters of the dial page read; the stream_* parameters are all in that part). It is NOT listed in the answer request parameters (whole page, 129k characters, read in two fetches on 2026-10-08), not in the media-streaming guide, and not a TeXML <Stream> attribute. So with answer or TeXML you cannot set it; start the stream with streaming_start after answering, or authenticate with a secret in the URL path or a custom parameter (see below). Exact upgrade-header casing: UNVERIFIED (spec writes it lower case).
  • custom_parameters (streaming_start: array of {name, value}; TeXML: <Parameter name= value=>) arrive in start.custom_parameters (a map of strings). They are part of a WS message, not the upgrade, and not signed; treat as untrusted unless the token/URL secret validated. Top-level custom_parameters was not found on answer or in the part of dial that was read (UNVERIFIED there; it exists on streaming_start).
  • Network allowlist: Telnyx does not publish a separate stream source-IP list. The IP-whitelisting page says for the webhook CIDRs: "These ranges also apply to WebSocket stream connections." Webhook CIDRs: CH1 192.76.120.128/29, DC2 192.76.120.136/29, SV1 192.76.120.144/29, LD6 185.246.41.0/29, FR5 185.246.41.8/29, AM6 185.246.41.16/29, SY1 103.115.244.0/29, SG1 103.115.244.8/29; webhooks use TCP 443. The list may change (the page does not say how often): fetch it again before pinning (UNVERIFIED that it is complete for WS).
  • Webhooks (not the WS) are signed: headers telnyx-signature-ed25519 and telnyx-timestamp (stated on the TeXML stream callback reference page; that page notes the headers are compatible with the Standard Webhooks spec and can be mapped to webhook-timestamp/webhook-signature). The algorithm being Ed25519 is inferred from the header name; the page does not describe verification steps (UNVERIFIED). Only relevant if brisvox ever serves the Call Control webhook; it does not (the user's HTTP app does). Crate/verification details not researched.
• Endpoint(s) / regions:
  • Brisvox hosts a wss:// endpoint (the spec's server is wss, host/path chosen by the customer, address /). TLS certificate requirements, supported TLS versions, accepted ports and whether ws:// is accepted: NOT stated (UNVERIFIED; use a publicly trusted certificate on 443). Query strings in stream_url: not forbidden in the docs seen (Twilio forbids them); UNVERIFIED, so prefer path secret + parameters.
  • Regions: no region selection for streaming found (UNVERIFIED). Telnyx source regions are the webhook CIDRs above.
  • Prerequisite (third-party integration guide found by search, not Telnyx docs, so UNVERIFIED; not re-checked in the 2026-10-08 fact check): a Call Control app with a webhook URL is needed for programmable calls; a plain number connection is not enough.
• How a call is set up to stream. Four ways (all documented):
  1. Call Control dial (POST /v2/calls) with stream_url, stream_track, optionally stream_bidirectional_mode, stream_bidirectional_codec (guide's examples). The dial reference also lists stream_codec, stream_bidirectional_target_legs, stream_bidirectional_sampling_rate, stream_auth_token and stream_establish_before_call_originate (boolean, default false; meaning not read: UNVERIFIED).
  2. Call Control answer (POST /v2/calls/{call_control_id}/actions/answer) with the same stream_* fields (answer reference lists stream_url, stream_track, stream_codec, stream_bidirectional_mode, stream_bidirectional_codec, stream_bidirectional_target_legs; it does NOT list stream_bidirectional_sampling_rate or stream_auth_token, whole page read). Setting stream_url also triggers streaming.started / streaming.stopped / streaming.failed webhooks (streaming.failed is not named in the pages re-read on 2026-10-08; the guide and streaming-stop page name streaming.started and streaming.stopped: streaming.failed UNVERIFIED).
  3. Call Control streaming_start on a live call (POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/streaming_start).
  4. TeXML: <Start><Stream> (asynchronous, call flow continues) or <Connect><Stream> (synchronous: the call flow waits until streaming stops, then the instructions after <Connect> run; the Connect page says "The following instructions will be executed when the service is stopped"; it has no XML example, so the <Connect><Stream ...> snippet further below is derived, not a doc sample). TeXML REST also has POST /v2/texml/Accounts/{account_sid}/Calls/{call_sid}/Streams.json (form-encoded Url, Track, Name, BidirectionalMode, BidirectionalCodec (PCMU|PCMA|G722 there), StatusCallback, StatusCallbackMethod).
  • Only ONE streaming/fork operation per call ("Currently only one streaming/fork operation is supported per call"); a media-forking request "will be stopped and replaced by a RTP connection" (the WS stream is replaced). The streaming_start reference shows generic 422 examples (not stream-specific): invalid call control ID (90015), call already ended (90018), call not answered yet (90034), "Media Streaming is used" (90045, detail "This command can't be issued when media streaming is used"), plus 10004/10032/10033 validation errors.
  • Brisvox example (derived, not a doc sample; JSON key names are from the streaming_start reference):

    POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/streaming_start
    Authorization: Bearer <API key>
    {
      "stream_url": "wss://agent.example.com/telnyx/stream",
      "stream_track": "inbound_track",
      "stream_codec": "PCMU",
      "stream_bidirectional_mode": "rtp",
      "stream_bidirectional_codec": "PCMU",
      "stream_bidirectional_target_legs": "opposite",
      "stream_bidirectional_sampling_rate": 8000,
      "stream_auth_token": "<random secret>",
      "custom_parameters": [ { "name": "agent", "value": "support-tr" } ],
      "client_state": "<base64>",
      "command_id": "<unique>"
    }
    

    The same fields exist as top-level stream_* fields on dial (with stream_auth_token) and, except stream_bidirectional_sampling_rate/stream_auth_token, on answer. TeXML equivalent (derived; attributes from the TeXML <Stream> page; no bidirectional XML example exists in the docs):

    <Response>
      <Connect>
        <Stream url="wss://agent.example.com/telnyx/stream" bidirectionalMode="rtp" bidirectionalCodec="PCMU"
                bidirectionalSamplingRate="8000" enableReconnect="false">
          <Parameter name="agent" value="support-tr" />
        </Stream>
      </Connect>
    </Response>
    

  • streaming_start parameters (exact, reference page; no field is marked required): stream_url (string, e.g. wss://www.example.com/websocket); stream_track (inbound_track default | outbound_track | both_tracks); stream_codec (PCMU|PCMA|G722|OPUS| AMR-WB|L16|default, default default; "When set to 'default' or when transcoding is not possible, the codec from the call will be used"); stream_bidirectional_mode (mp3 DEFAULT | rtp); stream_bidirectional_codec (PCMU default | PCMA|G722|OPUS|AMR-WB|L16; used only with mode rtp; case sensitive); stream_bidirectional_target_legs (both|self|opposite, default opposite); stream_bidirectional_sampling_rate (integer 8000 default | 16000 | 22050 | 24000 | 48000); enable_dialogflow (bool, default false), dialogflow_config (analyze_sentiment, partial_automated_agent_reply, both bool default false); client_state (base64); command_id (dedupe per call_control_id); custom_parameters; stream_auth_token (max 4000). Response 200 {"data":{"result":"ok"}}; 422/default errors[] with code, title, detail, source.
  • TeXML <Stream> attributes (exact): url (required), track, name, codec (PCMU|PCMA|G722|OPUS|AMR-WB| default; "Currently, transcoding is only supported between PCMU and PCMA codecs"), bidirectionalMode (mp3 default|rtp), bidirectionalCodec (PCMU default|PCMA|G722|OPUS|AMR-WB), bidirectionalSamplingRate (8000 default|16000| 24000), statusCallback, statusCallbackMethod (GET|POST, default POST), enableReconnect (default true). Child <Parameter name= value=>. Status callbacks: stream-started, stream-stopped, stream-failed. Doc examples on the page use <Start><Stream url="wss://yourdomain.com/stream" track="both_tracks" /> and a statusCallback + <Parameter> variant. Docs discrepancy: Call Control allows rates 22050/48000, TeXML only 8000/16000/24000, and the TeXML <Stream> codec list has no L16; use Call Control for L16.
• Protocol (messages in/out, with field names). All frames are JSON text frames (binary frames not mentioned: UNVERIFIED). Field names are snake_case; stream id key is stream_id (a UUID), not streamSid.
  • Telnyx -> server, in order (spec "Connection Flow"): connected, start, then media (repeating) and optionally dtmf / mark / error, finally stop.

    { "event": "connected", "version": "1.0.0" }
    

    With a configured token:

    { "event": "connected", "connected": { "x-telnyx-streaming-auth-token": "3c8b06a4-94a8-4d03-9fd1-941bc3f7166a" }, "version": "1.0.0" }
    

    {
      "event": "start",
      "sequence_number": "1",
      "stream_id": "32DE0DEA-53CB-4B21-89A4-9E1819C043BC",
      "start": {
        "user_id": "3E6F995F-85F7-4705-9741-53B116D28237",
        "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
        "call_session_id": "ff55a038-6f5d-11ef-9692-02420aeffb1f",
        "from": "+13122010094",
        "to": "+13122123456",
        "tags": [ "TAG1", "TAG2" ],
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "custom_parameters": { "customer_id": "customer_123" },
        "media_format": { "encoding": "PCMU", "sample_rate": 8000, "channels": 1 }
      }
    }
    

    {
      "event": "media",
      "sequence_number": "4",
      "stream_id": "32DE0DEA-53CB-4B21-89A4-9E1819C043BC",
      "media": { "track": "inbound", "chunk": "2", "timestamp": "5", "payload": "no+JhoaJjpzSHxAKBgYJDhtEopGKh4aIjZm7JhILBwYIDRg1qZSLh4aIjJev" }
    }
    

    { "event": "dtmf", "stream_id": "32DE0DEA-53CB-4B21-89A4-9E1819C043BC", "occurred_at": "2025-06-05T08:54:19.698408Z",
      "sequence_number": "5", "dtmf": { "digit": "1" } }
    

    { "event": "mark", "sequence_number": "5", "stream_id": "32DE0DEA-53CB-4B21-89A4-9E1819C043BC", "mark": { "name": "some_mark_name" } }
    

    { "event": "stop", "sequence_number": "5", "stream_id": "32DE0DEA-53CB-4B21-89A4-9E1819C043BC",
      "stop": { "user_id": "3E6F995F-85F7-4705-9741-53B116D28237", "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ" } }
    

    { "event": "error", "stream_id": "32DE0DEA-53CB-4B21-89A4-9E1819C043BC",
      "payload": { "code": 100004, "title": "invalid_media", "detail": "Media provided was not base64 encoded" } }
    

  • Field notes (spec schemas; every Telnyx-sent object has additionalProperties: false, so unknown fields are not expected, but ignore them anyway for forward compatibility):
    • connected: required event, version (string, protocol version, example 1.0.0); optional connected object with optional x-telnyx-streaming-auth-token. NOTE: connected has no sequence_number/stream_id.
    • start: required event, sequence_number, stream_id (UUID), start. Required inside start: user_id (UUID), call_control_id, media_format. Optional: call_session_id (UUID), from, to ("Caller number or SIP URI when available" for from; "Callee number or SIP URI when available" for to), tags (strings), client_state (base64 string), custom_parameters (string -> string). media_format.encoding enum PCMU|PCMA|G722|OPUS|AMR-WB|L16; sample_rate integer enum 8000|16000; channels integer, constant 1. The spec has no track list in start (Twilio has tracks).
    • media: required event, sequence_number, stream_id, media{track, chunk, timestamp, payload}. track enum inbound|outbound ("Call leg track that produced the media frame"); chunk string, "Per-stream media chunk number. Use to reorder media frames if needed."; timestamp string, "RTP timestamp associated with this media frame." (so NOT milliseconds like Twilio; units/clock rate, wrap-around and relation to ms: UNVERIFIED; the example "5" next to chunk "2" can't be interpreted); payload base64 "RTP payload without RTP headers".
    • sequence_number: string, "Monotonic sequence number for frames sent by Telnyx on this WebSocket connection." connected and error frames carry none.
    • TYPES: sequence_number, chunk, timestamp are JSON STRINGS in schema and examples; sample_rate, channels and error code are numbers. Parse strings; accept numbers too, defensively (as for Twilio).
    • dtmf: required event, sequence_number, stream_id, dtmf.digit; optional occurred_at (date-time, "Timestamp captured by the telephony engine. Use this to order DTMF events if they arrive out of order."). Digit enum: 0-9, *, #, A, B, C, D. No track field (Twilio has dtmf.track).
    • stop: sent "when Telnyx stops media streaming for the call" (spec). The guide says it is sent when the call ends, after the streaming.stopped webhook; whether it is also sent when the stream is stopped via REST while the call stays up: not stated in the pages (UNVERIFIED). Carries stop.user_id and stop.call_control_id.
    • error: required event, stream_id, payload{code, title, detail}; code/title enum: 100002 unknown_error, 100003 malformed_frame, 100004 invalid_media (example detail "Media provided was not base64 encoded"), 100005 rate_limit_reached (guide: "Too many requests"). Whether the stream/connection survives an error frame: not stated (UNVERIFIED).
  • Ordering: "The order of events is not guaranteed and the chunk number can be used to reorder the events." (guide); the spec says to use media.chunk, media.timestamp and sequence_number. This is a real difference from Twilio: brisvox needs a small bounded reorder buffer keyed on media.chunk (and tolerate gaps), and DTMF should be ordered by occurred_at. How far out of order frames get, and the reorder window to use: UNVERIFIED (measure live). Whether the start frame can arrive after a media frame: not stated.
  • Server -> Telnyx (bidirectional; client schemas also have additionalProperties: false):

    { "event": "media", "media": { "payload": "eW91ciBiYXNlNjQgZW5jb2RlZCBhdWRpbyBwYXlsb2Fk" } }
    

    { "event": "mark", "mark": { "name": "some_mark_name" } }
    

    { "event": "clear" }
    

    These carry NO stream_id (Twilio requires streamSid on every message). Because the schemas forbid extra properties, sending a stream_id may be rejected as malformed_frame (100003): inference from the schema, not a doc sentence, UNVERIFIED. Pipecat's official Telnyx serializer sends exactly {"event":"media","media":{"payload":...}} and {"event":"clear"} with no stream id (source read 2026-10-08; it stores stream_id but never sends it), which is consistent. There is no server->Telnyx stop, and no documented way to send DTMF or an error to Telnyx over the socket.
• Outbound audio format and chunking:
  • Bidirectional mode rtp: payload = base64 of the RTP payload (no RTP header) in the codec chosen by stream_bidirectional_codec (default PCMU). Guide table of codecs and rates: PCMU 8 kHz (default), PCMA 8 kHz, G722 8 kHz, OPUS 8 and 16 kHz, AMR-WB 8 and 16 kHz, L16 16 kHz. Verbatim warnings: when audio is sent in a different encoding than the call's "it will be transcoded, which may cause a degradation in quality"; the guide recommends L16 for AI voice agents (lower latency, no transcoding overhead). So the call's own codec (negotiated by the carrier/SIP leg) matters; the start.media_format tells the INBOUND encoding actually streamed.
  • Chunk size: "Provided chunks of audio can be in a size of 20 milliseconds to 30 seconds" (RTP mode). So Telnyx accepts large chunks, unlike a fixed 20 ms pacing; brisvox can still use 20 ms frames (160 bytes PCMU at 8 kHz). Minimum is 20 ms: smaller chunks are probably rejected or merged (UNVERIFIED; do not send < 20 ms).
  • L16 byte order (big/little endian), and whether it is raw linear PCM16: the docs say "L16" and "linear PCM" only; RFC 3551 L16 is network byte order, but Telnyx does not state it: UNVERIFIED (test live before using L16).
  • Rate limit: the guide says "Media payloads can only be submitted once per second." and this sentence sits under the guide's "Sending media files" subsection (MP3 files) of "Bidirectional media streaming", not under "Sending RTP stream". The spec adds MP3 frames are "played in submission order, with a one-message-per-second rate limit"; its RTP sentence ("RTP media chunks sent back to Telnyx can contain 20 milliseconds to 30 seconds of audio") carries no rate limit. So per the docs the once-per-second limit is for MP3 file payloads; that it does not apply to RTP-mode media frames (50/s at 20 ms) is an inference, not a doc sentence (UNVERIFIED): confirm live and watch for error 100005.
  • MP3 mode (the DEFAULT mode when stream_bidirectional_mode is not set): media.payload is a base64 MP3 FILE, queued and played in order. Not suitable for streaming TTS: always set stream_bidirectional_mode to rtp. A stream started without it would take brisvox PCM/G.711 frames as broken MP3 (UNVERIFIED consequence). (Note the guide's dial example for rtp also shows rtp explicitly.)
  • stream_bidirectional_target_legs: opposite (default), self, both "Specifies which call legs should receive the bidirectional stream audio". For an inbound call answered by brisvox the stream is on the caller's leg; the meaning of opposite for a single-leg inbound call is not explained in the pages read: UNVERIFIED. Test whether the caller hears the audio with defaults, else set self.
  • Tracks: stream_track selects inbound_track (caller audio; default), outbound_track (audio Telnyx plays to the caller, i.e. includes brisvox's own bidirectional audio, UNVERIFIED), or both_tracks. For the agent use inbound_track only; media.track is inbound for that. Drop frames whose track is not inbound.
  • Buffer capacity (Twilio: 10 minutes): not documented for Telnyx (UNVERIFIED). Whether brisvox may send ahead of real time and rely on clear: implied by the clear/mark text below but the queue size limit is unknown.
• Mark semantics (guide + spec):
  • Server sends mark after the media to track. Telnyx returns {"event":"mark",...,"mark":{"name":..}} "when the media immediately preceding a submitted mark finishes playing. If no audio is playing or queued, the mark is returned immediately." (spec). Guide: "Submitting marks when no audio is played or queued will result in them being immediately sent back." This is stated explicitly for Telnyx (Twilio only implies it).
  • clear: guide "Sending a clear message will immediately stop the media playing on the stream and clear the media queue." Spec: "Stops the current media playback and clears queued media. Queued marks are sent back by Telnyx." So the pattern is the same as Twilio: marks for cleared audio are echoed with the same JSON as played marks; brisvox must track locally that it sent clear and drop the echoes (exactly as the Twilio adapter forgets in-flight marks before sending clear). Note the improvement over Twilio: clear "immediately stops the media playing", i.e. also the currently playing chunk (Twilio says it empties the buffer). Residual audio already in the phone network: UNVERIFIED.
  • Marks carry no timestamp or played-sample count; the mark name is a free string ("Customer-defined mark name"; length and charset limits not documented, UNVERIFIED; reuse the Twilio scheme e<n> / p<n>). Whether two in-flight marks may share a name: not stated (use unique names).
  • Whether a mark echo arrives in order relative to media/dtmf frames: no ordering guarantee exists for Telnyx frames in general (see Ordering); use mark names, not arrival order, to match.
  • Whether marks work in MP3 mode: the guide says they track when media "ends on the stream"; not stated which modes. Use rtp mode.
  • Playback tracking design for played-text truncation is identical to Twilio's (progress marks every ~200 ms plus utterance-end marks; heard = confirmed marks + estimate of the unconfirmed tail); see twilio.md "Marks, clear and played-text tracking".
• Interruption (barge-in): send {"event":"clear"} the moment the turn epoch advances, before any new-epoch audio; stop sending old-epoch media; drop mark echoes that follow the clear (they refer to cleared audio). Whether media sent right after clear plays normally: implied (queue emptied), not stated (UNVERIFIED).
• Keepalive / timeouts / reconnect:
  • No ping interval, idle timeout, maximum stream duration or close codes are documented (UNVERIFIED). Brisvox applies its own timeouts (time to first start after upgrade, stall timer on inbound media, ping/pong from our side as in the generic WebSocket server). Inbound media cadence and frame duration: not documented (UNVERIFIED; the spec says a media frame carries one RTP payload, plausibly 20 ms).
  • Reconnect: TeXML <Stream enableReconnect> (default true): "Whether the platform should automatically attempt to reconnect the WebSocket stream if disconnected." The TeXML page suggests enableReconnect="false" "to end the stream when the WebSocket disconnects" (page: end the stream immediately on disconnection). If reconnect is on and brisvox closes the socket (e.g. hang-up attempt) Telnyx may reconnect and deliver a fresh connected/start for the same call; for the engine this means the same call_control_id could reach the server twice (inference, UNVERIFIED). Brisvox must (a) recommend enableReconnect="false" for <Stream>, (b) key sessions by call_control_id and refuse/close a second connection for a live or ended call. Whether Call Control streams have an equivalent setting (none in streaming_start) and whether stream_id stays the same after a reconnect: UNVERIFIED.
  • streaming.failed webhook (and TeXML stream-failed) = "Stream failed to start or was interrupted". The TeXML stream-failed wording ("failed to start or was interrupted") is confirmed on the TeXML stream page; the Call Control streaming.failed webhook name was not found on the pages re-read on 2026-10-08 (UNVERIFIED).
  • Closing the WS from the server: the guide does NOT say closing the WebSocket stops the stream or ends the call (UNVERIFIED). For <Connect><Stream> the next verbs run after the service stops; whether a server-initiated close counts as "stops" is not stated.
• Ending the call / stopping the stream (differs from Twilio):
  • There is no server->Telnyx stop message and (unlike Twilio) closing the socket is not documented as a hang-up. To hang up, call REST POST /v2/calls/{call_control_id}/actions/hangup (body optional fields client_state, command_id, custom_headers (SIP BYE headers); 200 {"data":{"result":"ok"}}; 422 codes 90015 invalid call control ID, 90018 call already ended; webhooks call.hangup, call.recording.saved). Pipecat's Telnyx serializer does exactly this (auto_hang_up default on, needs call_control_id and API key) on its EndFrame/CancelFrame.
  • To stop only the stream: POST /v2/calls/{call_control_id}/actions/streaming_stop with optional stream_id (UUID; if omitted "stops all streams associated with the call_control_id"), client_state, command_id (the request body object itself is marked required, all its fields optional, so send {}); sends the streaming.stopped webhook; 422 codes 90015/90018/90034. The TeXML equivalent ("update streaming") "moves the stream to a completed state and closes its WebSockets" (TeXML streams overview page).
  • Consequence for brisvox: the engine's Hangup needs a REST client (API key + call_control_id from start), supplied by the host app; a transport-level hang-up by closing the socket alone may leave the call up (UNVERIFIED either way). Provide a pluggable hang-up callback (e.g. a Hangup hook that calls the REST API) in the adapter config, and still close the socket after.
  • As with Twilio, to play a goodbye: send audio, then an utterance-end mark, wait for the echoed mark (own timeout), then hang up.
• Webhooks around the stream (Call Control; field names from the guide as key lists): streaming.started and streaming.stopped have top-level event_type, id, occurred_at, payload, record_type; payload has call_control_id, stream_url (the top-level key list was not re-confirmed on 2026-10-08, only the payload keys: UNVERIFIED). call.answered carries stream_url, stream_track (not re-confirmed: UNVERIFIED). TeXML statusCallback payload fields: not found (the stream callback reference page had no schema: UNVERIFIED). These are HTTP callbacks to the user's app, not to brisvox core.
• Timestamps / interim results / tool-call deltas: not applicable. Relevant timing data: inbound media.timestamp is an RTP timestamp string (not ms), chunk counter (gaps = lost or reordered inbound audio), sequence_number counts every Telnyx-sent frame; outbound media has no timestamp or chunk field.
• Concurrency / rate limits: one streaming/fork operation per call; one bidirectional RTP stream per call (guide: "The number of bidirectional RTP streams per call is limited to 1."); media chunk 20 ms to 30 s; "Media payloads can only be submitted once per second" (guide places it under media-file/MP3 sending, see above); error 100005 rate_limit_reached. Per-account concurrent stream limits, pricing and messages-per-second for RTP: NOT found (UNVERIFIED).
• Turkish support: not applicable to the transport (language-agnostic audio). Telephony quality note as in twilio.md: PCMU/PCMA 8 kHz is narrowband; L16/G722/OPUS 16 kHz (if the call leg negotiates it) gives wideband audio that Deepgram/Cartesia can use directly. Whether a Turkish PSTN call ever negotiates a wideband codec: UNVERIFIED (carrier dependent).

Differences from Twilio (summary)

(The Twilio column was not re-checked in the 2026-10-08 fact check; see twilio.md for its sources.)

Mapping to the brisvox transport trait (proposal reusing the Twilio adapter structure, check the real trait when implementing)

• Inbound: parse by event; connected (check token header/field if configured), start -> CallInfo (call_id = call_control_id; metadata transport=telnyx, stream_id, call_control_id, call_session_id, user_id, from, to, tags, client_state, encoding, sample_rate, custom.<name>), media (track inbound) -> reorder buffer (by chunk) -> decode by start.media_format.encoding: PCMU/PCMA via brisvox_audio::codec (g711.md); L16 (16 kHz) as PCM16; G722/OPUS/AMR-WB not decodable in-tree (refuse with a clear error, or require a codec in stream_codec) -> PCM16 AudioFrame. dtmf -> DTMF event (ordered by occurred_at), mark -> MarkAck or drop (post-clear), stop -> hang-up (PeerHangup), error -> fault (code in message), unknown event ignored. Drop frames whose stream_id differs from start.
• Outbound: PCM16 at the stream rate -> encode in the SAME codec set as stream_bidirectional_codec (document that the host must set stream_bidirectional_codec equal to the inbound encoding to avoid transcoding; start-time config is the host's job) -> base64 -> {"event":"media","media":{"payload":..}}; marks e<n>/p<n> as in the Twilio adapter; clear per rule above. The adapter must know the outbound codec: it is NOT announced in start (that is the inbound media_format). Make it a TelnyxConfig field (default PCMU 8 kHz) and assert it equals start.media_format when inbound==outbound is expected.
• Auth: constant-time compare of x-telnyx-streaming-auth-token (upgrade header; fall back to connected.*) with the configured secret; additional option of a secret path segment. 401/403 on mismatch before the upgrade completes. The token can only be set via streaming_start or dial, not answer/TeXML (see Auth), so the path secret is the fallback.
• Hang-up: host-provided async hook (REST hangup), plus close frame; see "Ending the call".
• Reuse of the Twilio server infrastructure (call limit, accept queue, ping/idle/write timeouts, mark bookkeeping) is expected; the new parts are the reorder buffer, snake_case/UUID parsing, the codec choice and the hang-up hook.
• Gotchas found during implementation (brisvox_transport::telnyx, tests with a scripted peer only):
  • The reorder buffer anchors on the first frame it sees. If chunk 2 overtakes chunk 1 at the very start, chunk 1 is dropped as late (20 ms). The first chunk number is not documented (UNVERIFIED), so nothing is assumed.
  • A frame arriving while earlier ones are held takes the buffer path even when it is the chunk due (it is released at once); media_reordered counts those too.
  • Frames may overtake start (nothing says they cannot): they are dropped and counted, at most 64, then the connection is refused (1008). Tested with a start timeout of 30 s: the 65th frame refuses (media_before_start == 65), 64 frames followed by start open the call.
  • Review fixes (verified findings), all by the adapter's own tests with a scripted peer:
    • A stream the HOST stops on purpose (streaming_stop, e.g. the retry after a transfer/conference command was refused with 90045) must not look like the caller hanging up. Telnyx then closes the socket; whether it sends stop first is UNVERIFIED (open item 7). Without help the adapter would report a hang-up to the engine (ending its session and the tool call in flight) or have the hook REST-hang-up the call being transferred. Additive API: TelnyxServer::stream_stopper() returns a cloneable StreamStopper; expect_stop(call_control_id) is called BEFORE streaming_stop and returns whether the call streams here. For STOP_EXPECTED_WITHIN (30 s; a conservative window that covers the REST call plus the close, and makes a forgotten announcement harmless) a stop frame, a close frame or a vanished socket of that call is the host's own doing: no hook call, no hang-up event (the session is kept, what the engine sends is discarded), the call key stays claimed (a TeXML reconnect is refused). The session ends when the engine ends it, the server shuts down or after STOPPED_LINGER (120 s, conservative upper bound for a retried transfer; the engine then sees the peer disconnect). Intended caller: the call-control binding's 90045 retry path, which must call expect_stop before it issues streaming_stop (the API is additive; the binding itself is a separate change).
    • max_control_bytes (default 16 KiB) bounds control messages only. A media frame is bounded by max_audio_bytes (default 64 KiB; about 32 KiB of G.711, 43 KB of base64) through the websocket limit and the payload check; it used to be rejected as "control message too large" (1009, call hung up) above 16 KiB although Telnyx documents no size for inbound chunks. Everything that is not media, or does not parse, is still bounded by max_control_bytes.
  • Header casing of the token is irrelevant to the code (HTTP header names are case-insensitive), so open item 1 only concerns whether the header is sent at all; the adapter accepts the token from either place and refuses a wrong one from either.
  • DTMF is ordered by sequence_number (a per-connection counter shared with every other frame, so it has gaps) after a short hold (reorder_timeout), not by occurred_at; both work, the counter avoids parsing RFC 3339.
  • Not done: L16 (byte order), G722/OPUS/AMR-WB, stream_track=both_tracks (chunk numbering across tracks is undocumented), a transport-level REST hang-up (the host passes a HangupHook), per-account stream limits.

Open items to settle with a live test (needs a Telnyx account, a number, a Call Control app and a public wss URL)

1. Exact header casing of x-telnyx-streaming-auth-token on the upgrade; whether answer/TeXML have an undocumented way to set it (docs: only streaming_start and dial list stream_auth_token).
2. Whether media frames in rtp mode are subject to the "once per second" rule (expected not; the guide puts the rule under media-file sending), and the behavior on 100005.
3. How out-of-order inbound frames really are (window size for the reorder buffer); unit of media.timestamp; media cadence.
4. L16 byte order and exact sample format; effect of stream_bidirectional_sampling_rate vs codec (PCMU at 16000?) and which sample rate start.media_format reports for each combination; whether 24000/48000 work with L16/OPUS.
5. Meaning of stream_bidirectional_target_legs for a single-leg inbound call (does opposite reach the caller?).
6. Residual audio after clear; whether marks echoed by clear arrive before or after other frames; whether media after clear plays at once.
7. Whether closing the WS ends the call, stops the stream, or triggers reconnect (and enableReconnect behavior); close codes; keepalive.
8. Whether a stream_id in server frames is rejected (malformed_frame) or ignored; whether extra properties are tolerated.
9. Whether Telnyx plays queued audio after the server closes the socket; error frame effect on the connection.
10. Latency Telnyx adds between our media and the caller's ear (feeds the LATENCY.md budget).
11. Query strings in stream_url; TLS requirements; source IPs actually used (compare against the webhook CIDRs).

Sources (all fetched 2026-10-08; re-fetched and fact-checked 2026-10-08)

• https://developers.telnyx.com/docs/voice/programmable-voice/media-streaming (and .md; limits, codec table, mark/clear rules, error table, webhooks, dtmf, ordering)
• https://developers.telnyx.com/api-reference/websockets/stream-call-media-over-websocket (and .md; AsyncAPI summary, field descriptions)
• https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/media-streaming/media-streaming.yml (AsyncAPI 3.0.0 v2.0.0 raw; all JSON examples and schemas; token header)
• https://developers.telnyx.com/api-reference/call-commands/streaming-start.md (parameters, enums, defaults, response)
• https://developers.telnyx.com/api-reference/call-commands/streaming-stop.md (stream_id optional, streaming.stopped)
• https://developers.telnyx.com/api-reference/call-commands/answer-call.md (stream_* parameters; whole page read in two fetches, 129k characters)
• https://developers.telnyx.com/api-reference/call-commands/dial.md (stream_* parameters incl. stream_auth_token, stream_bidirectional_sampling_rate; first 100k of 168k characters read)
• https://developers.telnyx.com/api-reference/call-commands/hangup-call.md (hangup endpoint and error codes)
• https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/stream (and .md; attributes, enableReconnect, Parameter, callbacks)
• https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/connect.md (<Connect> synchronous; instructions after run when the service stops; no Stream XML example)
• https://developers.telnyx.com/docs/voice/texml/rest-api/streams.md and https://developers.telnyx.com/api-reference/texml-rest-commands/start-streaming-media-from-a-call.md (TeXML REST start/stop)
• https://developers.telnyx.com/api-reference/callbacks/texml-stream.md (webhook signing headers telnyx-timestamp, telnyx-signature-ed25519; no payload schema)
• https://developers.telnyx.com/docs/voice/sip-trunking/network-configuration/ip-whitelisting.md (webhook CIDRs apply to WebSocket streams; TCP 443)
• https://raw.githubusercontent.com/pipecat-ai/pipecat/main/src/pipecat/serializers/telnyx.py (official Pipecat serializer source: media/clear without stream id; REST auto hang-up)
• https://docs.pipecat.ai/api-reference/server/services/serializers/telnyx.md (serializer parameters; auto_hang_up)
• Web search summaries (not primary text, used only where labeled UNVERIFIED): Call Control app prerequisite from a third-party guide; the IP-allowlist answer was cross-checked against the fetched IP page.
• Not fetched / not researched: crates.io (no new crate is needed for this transport: JSON, base64 and tungstenite are already in the tree; Ed25519 webhook verification crate selection is out of scope since brisvox core does not serve the webhook), Telnyx pricing, per-account stream limits, Telnyx sample repos (team-telnyx on GitHub), the sip.telnyx.com voice.json file.

Fact-checked 2026-10-08: 62 claims checked, 9 corrected. Corrections: (1) stream_auth_token also exists on dial (POST /v2/calls), not only streaming_start; it is absent from answer (whole page read) and TeXML, so the old "unverified whether settable via dial" is resolved for dial/answer/TeXML; (2) dial also lists stream_bidirectional_sampling_rate and stream_establish_before_call_originate, while answer does not list the sampling rate (was UNVERIFIED); (3) the streaming_start description quote for stream_auth_token corrected to "An authentication token to be sent as part of the WebSocket connection"; (4) "once per second" is under the guide's "Sending media files" (MP3) subsection, not RTP; scope for RTP downgraded from "unclear" to "inference, UNVERIFIED"; (5) the claimed TeXML Connect page example (<Connect><Stream .../></Connect><Say>) does not exist on the Connect page; removed and the snippet is marked derived; (6) the 422 list under streaming_start is generic spec examples (90015, 90018, 90034, 90045, 10004, 10032, 10033), not stream-specific cases; (7) Ed25519 is inferred from the header name telnyx-signature-ed25519 (page gives no algorithm text), plus a Standard Webhooks compatibility note was added; (8) the guide says stop is sent when the call ends after streaming.stopped; the "or stream stopped via REST" part is UNVERIFIED; the streaming_stop body object is required (fields optional); (9) the Call Control streaming.failed webhook name, the webhook top-level key list and call.answered fields were not found in the re-read pages and are now marked UNVERIFIED. Still UNVERIFIED after re-check: top-level custom_parameters on dial/answer, the Call Control app prerequisite (third-party source, not re-checked), the Twilio comparison column (belongs to twilio.md), and all behavioral items in "Open items".

SIP / RTP — telephony transport (Rust stack selection)

Scope: research Rust SIP stacks; inbound/outbound call with RTP audio. Related: docs/providers/g711.md (codec), docs/providers/twilio.md (the Media Streams transport; depth and style example), docs/providers/webrtc.md (str0m based, the other RTP-carrying transport), docs/providers/call-control.md (DTMF, transfer), docs/ARCHITECTURE.md "Transport". Researched: 2026-10-08. Every fact below was read from the pages listed under Sources on that date (crates.io API, GitHub API/pages, docs.rs, vendor docs, RFCs). Anything not confirmed is marked UNVERIFIED. Caveat on method: the fetch tool summarizes pages with a small model, so code-level claims (method names, feature lists) are second-hand extracts, not source reads. The spike (section 3 below) must re-confirm the ones it depends on against the actual crate source before they are trusted. This is a transport, not an STT/LLM/TTS provider: brisvox is a SIP user agent (UAS for inbound calls, UAC for outbound calls); there is no HTTP/WebSocket leg.

• Docs: RFC 3261 (SIP), RFC 3264 (offer/answer), RFC 3550/3551 (RTP, G.711 payload types), RFC 4733 (telephone-event), RFC 4028 (session timers), RFC 3581 (rport), RFC 4961 (symmetric RTP); stack docs per candidate in the tables; source list at the bottom (all fetched 2026-10-08).
• Auth / trust (what the carriers do, not the stacks):
  • Twilio Elastic SIP Trunking termination (brisvox -> Twilio -> PSTN): IP ACL, credential list (SIP digest) or both; if both are configured both are enforced; Twilio warns IP ACL alone does not protect against certain attacks (elastic SIP trunking overview).
  • Telnyx: credentials (SIP username/password, works with dynamic IPs), FQDN (hostname based inbound routing, credentials or IP for outbound), IP + token (X-Telnyx-Token header), IP + tech prefix, IP + P-Charge-Info (Telnyx trunking docs, re-read 2026-10-08 in the fact-check).
  • Inbound trust in brisvox: INVITEs must be authenticated by source-IP allowlist (carrier ranges) and/or digest challenge (401/407). Never log credentials. An open UDP 5060 listener is scanned within minutes on the public internet (general knowledge, not a fetched fact): default-deny unknown sources.
• Endpoint(s) / regions: see "Interop targets". Brisvox listens on UDP 5060 (default), optional TCP 5060 and TLS 5061; RTP on a configured UDP port range (one socket per call).

1. Candidate stacks (state on 2026-10-08)

crates.io/GitHub data fetched 2026-10-08 (API JSON). "Pushed" = GitHub pushed_at.

1.1 Feature matrix (what the docs claim; "-" = not mentioned in what was fetched = UNVERIFIED unless stated absent)

Other facts worth knowing:

• rsipstack: ClientInviteDialog and ServerInviteDialog are marked deprecated in favour of invite_dialog::InviteDialog (docs.rs struct pages, latest; the dialog module index page itself shows no deprecation note). On InviteDialog, hangup() delegates to hangup_with_headers(), which picks BYE (confirmed) or CANCEL (early) and works for either role (CORRECTED from the 0.7.3 source in section 9: the docs.rs-derived claim that hangup() is BYE-only and a no-op on UAS dialogs was wrong). Four releases in three days (0.7.0-0.7.3) and a recent embassy/no_std refactor mean API churn: pin an exact version.
• rsiprtp CallManager (docs.rs): create_call(remote_uri) -> CallId does no DNS or socket I/O (resolve with SipResolver, RFC 3263), handle_incoming_invite(dialog, offer_sdp) -> Option<(CallId, SessionDescription, u16)> (the u16 is undocumented), answer_call, reject_call, terminate_call (BYE; only for Established calls), handle_bye, tick(now) / next_deadline() for session timers, drain_events() and drain_outbound_requests() as the output side. The caller opens the client/server transactions itself for the requests the manager builds (PRACK, UPDATE, BYE, re-INVITE). This is a bring-your-own-glue sans-IO API, which fits brisvox style but means the integration glue (UDP socket loop, transaction pump, timers) is ours. now is std::time::Instant (docs.rs signature tick(&mut self, now: Instant); the docs pass next_deadline() to tokio::time::sleep_until), so the injected Clock must convert to/from std::time::Instant (confirmed 2026-10-08; previously UNVERIFIED).
• rsiprtp dependencies (Cargo.toml): tokio, tokio-rustls/rustls/webpki-roots, hickory-resolver, audio-codec-algorithms, ezk-g722, ropus, aes/ctr/hmac/sha1/sha2/md5, bytes, uuid, serde; no optional features (default = []); the SIP parser is in-tree (rsip is a dev-dependency only). Version, license and MSRV are workspace-inherited (not in the crate Cargo.toml). No unsafe lint info available (workspace lints not read).
• rsiprtp repo contains CLAUDE.md, wrk_docs/, wrk_journals/ (page does not say whether code is AI-written). 205 commits, no releases or tags on GitHub, CI workflow present. GitHub repo created 2025-12-05.
• ezk: ezk-rtc says its goal is use cases beyond WebRTC "including SIP, which does not always require ICE or even SRTP"; it depends on openssl (build burden) plus ezk-ice, ezk-srtp, rtp-types, rtcp-types. ezk-rtc is at 0.0.1 with 298 downloads; the fetched part of the ezk README has no maturity statement.
• rvoip: workspace of 46 crates, MSRV 1.91 (README badge), 79 open issues; audio API is SessionHandle::audio() with AudioFrame/AudioSender/AudioReceiver/AudioStream (api::audio), fields not documented on the page fetched; send_dtmf is RFC 4733. Dependency and compile-time weight would be large (UNVERIFIED, 46 crates).
• xphone: the dedicated-thread-per-call model conflicts with the brisvox goal of hundreds of calls per container and the "no blocking work on tokio workers" / cancellation invariants (a thread per call is not a tokio worker, but it breaks the CancellationToken/Clock style and costs memory per call).
• wavekat-sip: GitHub About says "built on rsipstack"; the README says "from-scratch ... no external SIP stack" and credits only rsip for message types. Contradictory, UNVERIFIED which is true.
• PJSIP via FFI (pjproject-sys 1.0.0, 2023; a higher-level community repo "THE-PJPROJECT" by JadKHaddad exists, status not checked: UNVERIFIED): mature C stack with its own media threads and global state, GPL-2.0-or-later unless a commercial license is bought. Conflicts with the project's license preference (MIT/Apache/BSD), with the no-FFI-surprises ethos and with per-session isolation and deterministic simulation. Note only; not recommended.

2. Scored comparison

Scale 1 (poor) to 5 (strong). The scores are the author's judgement from the evidence above, NOT measured results; they were not validated against running code. Criteria are those named for the stack selection. "+own media" means the cost of the missing pieces is counted (we would write them).

Reading the table: rsiprtp scores highest on features and fit with the brisvox invariants but lowest on the maintenance evidence that matters most for a dependency we would carry for years (single maintainer who states no commitment to contributions, 5 months since the last push, 261 downloads, interop shown only against Asterisk, the AI-bridge example is a stub). rsipstack has the strongest maintenance and adoption signal and the permissive license, at the cost of writing the media half. rvoip is the broadest and the only one with a published multi-PBX interop gate, but it is a 46-crate workspace with an API that is still in preview outside SIP and 79 open issues.

3. Recommendation

Recommendation: Use rsipstack (MIT) for SIP signaling and write the media half in brisvox (brisvox-transport feature sip): minimal SDP offer/answer for PCMU/PCMA + telephone-event, an RTP session task per call, RFC 4733 receive/send, a small jitter/reorder buffer, G.711 through the existing brisvox_audio::codec (ulaw_encode/decode, alaw_encode/decode). Reasons: (1) signaling (transactions, dialogs, digest, TLS, retransmission timers) is the hard, interop-sensitive code and rsipstack is the most active and most adopted option (also the base of RustPBX); (2) the media half is small (12-byte RTP header, 160 G.711 bytes per 20 ms, 4-byte telephone-event payload) and is the hot path, where brisvox's own pacer, Clock, buffer reuse and CancellationToken rules matter and a library's media loop would get in the way; (3) tokio-native, MIT; (4) brisvox already owns the G.711 codec and resampler. Rejected: xphone (thread per call), PJSIP (GPL, FFI, global state), wavekat-sip (too young), ezk (no confirmed DTMF, OpenSSL in the media crate), rvoip (size, preview media layer).

Hedge (NOT BUILT): the draft proposed keeping the SIP stack behind a narrow internal trait (SipSignaling: register, accept invite, answer/reject, dial, hangup, in-dialog events) so rsiprtp (sans-IO, complete) or rvoip can replace rsipstack if the spike fails. The implementation did not build that trait: the spike worked, and inbound.rs, outbound.rs and call.rs use rsipstack types directly, so a stack swap would rewrite those three files (the media half, sdp.rs and rtp.rs, is stack-independent). Pin an exact rsipstack version (the 0.7.x line changed in 3 days; it is pinned with =0.7.3). Revisit if: rsipstack cannot be driven with injected time/sockets for deterministic tests, session timers are required by a target carrier and are painful to add, or an interop bug is unfixable.

Do-first spike (historical; superseded by the implementation, see section 9): build examples/sip_echo against rsipstack that answers an INVITE from a local sipp/Asterisk-in-docker/second brisvox UA, negotiates PCMU + telephone-event, echoes audio, sends BYE; read the real source for the UNVERIFIED items (session timers, fake transport, accept_with_public_contact, behaviour of 200-without-ACK, CANCEL race, forked responses).

4. Minimal integration plan

Architecture follows docs/ARCHITECTURE.md Transport: a protocol adapter that bridges SIP/RTP to call_pair() channels. Transport::accept(&mut self, cancel) -> Result<Option<CallLink>> stays the inbound API; outbound needs one extra method (see below). Wire events used: WireEvent::{Started, Audio, Dtmf, MarkAck, Lead, Fault, Hangup} and WireOut::{Audio, Clear, Mark, Hangup} (crates/brisvox-transport/src/call.rs, read 2026-10-08, re-checked in the fact-check).

1. One SIP UA endpoint per server (SipServer). Owns the UDP socket (and optional TCP/TLS listeners), the rsipstack Endpoint and the DialogLayer, one accept task (tracked by a TaskTracker), and the registration tasks for REGISTER-based accounts (not for Twilio trunks, see interop). Config: bind addr, public_ip/advertised host (SDP c= and Contact/Via), RTP port range, allowed source CIDRs, digest credentials for inbound auth, call limit, accept queue size, timeouts.
2. Inbound INVITE -> CallLink. (a) Check source allowlist / digest (401/407). (b) Over the call limit or accept queue full -> 503 Service Unavailable (plus Retry-After) like the Twilio server's 503; bad SDP/no common codec -> 488. (c) 100 Trying, bind the per-call RTP socket, 180 Ringing optional, answer 200 OK with SDP (our c=/port, PCMU/PCMA in the offerer's preference order restricted to what we support, telephone-event with the offerer's dynamic payload type, a=ptime:20, sendrecv). (d) On ACK: call_pair(), send WireEvent::Started(CallInfo) (metadata: Call-ID, From/To, remote address, selected codec, x-* headers; CallInfo::SAMPLE_RATE_KEY = 8000 so the engine uses its 8 kHz telephony path), hand the CallLink to the accept queue (the slot is reserved when the INVITE arrives and permit.send fills it) (a closed accept side -> BYE, counted). Call state ends on BYE, CANCEL, ACK timeout (64*T1 = 32 s for a 200 without ACK per RFC 3261, UNVERIFIED here: not re-read), RTP silence timeout, or CallEnds::ended.
3. One RTP session per call (rtp_session task). One tokio::net::UdpSocket per call from the configured even-port range (RTCP on port+1 or rtcp-mux; RTCP can start as receive-only SR/RR keepalive). Receive: parse (rtp-types MIT OR Apache-2.0, or hand-rolled 12-byte header), drop unknown SSRC/payload types, reorder with a small bounded buffer (suggest 2-3 packets, 40-60 ms; fixed first, adaptive later), conceal a gap with AudioFrame silence or an interpolated frame (policy TBD with the engine's PLC), then G.711 -> PCM16 with ulaw_decode/alaw_decode (selected by the negotiated payload type 0 or 8, RFC 3551) into 160-sample 8 kHz frames -> WireEvent::Audio (the engine resamples). Send: WireOut::Audio PCM16 8 kHz -> ulaw_encode/alaw_encode -> RTP: sequence +1, timestamp +160 per 20 ms, random initial sequence/timestamp/SSRC, marker bit on the first packet after a gap; pacing comes from the existing OutputPacer, so the RTP task sends when WireOut::Audio arrives (no second timer). Preallocate packet buffers (hot-path rule); never block the runtime thread.
4. DTMF. Receive RFC 4733 telephone-event packets (payload: event, E bit, R bit, volume, duration; events 0-9 = digits, 10 = *, 11 = #, 12-15 = A-D per RFC 4733 Table 3). Emit one WireEvent::Dtmf per event, de-duplicated by RTP timestamp, on the first packet or on the end packet (policy choice); the end packet SHOULD be sent three times by the sender (RFC 4733), so dedupe. Also accept SIP INFO (application/dtmf-relay, UNVERIFIED format) as fallback. Send DTMF (outbound) as telephone-event packets. Telnyx says RFC 2833 is its default DTMF mode and typically payload type 101 (support article, re-read 2026-10-08); Twilio: RFC 2833 support not stated on the Twilio pages fetched, UNVERIFIED; always read the payload type from the SDP, never hard-code 101.
5. Mapping hang-up. Remote BYE -> reply 200 OK, WireEvent::Hangup, cancel the RTP task, free the port. Engine WireOut::Hangup -> BYE (confirmed dialog) or CANCEL (pending outbound; rsipstack's InviteDialog::hangup() delegates to hangup_with_headers, which picks BYE/CANCEL by state for either role: corrected in section 9) with a transaction timeout, then cancel ended. Remote CANCEL before the 200 -> 487, never create a link.
6. Barge-in / marks (no SIP equivalent). There is no wire-level clear or mark echo in RTP. WireOut::Clear only drops what the adapter itself still holds (the RTP send queue); audio already sent to the network plays out at the far end (carrier jitter buffer, unknown size: UNVERIFIED, measure on a live call). Synthesize WireEvent::MarkAck when the packets ahead of a WireOut::Mark have been sent (the lead is then the network/jitter-buffer delay, which brisvox cannot observe), and report WireEvent::Lead from an estimate (RTCP RR round trip and jitter fields can refine it later). Keep the lead small by sending close to real time (the pacer already does).
7. Outbound call API (new). Not part of Transport::accept. Add SipServer::dial(DialRequest) -> Result<CallLink, DialError> where DialRequest { to: SipUri, from: SipUri/caller id, auth: Credential or trunk, extra_headers, offer: codecs, ring_timeout, cancel: CancellationToken }. It resolves the target (RFC 3263 SRV/NAPTR where the stack supports it; else FQDN/IP), sends INVITE with SDP, handles 401/407 digest retries, 18x (optionally early media), 200 + ACK, and returns the link after ACK with WireEvent::Started (direction = outbound). Failures return the SIP status (486, 603, 408...); cancel before answer sends CANCEL. Honour the same call limit. Idempotency: the caller supplies a dial key so a retried request never creates two calls (engine rule for side-effect tools).
8. Timeouts, cancellation, limits. Every await has a timeout (INVITE ring timeout, ACK wait, BYE transaction, RTP silence e.g. 30-60 s without packets -> Fault then hang up; session-timer expiry if negotiated). Each call = child tasks of the server's TaskTracker, all cancellable via CancellationToken; a panic or error in one call must not affect others (isolate per-call task; signaling state per dialog). Bounded channels as in call_pair().
9. Session timers and keepalive. rsipstack has reinvite/update; a session-timer layer (RFC 4028 Session-Expires/Min-SE, refresher role) would be ours (rsipstack has none: confirmed in the 0.7.3 source, section 9; brisvox does not offer timer, so it does not implement them). Required only if a target demands it (not found in the Twilio/Telnyx pages fetched). OPTIONS pings for NAT binding keepalive (Twilio: no more than one per 10-15 s).
10. Testing. (a) Unit: SDP offer/answer, RTP header/telephone-event codec, jitter buffer, with vectors (RFC 3551 payload types, RFC 4733 events). (b) Sim: scripted SIP peer over UDP loopback (second endpoint in the test) driving INVITE/ACK/BYE/CANCEL, 401 challenge, 503, 488, glare, and an RTP peer sending G.711 + telephone-event with loss/reorder. (c) Live (needs infrastructure): Asterisk (docker) and a Twilio or Telnyx trunk, BRISVOX_LIVE_TESTS=1. SIPp as test peer: UNVERIFIED (not researched), rvoip claims SIPp in its own gate.

5. Interop targets

5.1 Twilio Elastic SIP Trunking (docs fetched 2026-10-08)

• Twilio is a trunk provider; brisvox plays the customer SBC/PBX. Do not confuse with Media Streams (twilio.md): SIP trunking carries RTP, not a WebSocket.
• Origination (PSTN -> brisvox): configure an origination SIP URI (IP or FQDN; the user part is the dialed number; Twilio adds a Diversion header carrying the dialed Twilio number). UDP default; ;transport=tcp or ;transport=tls (TLS default port 5061, other port allowed); the sips scheme is NOT supported; ;edge=<location> selects the egress edge (e.g. edge=dublin; missing/wrong value -> the edge where the PSTN call arrives); up to ten origination URIs with priority (0-65535, lowest first) and weight (1-65535).
• Termination (brisvox -> PSTN): termination URI like {name}.pstn.twilio.com (localized: {name}.pstn.<location>.twilio.com; locations: Ashburn, Umatilla, Dublin, Frankfurt, Singapore, Tokyo, Sao Paulo, Sydney); IP ACL and/or credential list (at least one required); numbers in E.164 with a leading + or Twilio returns 400 Bad Request; caller ID must be a Twilio number or verified caller ID. If an INVITE gets no response, Twilio recommends moving to the next available IP after 4 seconds (applies to us as UAC).
• Behaviour requirements: do not register the trunk; send Max-Forwards: 70; OPTIONS pings optional, at most one per 10-15 s; NAT bindings kept open with OPTIONS over UDP or OPTIONS/CRLF keepalives over TCP/TLS (the OPTIONS/CRLF keepalive sentence was not re-confirmed in the fact-check: UNVERIFIED); symmetric RTP is considered less secure, Twilio recommends leaving it disabled (enable only to traverse a non-SIP-aware NAT) so Twilio sends media only to the address in the SDP (so our advertised SDP address must be correct, see NAT).
• Signaling: ports 5060 (UDP/TCP) and 5061 (TLS); gateway ranges (IP page): Virginia 54.172.60.0/30, Oregon 54.244.51.0/30, Ireland 54.171.127.192/30, Frankfurt 35.156.191.128/30, Tokyo 54.65.63.192/30, Singapore 54.169.127.128/30, Sydney 54.252.254.64/30, Sao Paulo 177.71.206.192/30. Twilio says not all host active gateways at a time (accept signaling from all listed IPs) and recommends using the configured FQDN, not the IPs.
• Media: UDP, to 168.86.128.0/18, destination ports 10,000-60,000; source IP and source port ANY (confirmed on the IP page 2026-10-08). Bandwidth planning: peak = simultaneous calls x 100 kbps (G.711 plus overhead).
• Codecs (codecs page): PCMU and PCMA by default (GA); G.729, Opus, AMR-NB are Limited Availability and "not supported end to end". Origination offer order: PCMU then PCMA (without LA codecs; with LA codecs enabled: Opus, PCMU, PCMA, G.729, AMR-NB). Termination: Twilio matches the first supported codec in our SDP offer, so offer PCMU first.
• Secure trunking: TLS 1.2+ (1.0/1.1 dropped); SRTP origination accepts only AES_CM_128_HMAC_SHA1_80, termination accepts _80 and _32; MKI not supported; with secure trunking enabled unencrypted calls are rejected; trust DigiCert Global Root CA, G2, G3. Source note: these come from Twilio search-result summaries (the Twilio secure-trunking URL tried in the fact-check returned 404; the Secure Media page covers Programmable Voice SIP Domains and confirms _80/_32, MKI unsupported, unencrypted rejected, but not trunking, TLS versions or DigiCert): treat the trunking-specific parts as UNVERIFIED against a trunking page. => SRTP (SDES) would be needed for secure trunks; not in the first scope, rsiprtp and xphone have SDES, rsipstack/rustrtc side to be evaluated.
• Telephone-event on Twilio: not stated on the pages fetched. UNVERIFIED.

5.2 Telnyx SIP (docs fetched 2026-10-08)

• Signaling (sip.telnyx.com page): US sip.telnyx.com 192.76.120.10 and 64.16.250.10; Europe sip.telnyx.eu 185.246.41.140/.141; Australia sip.telnyx.com.au 103.115.244.145/.146; Canada sip.telnyx.ca 192.76.120.31 and 64.16.250.13; Middle East sip.telnyx.me 185.246.42.128/.129; Asia (beta) sip.telnyx.asia 103.115.244.158/.159. Ports UDP/TCP 5060, TLS 5061, WSS 7443. (A search result showed 192.76.120.106 for US and a different /27 media subnet; the live sip.telnyx.com page is authoritative: re-check before writing firewall rules.)
• Media: UDP 16384-32768; subnets 36.255.198.128/25, 50.114.136.128/25, 50.114.144.0/21, 64.16.226.0/24 to 64.16.230.0/24, 64.16.248.0/24, 64.16.249.0/24, 103.115.244.128/25, 103.115.247.0/24, 185.246.41.128/25, 185.246.42.128/28. ptime 20 ms. Codecs: G.711U/A, G.729, G.722, Opus, AMR-WB (plus video H.264/VP8). Whether PCMU/PCMA is the default offer order: UNVERIFIED (the Telnyx audio-and-codecs support article shows an example inbound offer listing G.722, PCMU, PCMA, G.729, telephone-event but does not say what is enabled by default; the claim that G.722 is enabled by default for LiveKit connections is UNVERIFIED; restrict our SDP to PCMU/PCMA and check the connection's codec list).
• Auth: credentials (REGISTER-capable, dynamic IPs), IP, FQDN, IP+X-Telnyx-Token, IP+tech prefix, IP+ P-Charge-Info; error text examples: RG1 (480) not registered on a credential connection, R47 (403) multiple Contact addresses in one REGISTER, B3 (488) SRTP mismatch (all confirmed 2026-10-08).
• TLS 1.2 and 1.3 (1.0/1.1 not accepted, sip.telnyx.com); SRTP preferred cipher on the B2BUA AEAD_AES_256_GCM_8 (first in the default offer), also AES_CM_128_HMAC_SHA1_80 (sip.telnyx.com); the claim that a second Telnyx page disagrees on the preferred cipher was not reproduced in the fact-check (UNVERIFIED which is current).
• DTMF: RFC 2833 (default, "recommended"), SIP INFO, inband, selectable per connection; typical RFC 2833 payload type 101.
• Media IP: the earlier claim that Telnyx "auto-detects your media IP address by monitoring early RTP packets" and adjusts if the source differs from the SDP ("Disable RTP Auto Adjust" / "Accept any RTP packets" expert options) could NOT be confirmed on any Telnyx page in the fact-check (only a community thread mentions the portal toggles "RTP Auto Adjust" and "accept any RTP packets"): UNVERIFIED. STUN stun.telnyx.com:3478 (UDP), TURN turn.telnyx.com:3478 (UDP/TCP; credentials from Telnyx support).

5.3 Asterisk and FreeSWITCH

• Asterisk (PJSIP NAT doc, fetched 2026-10-08): local_net, external_media_address (public IP written into the SDP media address for peers outside local_net), external_signaling_address; endpoint options direct_media=no, rtp_symmetric, force_rport, rewrite_contact for phones behind NAT. Expect Asterisk to latch symmetric RTP: brisvox should send RTP from the same port it advertises and listens on (RFC 4961). rsiprtp's basic_call example runs against Asterisk; rvoip's release gate lists it.
• FreeSWITCH: NAT parameters (ext-rtp-ip, ext-sip-ip, etc.) NOT confirmed in the docs fetched (the SignalWire page fetched was only an index): UNVERIFIED. rvoip lists FreeSWITCH in its gate; xphone claims it. Treat as a second live-test target.

5.4 NAT and deployment considerations

• Brisvox is the server: give it a public IP (or a static NAT) and advertise it in SDP c=, o=, Contact and Via (rsipstack accept_with_public_contact; example --external-ip). Behind Kubernetes/Docker bridge NAT the advertised address must be configured, not auto-detected.
• RTP at scale: one UDP socket per call, so hundreds of calls = hundreds of open ports in a range that must be forwarded/published; prefer host networking or a wide published port range. Per-call sockets also mean ulimit -n sizing. (Design consideration; scale numbers untested.)
• Symmetric RTP (RFC 4961, BCP 131: use one UDP port pair for sending and receiving; required for NATs without ALG and for SBCs): send from the same socket we receive on. Latching onto the first source address (rustrtc enable_latching is such a feature) helps with NATed peers but weakens security; default: accept RTP only from the SDP address, optionally latch within a short window for trusted peers (implemented as SipConfig::rtp_latch + rtp_latch_window: only a packet that passed the payload-type, SSRC and sequence checks moves the destination, only within the window after the call is up or a re-INVITE, and only once).
• SIP over UDP behind NAT: rport (RFC 3581) so responses return to the sender's address and port; TCP/TLS avoid that class of problem (connection reuse) at the price of head-of-line blocking.
• Firewall: allow carrier signaling ranges on 5060/5061 and media ranges (Twilio 168.86.128.0/18 UDP 10000-60000; Telnyx list above) to our RTP range. Prefer FQDN/SRV over hard-coded IPs.
• SIP ALGs on routers/firewalls corrupt SDP: disable (general knowledge: UNVERIFIED against a doc).
• Latency note for docs/LATENCY.md: SIP/RTP paths carry the carrier's RTP packetization (20 ms) and jitter buffer; the transport adds our reorder buffer depth (40-60 ms suggested) plus 20 ms packetization on both legs; measure on a live trunk.

6. Protocol facts used (RFCs, fetched 2026-10-08)

• RFC 3551: PCMU = static payload type 0, PCMA = 8, clock 8000 Hz, 1 channel; default packetization 20 ms (160 octets); RTP timestamp advances 160 per 20 ms (derived from the RFC's rules, not a verbatim sentence).
• RFC 4733 (obsoletes RFC 2833): media type audio/telephone-event, no static payload type (assigned dynamically in SDP, e.g. a=rtpmap:100 telephone-event/8000); default clock 8000 Hz; event codes: 0-9 digits, 10 *, 11 #, 12-15 A-D; payload fields event (8 bit), E (end) bit, R bit, volume (0 to -63 dBm0), duration (16 bit, timestamp units); the final packet of an event SHOULD be sent three times (a SHOULD, not a MUST).
• RFC 3581: rport Via parameter asks the server to answer to the actual source IP and port.
• RFC 4961 / BCP 131: symmetric RTP and RTCP (see above).
• RFC 3261, 3264, 4028, 3262, 3515 etc.: not re-read; behaviour described from the stacks' own docs only.

7. Turkish support

Not applicable to the transport (language-agnostic G.711 audio). Telephony quality note as in twilio.md: 8 kHz narrowband G.711 is typically harder for STT; wideband codecs (G.722 at Telnyx, Opus) could help but both carriers' default/guaranteed codecs are PCMU/PCMA, and rsipstack-based media would need G.722/Opus added by us. Turkish PSTN numbers/trunks (e.g. a local carrier) were not researched (UNVERIFIED).

8. Gotchas (research-time; implementation gotchas get appended later)

• rsiprtp ai_bridge.rs looks like the AI-agent integration but is a simulation with no SIP/RTP; do not treat it as proof the stack runs a real call to an AI.
• GitHub license fields can differ from crates.io (rsiprtp: GitHub shows Apache-2.0 only, crates.io says MIT OR Apache-2.0; rsip: NOASSERTION). Run cargo deny on the chosen set before merging.
• rsipstack versions move daily at the moment: Cargo.lock plus exact pin, and re-read the changelog on every bump.
• Twilio does not accept sips:; use sip: with ;transport=tls.
• Telnyx and Twilio media IPs/ports differ from our own advertised RTP range; do not confuse the two lists in firewall rules.
• Dialog deprecations in rsipstack (ClientInviteDialog, ServerInviteDialog -> InviteDialog): code against InviteDialog.

9. Implementation notes (read from rsipstack 0.7.3 source and measured with local tests)

Module brisvox_transport::sip (cargo feature sip, off by default). Stack: rsipstack 0.7.3 pinned with default-features = false, features = ["platform-tokio", "rustls"] (rustls with the ring provider is enabled for the TLS connection types; still no WebSocket or SRV lookup; MIT, LICENSE file read in the crate; cargo deny check passes). Media half (SDP, RTP, reorder buffer, RFC 4733) is ours.

Resolved from the source (previously UNVERIFIED above):

• rsipstack has its own SIP parser now (no rsip dependency); the only extra dependencies with platform-tokio are tokio, tokio-util, parking_lot, socket2, if-addrs and rand 0.10.
• Server side: the endpoint hands every new server transaction to incoming_transactions(); an INVITE without To tag becomes a dialog with DialogLayer::get_or_create_server_invite, and InviteDialog::handle(&mut tx) must run on its own task for the INVITE transaction (it takes the ACK or the CANCEL). CANCEL does not appear as a separate transaction: the dialog turns it into Terminated(UacCancel) and answers 487. In-dialog requests need DialogLayer::match_dialog + handle.
• BYE, INFO, UPDATE, re-INVITE, OPTIONS, REFER, NOTIFY and MESSAGE inside a dialog reach the application as DialogState events carrying a TransactionHandle; the application must answer within 64*T1 (32 s) or the stack answers 501. Brisvox answers INFO (DTMF) and re-INVITE/UPDATE (SDP) and refuses the rest with 501.
• Client side: DialogLayer::do_invite sends the INVITE, answers a 401/407 once when a Credential is set (otherwise the challenge is returned as the final response), ACKs a 2xx itself and returns the dialog. Dropping the future abandons the call: CANCEL (also from the Calling state, once a provisional arrives), and a 2xx that crosses the CANCEL is ACKed and ended with BYE. The dialog is never removed from the layer automatically: the call task calls remove_dialog.
• Session timers (RFC 4028) are not implemented by rsipstack; Brisvox does not offer timer, so peers do not require it. Deterministic simulation of SIP signaling is not possible: transaction timers run on tokio time.
• TransportLayer::set_whitelist drops datagrams and TCP connections from other source IPs before parsing.
• rsipstack logs whole SIP messages at info level (udp received / udp sent). They contain digest responses and caller data, never a password; run production with rsipstack=warn.
• A CRLF CRLF datagram (RFC 5626 keepalive) is answered with CRLF by the stack.
• On Windows the next receive after a send to a closed RTP port fails with a connection reset (ICMP). The call task ignores ConnectionReset/ConnectionRefused on its RTP socket.

Behaviour of the stack that the review of the SIP transport relied on (0.7.3 source):

• Dropping a server Transaction after its final answer hands it to the endpoint cache of finished transactions; the cache absorbs the ACK and answers a retransmitted INVITE with the same answer until its cleanup timer fires. A refusal therefore does not have to wait for the ACK (it used to, and held a handler slot for the Timer K wait).
• A request that cannot make a transaction key (no From tag, no Via) is dropped by the endpoint with a warning and no answer. A CANCEL without a matching transaction is answered 481 by the endpoint itself.
• DialogStateReceiver is an unbounded channel (UnboundedReceiver). Brisvox bounds it indirectly: each state is produced by a request that holds one of 512 handler slots until the call task answers it.
• The stack reads Require only for 100rel; Brisvox answers any INVITE with another or unknown required tag with 420 and an Unsupported header (RFC 3261 section 8.2.2.3).
• TransportLayer::set_whitelist applies to everything received, so it also drops the answers of outbound calls from hosts outside allowed_sources.
• Contact: a call set up over TCP gets ;transport=TCP in our Contact (inbound and outbound), because the peer sends its BYE and re-INVITE to the Contact (RFC 3261 sections 12.1.1 and 8.1.1.8).
• Secrets: DialRequest::headers can carry an authentication token (X-Telnyx-Token). Its Debug shows header names only, but rsipstack logs whole INVITEs at info: the token appears in logs unless rsipstack=warn.
• A held call (the peer re-INVITEs with a=sendonly, or with c=0.0.0.0) may send no RTP at all; the RTP silence timeout is suspended while the call has no media address or the peer does not listen, and restarts on resume. A re-INVITE that moves, holds or resumes the media starts the receive stream over (new SSRC, new sequence numbers are heard at once).
• A re-INVITE without a body (delayed offer; session refresh, 3PCC, hold done by a controller) is answered 200 with our current SDP (o= version bumped); the peer's answer comes in the ACK. The call task remembers the CSeq of that INVITE and, when the dialog confirms with an ACK of that CSeq (InviteDialog::last_remote_ack), parses the body like an offer and applies it (new media address, hold/resume, receive restart, reopened latch window). An ACK without a body leaves the stream as it was; an unusable one is logged and ignored. An initial INVITE without an offer is still refused with 488.
• Bind address and public_ip (found by the review tests): rsipstack reports the address of a socket bound to 0.0.0.0 as the address of the first non-loopback interface (SipConnection::resolve_bind_address). Brisvox therefore always (re)creates its UDP and TCP sockets on the configured bind_addr with the chosen port and uses the reported address only for the port and the comparison with public_ip. Before this a server bound to 0.0.0.0 with a public_ip listened only on the first interface (not on loopback, not on a second NIC). tests/sip.rs runs a 0.0.0.0 bind advertised as 127.0.0.2 and checks c=, o=, Contact and a BYE sent to the Contact.
• Digest qop: for a challenge with qop="auth" rsipstack answers qop="auth" (quoted), nc=00000001 and a cnonce; RFC 2617 writes the qop value as a bare token. The hash is verified in tests/sip.rs; whether a carrier accepts the quoted form is UNVERIFIED (only a real carrier shows it). The hash function itself is pinned by known answers computed with an independent MD5 implementation (src/sip/auth.rs unit test).
• Marks: the session cuts a mark on a clear (MarkCleared) and ignores its later echo, so the engine never sees MarkPlayed for cut audio whether the adapter drops or echoes a mark on Clear. The SIP adapter drops them. The core pacer releases audio in real time; a long single frame queues all its packets in the adapter at once, which is why the mark tests use one 1 s frame.
• RTP ports: only even ports are used (odd ones stay free for RTCP). rtp_ports must contain at least one even port (validate rejects (20001, 20001)); the rotation cursor wraps inside the even ports first..=last where last is high rounded down to even, so an odd high is never bound.
• Accept queue: an inbound INVITE reserves its accept-queue slot (Sender::try_reserve_owned) before anything is sent, and holds it until the call is handed over, so a burst larger than accept_queue gets 503 instead of 200 followed by a BYE.
• Bot audio that is not 8 kHz is dropped and counted in dropped_audio_frames; a warning is logged once per call. No Fault event is sent to the engine (the earlier text claiming one was wrong).
• Barge-in: the call task always reads the engine channel (a clear must not wait behind a backlog); a frame that does not fit the 500-packet send queue is dropped and counted, which the core pacer (real-time release) makes a rare case. (Observed in the tests, not read from the pacer source:) the core pacer passes a long frame on whole but did not release the next frame until the first one had played out, so a long backlog in the send queue comes from one long frame.

Design decisions: one task per call owning RTP socket, reorder buffer, send queue and dialog events; one re-armed timer for send slot / reorder deadline / RTP silence; packets sent one per 20 ms on an absolute schedule (never a burst); Clear drops queued packets and marks; marks resolve when the packets before them were sent; no Lead is reported. Outbound DTMF is SipHandle::send_dtmf(call_id, ..) because TransportCommand has no DTMF command yet. Not done: RTCP, REFER, delayed-offer INVITE, early media, SRV. (SIPS and SDES-SRTP: docs/TELEPHONY.md, "SIP over TLS and SRTP"; the Twilio secure-trunking facts were fetched again on 2026-10-13 from https://www.twilio.com/docs/sip-trunking and match the notes above: TLS 1.2+, port 5061, _80 only on origination, _80/_32 on termination, no MKI, sips: treated as sip: over TLS.) UNVERIFIED still: INFO DTMF body formats against a real carrier, Twilio/Telnyx telephone-event behaviour, carrier jitter-buffer size (barge-in tail), interop beyond the scripted peers of tests/sip.rs.

UNVERIFIED (summary list)

1. rsipstack: MSRV; embassy target limits; ability to inject a fake transport or time for deterministic tests (resolved the other way in section 9: none, tests use UDP loopback and the real clock). Resolved by the implementation: session timers, RFC 4733, jitter buffer and SDP negotiation are not in rsipstack (Brisvox has its own media half); CANCEL before the answer and a 200 that is never acknowledged are covered by tests/sip.rs.
2. rsiprtp: exact RTP/transport API for driving real sockets; real-world interop beyond Asterisk; any unsafe. (now type resolved: std::time::Instant; CANCEL is covered by its integration tests.)
3. rvoip: sans-IO status, audio frame fields, compile weight, session timers, MSRV claims beyond README badge, endpoint_local_call example.
4. ezk: DTMF, G.711, jitter buffer, session timers, UDP/TCP transport list, MSRV, maturity statement (README fetch partial); ezk-rtc maturity beyond 0.0.1.
5. wavekat-sip: tokio dependency, whether it uses rsipstack, interop tested, NAT support.
6. xphone: runtime used by server mode, SDES cipher suite detail; "used in production alongside xbridge" is a self-claim.
7. sip-core (xmppjingle/sipr) capabilities.
8. Twilio: telephone-event (RFC 2833/4733) in SDP; OPTIONS/CRLF keepalive wording; trunking-specific secure-trunking facts (TLS versions, DigiCert roots, SRTP suites per direction: search-summary sourced); a numeric carrier jitter-buffer size; barge-in tail size.
9. Telnyx: default codec order and G.722 default; the "auto-detects media IP"/RTP Auto Adjust behaviour; whether a second page names a different preferred SRTP cipher; media subnet discrepancy between cached copies; exact signaling IP for US (.10 on the fetched page vs .106 in a search snippet).
10. FreeSWITCH NAT parameters; SIPp usage; SIP INFO DTMF content type; 64*T1 ACK timeout (RFC 3261 not re-read); SIP ALG behaviour.
11. Production readiness of RustPBX (rsipstack's flagship user); THE-PJPROJECT status.
12. Third-party scale numbers (calls per core, memory per call) for any stack: none fetched.

Sources (all fetched 2026-10-08)

• https://crates.io/api/v1/crates/rsipstack , /ezk-sip-ua , /ezk-sip-core , /ezk-rtc , /rvoip , /rvoip-sip , /rsip , /rsiprtp , /xphone , /wavekat-sip , /rtp-engine , /rtp-types , /rustrtc , /msf-rtp , /sip-core , /pjproject-sys
• https://api.github.com/repos/restsend/rsipstack , /kbalt/ezk , /eisenzopf/rvoip , /0x4D44/rsiprtp , /x-phone/xphone-rust , /wavekat/wavekat-sip , /vasilakisfil/rsip , /xmppjingle/sipr , /restsend/rustrtc
• https://github.com/restsend/rsipstack , https://docs.rs/crate/rsipstack/0.7.3/source/README.md , https://docs.rs/rsipstack/latest/rsipstack/dialog/ (+ client_dialog::ClientInviteDialog, server_dialog::ServerInviteDialog, invite_dialog::InviteDialog) , https://github.com/restsend/rsipstack/tree/main/examples/client , https://raw.githubusercontent.com/restsend/rsipstack/main/examples/client/main.rs , https://raw.githubusercontent.com/restsend/rustpbx/main/Cargo.toml , https://github.com/restsend/rustrtc
• https://github.com/0x4D44/rsiprtp , https://docs.rs/crate/rsiprtp/latest , https://docs.rs/rsiprtp/latest/rsiprtp/ , https://docs.rs/rsiprtp/latest/rsiprtp/session/struct.CallManager.html , https://raw.githubusercontent.com/0x4D44/rsiprtp/main/crates/rsiprtp/Cargo.toml , .../examples/ai_bridge.rs , https://raw.githubusercontent.com/0x4D44/rsiprtp/main/tests.md , .../ARCHITECTURE.md
• https://github.com/eisenzopf/rvoip , https://raw.githubusercontent.com/eisenzopf/rvoip/main/README.md , https://docs.rs/rvoip-sip/latest/rvoip_sip/
• https://github.com/kbalt/ezk , https://docs.rs/ezk-sip-ua/latest/ezk_sip_ua/ , https://docs.rs/ezk-sip-core/latest/ezk_sip_core/ , https://docs.rs/crate/ezk-sip-core/latest/features , https://docs.rs/ezk-rtc/latest/ezk_rtc/
• https://github.com/x-phone/xphone-rust , https://github.com/wavekat/wavekat-sip , https://raw.githubusercontent.com/wavekat/wavekat-sip/main/README.md
• https://docs.pjsip.org/en/latest/overview/license_pjsip.html
• Twilio: https://www.twilio.com/docs/sip-trunking , https://www.twilio.com/docs/sip-trunking/ip-addresses , https://www.twilio.com/docs/sip-trunking/codecs , https://www.twilio.com/docs/voice/api/secure-media (+ web-search summaries of the Twilio secure-trunking docs)
• Telnyx: https://sip.telnyx.com/ , https://developers.telnyx.com/public/llms/calling/sip-trunking-full.txt , https://support.telnyx.com/en/articles/1130710-what-is-dtmf-and-how-to-configure-it-on-telnyx , https://support.telnyx.com/en/articles/3192298-audio-and-codecs (plus web-search summaries of the Telnyx docs index)
• Asterisk: https://docs.asterisk.org/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/Configuring-res_pjsip-to-work-through-NAT/
• RFCs: https://www.rfc-editor.org/rfc/rfc3551.html , /rfc4733.html , /rfc4961.html , /rfc3581.html
• Repo files read: crates/brisvox-transport/src/call.rs, transport.rs, crates/brisvox-audio/src/codec.rs (function names ulaw_encode/decode, alaw_encode/decode), docs/ARCHITECTURE.md (Transport).

Fact-checked 2026-10-08: about 130 claims checked, 13 corrected (plus 6 downgraded to UNVERIFIED):

• rsiprtp now is std::time::Instant (was UNVERIFIED); rsiprtp CANCEL is covered by its integration tests (was "not named"); the "differential-tested vs rsip / RFC 4475 / fuzz" claim is supported by tests.md, not by the README; rsiprtp terminate_call only acts on Established calls; rsiprtp ICE: TURN relay, trickle and ICE restart unsupported.
• rvoip WebSocket: plain SIP-over-WebSocket has "bounded evidence", only WSS is developer preview (was "WS developer preview").
• xphone: wording is "used in production alongside xbridge", not "powers xbridge"; Opus/G.729 are optional feature flags; interop list split into trunks vs PBXes.
• rsipstack: hangup() is BYE-only and a no-op on UAS dialogs; BYE/CANCEL selection is in hangup_with_headers; the dialog module index page shows no deprecation (struct pages do); crate first published 2025-01-10; embassy "UDP + TLS client only" is not what the README says (downgraded to UNVERIFIED).
• RFC 4733: the triple send of the end packet is a SHOULD.
• Twilio: media source IP/port ANY is confirmed on the IP page (was UNVERIFIED); the "3-4 IPs" phrasing is not on the page (it says next available IP after 4 s); edge= fallback behaviour added; secure-trunking details (TLS 1.2+, DigiCert, per-direction SRTP suites) rest on search summaries, since the fetched Secure Media page covers Programmable Voice, not trunking (downgraded); OPTIONS/CRLF keepalive over TCP/TLS not re-confirmed (downgraded).
• Telnyx: the "auto-detects media IP / Disable RTP Auto Adjust" quote could not be found on any Telnyx page (downgraded to UNVERIFIED); TLS is 1.2 and 1.3; G.722-default claim unconfirmed (support article only shows G.722 first in an example offer); the "two pages disagree on cipher" claim not reproduced.
• ezk README maturity statement: fetch was partial, so "none" is UNVERIFIED.
• Confirmed unchanged: all crates.io versions, dates, licenses and download counts; GitHub stars/forks/issues/push dates; Twilio and Telnyx IP ranges, ports, codecs; Asterisk NAT options; RFC 3551/3581/4961 facts; PJSIP license; brisvox WireEvent/WireOut/codec function names.

Telephony call control (DTMF, transfer, voicemail/AMD) — Twilio and Telnyx

Scope: DTMF in/out, warm/cold transfer (tool-callable), voicemail / answering-machine detection strategy and leave-message flow. Related: docs/providers/twilio.md (Media Streams wire protocol, request validation), docs/providers/telnyx.md (Telnyx media streaming wire protocol), docs/providers/g711.md (codec). Researched: 2026-10-08. Every fact below was read from the pages listed under Sources on that date. Anything not confirmed on a fetched page is marked UNVERIFIED. Statements labelled "Proposal" or "Brisvox design" are engineering choices, not documentation claims. This is call control (REST/webhooks next to the media WebSocket), not an STT/LLM/TTS provider.

Scope boundary (from twilio.md): brisvox core is the WebSocket SERVER of the media stream and does not serve TwiML or webhooks. Everything on this page that is REST (update call, participants, send_dtmf, transfer) is an OUTBOUND HTTPS call that a brisvox tool/adapter makes (reqwest 0.13.5, already in the workspace Cargo.toml); everything that is a callback (status callbacks, AMD results, conference events, Telnyx webhooks) is served by the user's HTTP app or by an optional brisvox webhook module (not decided here).

0. Capability matrix (what the docs say works)

1. Twilio

1.1 REST basics (auth, encoding)

• Docs: https://www.twilio.com/docs/usage/requests-to-twilio (fetched 2026-10-08).
• Auth: HTTP Basic. "use the Account SID as the HTTP Basic authentication username and the Auth Token as the password" (page wording). Alternative: API key SID as username and API key secret as password; the page says to prefer API keys for applications unless a reference says to use Account SID + Auth Token. Docs' own curl examples use -u $TWILIO_API_KEY:$TWILIO_API_SECRET. Brisvox: support both; never log the token/secret (same rule as twilio.md).
• Base URL: https://api.twilio.com/2010-04-01/ (all examples; the page does not state it as a standalone rule); resource URLs end in .json.
• POST bodies: application/x-www-form-urlencoded or multipart/form-data ("Twilio APIs expect ..."). Repeated parameters (e.g. several StatusCallbackEvent): the Call create page says "Send multiple values as separate parameters" (page wording: "use a separate parameter for each").
• Rate limits / concurrency limits / error body format: NOT covered on the fetched pages (UNVERIFIED). Error bodies in samples have error_code and error_message fields only.
• Idempotency: no idempotency header or key is documented for Calls or Participants (UNVERIFIED). Brisvox must provide at-most-once itself (engine rule "SideEffect tools never run twice"); after a timeout, GET the call before any retry.

1.2 Call resource: create, update, fetch

Docs: https://www.twilio.com/docs/voice/api/call-resource (and .md), https://www.twilio.com/docs/voice/tutorials/how-to-modify-calls-in-progress (fetched 2026-10-08).

• Create: POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls.json. Required To, From. Exactly the documented example:

  curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \
  --data-urlencode "Url=http://demo.twilio.com/docs/voice.xml" \
  --data-urlencode "To=+15558675310" \
  --data-urlencode "From=+15017122661" \
  -u $TWILIO_API_KEY:$TWILIO_API_SECRET
  

  Create parameters relevant here (page table): Url (absolute URL returning TwiML), Twiml ("Max 4000 characters."; page wording: "If both twiml and url are provided then twiml parameter will be ignored", i.e. Url wins on Create), ApplicationSid, Method (GET|POST, default POST), FallbackUrl/FallbackMethod, StatusCallback/StatusCallbackMethod (default POST; "Without events, only completed is sent"), StatusCallbackEvent (initiated, ringing, answered, completed; default completed), Timeout (default 60, max 600; a 5-second buffer may be added), TimeLimit, SendDigits (up to 32 characters; page wording: "If both SendDigits and MachineDetection parameters are provided, then MachineDetection will be ignored"), Record etc., and the AMD set in 1.7. Dial-out result fields: sid (CA...), status, direction, answered_by, parent_call_sid, ...
• Update (redirect / hang up a LIVE call): POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json (Sid = 34 chars, starts with CA). Page description (paraphrase; the exact earlier-quoted sentence "Modifies an active call. You can redirect an in-progress call to new TwiML or terminate it." was NOT found verbatim, the page says "Updating a Call allows you to modify an active call" and that a POST to a Call instance lets you redirect an in-progress call or terminate it). Parameters (page table):

  Param	Meaning
  Url	Absolute URL returning TwiML; called with Method when the call connects
  Method	GET or POST, default POST (ignored if application_sid present)
  Twiml	TwiML used without fetching Url; mutually exclusive with Url (page wording: "Twiml and url parameters are mutually exclusive")
  Status	canceled or completed
  FallbackUrl, FallbackMethod	used on error fetching/executing the TwiML at Url
  StatusCallback, StatusCallbackMethod	status updates; to change StatusCallback of a call "it is required to set the Url in the same statement"
  TimeLimit	max call duration in seconds
  The maximum length of Twiml on UPDATE is not stated (only the Create page says 4000 characters): UNVERIFIED, keep
  update TwiML under 4000 characters or use Url.
  Example of the documented shape (inline TwiML update; the docs show this as SDK code, the curl form below is derived
  from the Create example and the parameter table, not a verbatim sample):

  curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls/$CALL_SID.json" \
  --data-urlencode "Twiml=<Response><Dial>+905551112233</Dial></Response>" \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
  

  Response: the updated Call resource (fields: account_sid, answered_by, api_version, caller_name, date_created, date_updated, direction, duration, end_time, forwarded_from, from, from_formatted, group_sid, parent_call_sid, phone_number_sid, price, price_unit, queue_time, sid, start_time, status, subresource_uris, to, to_formatted, trunk_sid, uri). status values: queued, ringing, in-progress, completed, busy, failed, no-answer, canceled. Error codes for updating a completed/unknown call: not listed on the page (UNVERIFIED). The adapter therefore does not rely on one status code when it ends a warm transfer's agent leg: after a 4xx other than 404 it reads the leg and treats a final status as "already over", and ends a queued or ringing leg with Status=canceled (the update table lists canceled or completed).
• Semantics (tutorial page): the request "instructs Twilio to make an immediate change [to] the TwiML document that Twilio is using in a phone call". Not stated: what happens to the verb currently running (the page says nothing). Hang up: Status=completed ("To end a phone call by your choice, pass a completed status to a CallSid in progress"). The page also says Twilio ends a call on <Hangup> or when it runs out of TwiML documents to process.
• Parent/child (call-resource page, paraphrase of the "modifying active calls" notes): redirecting an active call to another phone number makes Twilio create "an entirely new Call instance for that new phone number"; the original call is the parent call, and each additional dialed number is a child call, each with its own Call SID. A parent call executing a <Dial> "is considered in-progress by Twilio" even after redirection, so "you must use Status=completed to end it."
• Fetch: GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json.

1.3 What a REST update does to a bidirectional Media Stream

This is the central unknown for DTMF and transfer on Twilio.

• Documented: <Connect><Stream> creates the bidirectional stream; "Twilio doesn't execute subsequent TwiML instructions" and "Twilio executes the remaining TwiML instructions only after your server closes the WebSocket connection" (stream TwiML page). The overview page: "You can stop a bidirectional Media Stream by closing the WebSocket connection from your server or by ending the Call." The messages page says "the only way to stop a Stream is to end the call" (the contradiction is recorded in twilio.md). The stream TwiML page says "You can also update the call with TwiML instructions using the Update a Call resource" (page wording); it does not say what happens to the Stream in that case (our reading; no such sentence is quoted from the page). The general <Connect> page: "If there is no further verb, Twilio will end the phone call", and "If you do not provide an action URL, <Connect> will finish and Twilio will move on to the next TwiML verb in the document". <Connect action> text: "When the <Connect> verb ends, Twilio sends an HTTP request to this URL"; it does not list Stream-specific parameters.
• NOT documented (UNVERIFIED, live-test item 1): whether a REST update with new TwiML closes the stream, sends a stop frame, closes the socket from Twilio's side, or in what order; whether a new <Connect><Stream> inside the update TwiML is allowed while the old stream is still ending (media-streams overview page: "For bidirectional Streams, you can have only one Stream per Call"; the <Stream> TwiML page only says a Stream name must be unique per Call).
• Safe sequencing rules derived from the documented facts (Brisvox design):
  1. Never close the WebSocket first when a hand-off TwiML must follow, unless the original TwiML has a <Connect action>/next verb that does the hand-off: with no further verb the call ends.
  2. So: finish playing the farewell/hand-off audio (utterance-end mark played), call REST update, wait for HTTP 200, then keep the socket open and treat the next stop/close as expected (not a user hang-up) for a bounded time (e.g. 5 s), then close.
  3. Pre-planned documented alternative: original TwiML <Connect action="https://app/after-stream"><Stream .../></Connect>; brisvox closes the socket, Twilio requests the action URL (UNVERIFIED that closing a Stream triggers action), the user's app returns <Dial> TwiML chosen from state brisvox has stored (needs shared state keyed by CallSid). Rejected as the default: requires the user's HTTP app and extra state; REST update is self-contained.

1.4 DTMF

Inbound (caller presses keys): see twilio.md ("Protocol"): {"event":"dtmf","streamSid":..,"sequenceNumber":"5","dtmf":{"track":"inbound_track","digit":"1"}}, bidirectional streams only. Overview page (fetched 2026-10-08): "DTMF isn't supported with unidirectional streams." "DTMF is supported with bidirectional Media Streams only in the inbound direction, from Twilio toward your media server." Digit alphabet beyond one key and whether the tone audio is also present in the media payload: UNVERIFIED (the messages page does not say). No duration or timestamp is sent with a dtmf event.

Outbound (bot presses keys on the far end, e.g. IVR navigation):

• Over the stream: NOT supported (same overview page: "Sending DTMF outbound from your media server toward Twilio is not supported"; the server may only send media, mark, clear).
• TwiML <Play digits="..."> (https://www.twilio.com/docs/voice/twiml/play, fetched 2026-10-08):
  • digits allowed characters: 0-9, A, B, C, D, W, w, #, *. Lowercase w = 0.5 s pause, uppercase W = 1 s pause (page prose: www3 = 1.5 s before tone 3; the page's own samples are inconsistent between www3 and wwww3). No maximum length or tone duration is stated.
  • The page describes <Play digits> as playing DTMF tones "during a call" and suggests testing an IVR menu. It does NOT say that the tones go to a particular leg; for dialing a number with an extension the page says use <Number sendDigits>. <Play digits> cannot be used inside <Gather> (a nested <Play> with a file is allowed, digits are not).
  • Example (verbatim): <Response><Play digits="www3"></Play></Response>.
• Other digit-sending parameters: Create Call SendDigits (up to 32 chars) and <Dial><Number sendDigits="wwww1928"> (page 'number': plays tones "once the call is answered"; same alphabet 0-9 A B C D W w # *). These apply to calls Twilio places, not to an already-running stream.
• Consequence for a call that is in a Media Stream: the only documented way to emit DTMF mid-call is to REPLACE the TwiML via Update Call (1.2). The update ends the <Connect><Stream> flow in some way (1.3) so after the digits the TwiML must start a NEW stream:

  <Response>
    <Play digits="ww1234#"/>
    <Connect>
      <Stream url="wss://agent.example.com/twilio/stream" name="brisvox">
        <Parameter name="resume" value="SESSION_ID"/>
      </Stream>
    </Connect>
  </Response>
  

  Consequences (design, UNVERIFIED in practice): a new WebSocket upgrade, a new streamSid, a gap in both audio directions, the new start.customParameters.resume must be mapped back to the live session by an adapter (CallInfo.metadata["custom.resume"]), and the Twilio signature check applies to the new upgrade as usual. This is heavy; do it only for deliberate IVR navigation.
• In-band alternative (Proposal, reliability UNVERIFIED): synthesize the two-tone DTMF waveform as PCM16 8 kHz in the engine, mu-law encode, and send it as normal media frames with the audio pacer. No Twilio doc says in-band tones sent on the stream are passed to the far end as DTMF or detected by an IVR; the far-end behaviour of G.711 tones is carrier- and IVR-dependent. Parameters to expose as config, tested live: tone ms, gap ms, level. For orientation only: Telnyx's own send_dtmf documents duration_millis 100-500, default 250 (section 2.2). Frequency table is the ITU keypad standard; this research confirmed only keys 5 (770+1336 Hz) and 8 (852+1336 Hz) via the dtmf_tones repo README, the rest of the table (rows 697/770/852/941, columns 1209/1336/1477/1633) is UNVERIFIED by a fetched source: cross-check with a decoder in a unit test (Goertzel).
• Event wiring (brisvox): WireEvent::Dtmf already exists (see twilio.md table, "dtmf -> WireEvent::Dtmf"); brisvox delivers it as Data::Dtmf to the turn state machine/flows and exposes it to tools (e.g. a dtmf message in the LLM context: "[caller pressed 5]"). Outbound: a new transport command SendDtmf { digits } per transport: Telnyx -> send_dtmf; Twilio -> either the REST-update route above or in-band synthesis, selected by config; others -> "unsupported" error.

1.5 Transfer on Twilio

Primitives (all fetched 2026-10-08): TwiML <Dial>, <Number>, <Conference>, <Refer>, <Redirect>; REST Calls update; Conference and Participant resources.

1.5.1 Cold transfer (bot says goodbye, caller is connected to a number)

• REST: Update Call (1.2) with Twiml=<Response><Dial callerId="+90..." answerOnBridge="true" timeout="30" action="https://app/dial-result">+90555...</Dial></Response> (attributes from the <Dial> page: action, answerOnBridge (default false), callerId, timeout default 30 (5-600, +5 s buffer), timeLimit default 14400, hangupOnStar, record). The caller's call becomes the parent; <Dial> creates a child call with its own CallSid; both legs bill (billing statement not fetched: UNVERIFIED). A plain-text number is the same as nested <Number>; E.164 recommended.
• callerId rules (<Dial> page): the dialed party sees the inbound caller's number by default; with <Number> callerId may be the To or From of Twilio's request, a purchased Twilio number or a verified number; for inbound SIP calls it cannot be the To/From.
• Outcome reporting: with action, Twilio sends DialCallStatus (completed, answered (conference), busy, no-answer, failed, canceled), DialCallSid, DialCallDuration, DialBridged. Without action, Twilio moves to the next verb; with none the call ends. After the update brisvox is no longer in the media path, so the outcome reaches only the user's HTTP app (or brisvox via a status callback/poll: GET the child call, finding it needs the call list filter by parent: UNVERIFIED, not fetched). If the dial fails (busy/no-answer/failed), the caller returns to whatever the action URL says; to put the bot back, the action handler must return <Connect><Stream> again (new session with resume parameter, see 1.4). This is the documented way to support "transfer failed, bot continues".
• SIP REFER: <Refer><Sip>sip:alice@example.com</Sip></Refer> (https://www.twilio.com/docs/voice/twiml/refer, fetched 2026-10-08). "<Refer> is only supported on SIP call legs"; PSTN and Voice SDK legs are not supported and return an error. So it applies only if the call reached Twilio via SIP (the SIP transport), not for PSTN numbers. Action parameters ReferCallStatus, ReferSipResponseCode, NotifySipResponseCode. Billing: not stated on that page (a Twilio help text seen in search says SIP REFER is a separately charged feature: UNVERIFIED).
• <Redirect> only changes the TwiML document ("All verbs after <Redirect> are unreachable and ignored"); not a transfer by itself.

1.5.2 Announced / screened transfer (no conference): whisper on the agent leg

<Dial><Number url="https://app/whisper"> runs TwiML "on the called party's leg after answer, before the parties are connected" (page 'number', fetched 2026-10-08; paraphrase of the page). Only <Play>, <Say>, <Gather>, <Hangup> are supported there ("Other TwiML verbs aren't supported"); with answerOnBridge on <Dial> the caller keeps hearing ringing while it runs, and that TwiML cannot contain <Dial>. Use: <Say language="tr-TR" ...> to read a short summary and a <Gather numDigits="1"> "press 1 to accept"; <Hangup/> otherwise (the page: offer them a chance to decline using <Gather> and <Hangup>). The url is a URL, so the user's HTTP app serves it (summary passed as a query string or looked up by ParentCallSid: design). Turkish <Say> voices (https://www.twilio.com/docs/voice/twiml/say/text-speech, fetched 2026-10-08): Google Standard-A..E, Wavenet-A..E, Chirp3-HD (Aoede, Charon, Fenrir, Kore, Leda, Orus, Puck, Zephyr), Amazon Polly Neural Burcu-Neural, Polly Standard Filiz. <Say> text limits (same page): Basic 4000 characters, Polly 3000 (excluding SSML tags), Google 5000 (including SSML tags, newlines and spaces).

1.5.3 Warm transfer (bot or first agent briefs the target, then hands off)

Documented conference primitives:

• TwiML <Conference> (https://www.twilio.com/docs/voice/twiml/conference, fetched 2026-10-08): attributes muted (default false), beep (true|false|onEnter|onExit, default true), startConferenceOnEnter (default true; false = muted and hears hold music until a moderator with true joins), endConferenceOnExit (default false), participantLabel (unique in the conference, max 128 chars; duplicate -> error 16025, call not added), waitUrl/waitMethod, maxParticipants (<= 250), record, region (us1,ie1,de1,sg1,br1,au1,jp1), jitterBufferSize (small|medium|large|off, default large), statusCallback, statusCallbackMethod (the page is internally inconsistent about its default: text says POST, table says GET when no waitUrl: pass it explicitly), statusCallbackEvent (space-separated: start end join leave mute hold modify speaker announcement; the first participant's values win). The conference does not start until two participants join (and at least one has startConferenceOnEnter true); names are namespaced to the account; do not put personal data in the name. Callback parameters: ConferenceSid, FriendlyName, AccountSid, SequenceNumber, Timestamp, StatusCallbackEvent (conference-start|end, participant-join|leave|mute|unmute|hold|unhold|modify|speech-start|speech-stop, announcement-end|fail); participant events add CallSid, Muted, Hold, Coaching, EndConferenceOnExit, StartConferenceOnEnter, ParticipantLabel; participant-leave adds ParticipantCallStatus, ReasonParticipantLeft.
• Conference resource (https://www.twilio.com/docs/voice/api/conference-resource): GET .../Conferences.json?FriendlyName=NAME&Status=in-progress finds the ConferenceSid (CF...); status is init|in-progress|completed; conference rooms "are not directly created from the Programmable Voice API" (create with TwiML <Dial><Conference> or the Participants API); POST .../Conferences/{Sid}.json with Status=completed ends it or AnnounceUrl= announces to everyone. The page says "Starting from September 30th, 2026, the default [of the Status list filter] is in-progress" (already past on 2026-10-08): always pass Status explicitly. Docs recommend the statusCallback over polling.
• Participants (https://www.twilio.com/docs/voice/api/conference-participant-resource, fetched 2026-10-08; base https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Participants):
  • Create: POST .../Participants.json; required From, To. Parameters (selection): Label, CallerId, Timeout (5-600, default 60, +5 s), Muted, Beep, EarlyMedia (default true), StartConferenceOnEnter (default true), EndConferenceOnExit (default false), WaitUrl, Record, ConferenceStatusCallback, ConferenceStatusCallbackEvent (default start end), StatusCallback/StatusCallbackEvent (call status), MachineDetection, MachineDetectionTimeout (default 30), MachineDetectionSpeechThreshold, MachineDetectionSpeechEndThreshold, MachineDetectionSilenceTimeout, AmdStatusCallback, AmdStatusCallbackMethod (default POST), CallToken, Region (us1, us2, ie1, de1, sg1, br1, au1, jp1). Response fields: account_sid, call_sid, label, conference_sid, date_created, date_updated, end_conference_on_exit, muted, hold, status, start_conference_on_enter, coaching, call_sid_to_coach, queue_time (create only), uri; participant status: queued|connecting|ringing|connected|complete|failed. The sample create response has "status": "queued". Reconstructed request (the page's own curl example was too long to quote; this follows its fields):

    curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Conferences/$CF_SID/Participants.json" \
    --data-urlencode "From=+15017122661" --data-urlencode "To=+905551112233" --data-urlencode "Label=agent" \
    --data-urlencode "EndConferenceOnExit=false" -u $TWILIO_API_KEY:$TWILIO_API_SECRET
    

  • Update: POST .../Participants/{CallSid-or-Label}.json (label must be percent-encoded). Hold=true|false, HoldUrl, HoldMethod (default GET), AnnounceUrl, AnnounceMethod (default POST), Muted, BeepOnExit, EndConferenceOnExit, WaitUrl, Coaching, CallSidToCoach. Documented samples (verbatim): hold: --data-urlencode "Hold=true" --data-urlencode "HoldUrl=http://www.myapp.com/hold_music"; announce: --data-urlencode "AnnounceUrl=http://www.myapp.com/announce"; both against .../Conferences/CF.../Participants/CallSid.json. Announce URL media types: the Conference resource page lists MP3, WAV or TwiML; the list of TwiML verbs allowed (<Play>, <Say>, <Pause>, <Redirect>) was NOT confirmed on the participant page: UNVERIFIED. Whether an announcement interrupts audio already playing is not stated. Long files delay playback; announcements of 30 minutes or longer can trigger a request timeout (conference and calls stay connected, participants hear "An application error has occurred").
  • Delete (remove the leg from the conference): DELETE .../Participants/{CallSid}.json -> HTTP 204, no body (the removed participant's call ends or continues per its TwiML: UNVERIFIED which, the page does not say; the Twilio blog tutorial instead ends a leg with Calls update status: completed).
  • List/fetch: list filters Muted, Hold, Coaching, PageSize (default 50, max 1000); fetch accepts a Call SID or a label.
• Documented warm-transfer shape (Twilio TaskRouter "Call Control Concepts", https://www.twilio.com/docs/taskrouter/contact-center-blueprint/call-control-concepts, fetched 2026-10-08): (1) put the caller on hold (participant update Hold=true + HoldUrl), (2) create a new TaskRouter task for the transfer target (with the conference SID and original TaskSID) and, once assigned, call agent 2 into the conference with TwiML (the page's route is via TaskRouter, not a bare Participants create), (3) three-way call, (4) remove agent 1's leg via the Participants API, (5) complete the task. Cold-transfer variant on the same page: "it is not important for the addition of the new participant to be completed before the first agent call SID is removed" and "The conference and caller leg will stay up even if no one else is on the conference."
• Voice-AI example from Twilio (blog, published 2025-09-08, https://www.twilio.com/en-us/blog/developers/tutorials/product/warm-transfer-openai-realtime-programmable-sip): the caller sits in a conference (<Conference startConferenceOnEnter="true" participantLabel="customer" endConferenceOnExit="true">, conference named with the inbound CallSid), the AI is a SECOND conference participant (label "virtual agent") dialed over SIP, the human agent is added with Participants create (label "human agent", earlyMedia: false, callToken), a conference join status callback triggers removal of the AI leg by listing participants and updating that leg with status: completed. The article says it has no unit tests and that tests are needed before production; it does NOT state anything about a missing briefing/summary announcement or fragile error handling (an earlier version of this file claimed so; not supported by the page).
• Problem for brisvox (design analysis): with <Connect><Stream> the bot is not a conference participant; it is a WebSocket on the caller's own leg. Moving the caller into a conference by TwiML ends that flow (1.3), so the bot cannot brief the agent or stay in a three-way call. Three workable shapes:
  1. Consult-leg pattern (composed from documented primitives only; end-to-end UNVERIFIED): (a) update the caller's call with <Play loop="0"> hold audio (or <Conference> alone with waitUrl); (b) create a second outbound call to the agent via Calls create with Twiml=<Response><Connect><Stream url="wss://.../twilio/stream"><Parameter name="role" value="consult"/><Parameter name="parent" value="CALLER_CALL_SID"/></Stream></Connect></Response> so a second brisvox session talks to the agent (briefing, "accept?" via speech or DTMF); (c) if accepted, update both calls with <Dial><Conference>SAME_NAME</Conference></Dial> (agent endConferenceOnExit, caller endConferenceOnExit), the consult stream ends; (d) if declined, update the caller back to <Connect><Stream> with resume. Needs answered_by handling on the agent leg (voicemail of the agent's phone must not "accept": use AMD from 1.7).
  2. Whisper screening (1.5.2): no conference, simplest, Twilio TTS reads the summary, agent accepts by DTMF. Good default for "warm".
  3. Bot as a conference participant from the start (Twilio blog shape): needs the bot reachable as a SIP/PSTN endpoint; not researched further.
• Tool contract (Proposal): transfer_call { destination, mode: "cold" | "announced" | "warm", summary?, reason? } as a SideEffect tool: never speculative, idempotency key per call+destination, one transfer per call. Result returned to the LLM: {status: "initiated" | "failed", detail}; after initiated the session ends (cold) or waits for the consult result (warm). The tool must (1) validate E.164 against an allow-list from config (prevents prompt-injection toll fraud), (2) have the bot finish its hand-off sentence and wait for the played-mark (the Twilio adapter notes in twilio.md "Ending the call"), (3) only then call the REST update.

1.6 Status callbacks (Twilio)

• Calls API: StatusCallback + StatusCallbackEvent (initiated|ringing|answered|completed, default completed); form-encoded request carrying the standard TwiML request parameters (https://www.twilio.com/docs/voice/twiml, fetched 2026-10-08): CallSid, AccountSid, From, To, CallStatus (page lists queued, ringing, in-progress, completed, busy, failed, no-answer, canceled; initiated is NOT in that list although it is a valid StatusCallbackEvent name), ApiVersion, Direction (inbound|outbound-api|outbound-dial), ForwardedFrom, CallerName, ParentCallSid, CallToken; status callbacks add CallDuration, RecordingUrl/Sid/Duration.
• <Dial><Number statusCallback ...> (page 'number'): adds ParentCallSid, CallStatus, CallDuration (completed only), Timestamp (RFC 2822, UTC), CallbackSource (call-progress-events), SequenceNumber (starts at 0; events may arrive out of order). Child calls are never queued.
• Conference callbacks: see 1.5.3. Stream callbacks (statusCallback on <Stream>): in twilio.md.
• Authenticity: same X-Twilio-Signature HMAC-SHA1 scheme as twilio.md ("Request validation"); the callback is HTTP(S), so the URL form is the normal one.

1.7 Answering Machine Detection (Twilio)

Docs: https://www.twilio.com/docs/voice/answering-machine-detection and -faq-best-practices (fetched 2026-10-08).

• Where AMD works (FAQ page): Calls API create, Participants API create, <Dial><Number>, <Dial><Sip>. It does NOT work on Elastic SIP trunking calls, <Dial><Client>, <Dial><Conference>, <Dial><Queue>. Changelog 2022-10-07: Dial and Participants AMD need an account with "Enhanced Programmable SIP Features". Inbound-call AMD: not offered (the pages show only outbound use; not stated explicitly).
• MachineDetection: Enable (returns as soon as the party is identified; use to connect humans / hang up on machines) or DetectMessageEnd (returns human immediately; for a machine only when the greeting ends, "usually indicated by a beep"; the mode for leaving voicemail).
• AnsweredBy values: with Enable: machine_start, human, fax, unknown; with DetectMessageEnd: human, machine_end_beep, machine_end_silence, machine_end_other (also a fallback when a machine was detected but MachineDetectionTimeout expired before the greeting ended), fax, unknown (timeout or initial-silence timeout). machine_start is not defined further on the page. FAQ: treat any machine_end_* as "machine, greeting finished" unless you must tell them apart.
• Timing parameters (Create Call / AMD pages): MachineDetectionTimeout default 30 s (AMD page range 3-59; the <Dial><Number> page says 3-60; the Create Call page lists no range: inconsistent, UNVERIFIED which is right; stay within 3-59), only relevant for DetectMessageEnd per the FAQ; MachineDetectionSpeechThreshold 1000-6000 ms default 2400 (higher = fewer false machine, slower machine detection); MachineDetectionSpeechEndThreshold 500-5000 ms default 1200 (higher helps short voicemails, delays human detection; lower risks false human); MachineDetectionSilenceTimeout 2000-10000 ms default 5000 (initial silence before unknown). FAQ tuning hints: greetings of individual humans (residential/mobile) typically under 1800 ms; business 1800-3000 ms; machines over 3000 ms; recommended values for residential/mobile callees SpeechThreshold 1800-2000 and SpeechEndThreshold 1400-1500; for business callees SpeechThreshold 1800-3000 and SpeechEndThreshold 1400-1500. "30 seconds is frequently not enough time" for business voicemail (FAQ); low MachineDetectionTimeout increases unknown.
• Sync vs async: default is synchronous: Twilio blocks the call until the verdict (the callee hearing silence for "several seconds" is our description, UNVERIFIED wording), then runs the TwiML; with Url it sends a webhook containing the decision (exact form-field name in that webhook: described as AnsweredBy in the AMD docs; the TwiML request-parameter page does not list it: UNVERIFIED). Async (AsyncAmd=true, Calls API): callee connected immediately, TwiML runs, result posted to AsyncAmdStatusCallback (+ AsyncAmdStatusCallbackMethod; AMD page says only POST, the Create page says GET|POST: UNVERIFIED which is right). Whether Participants API, <Dial><Number>, <Dial><Sip> are async only: UNVERIFIED (not stated on the AMD page; the 2022 changelog says AMD "will run in the background while the call connects" for those). Async callback fields: CallSid, AccountSid, AnsweredBy, MachineDetectionDuration (ms). The page shows no example payload (an earlier version of this file said it did); illustrative, constructed payload only: CallSid=CA...&AccountSid=AC...&AnsweredBy=machine_end_beep&MachineDetectionDuration=4200.
• Typical latency (FAQ): results "within ~4 seconds after the call was answered" with default settings (an average); webhook round trip is the most common cause of slowness. Accuracy: FAQ "close to 100% accurate in US destinations with default settings" for DetectMessageEnd; international accuracy "may be slightly reduced".
• Forked-stream interaction (AMD page, key for brisvox): async AMD uses one of the four forked audio streams per call; sync AMD uses none. The AMD page says Media Streams, SIPREC and Real-Time Transcription should be started "only after" Async AMD finishes, as indicated by the AsyncAmdStatusCallback. The stream overview page lists AMD among features sharing the four-track limit (that limit is stated for unidirectional streams); bidirectional streams are limited to one per call. Whether async AMD can run concurrently with a bidirectional <Connect><Stream> is therefore at best discouraged by the docs (UNVERIFIED if it errors).
• Recommended Twilio voicemail pattern for brisvox (Proposal built on the above): outbound Calls create with MachineDetection=DetectMessageEnd (sync), MachineDetectionTimeout=45 (below 59), MachineDetectionSilenceTimeout default, Url=https://app/voice whose handler reads AnsweredBy and returns <Connect><Stream url=...><Parameter name="answered_by" value="{AnsweredBy}"/></Stream></Connect>; brisvox gets CallInfo.metadata["custom.answered_by"] at start, so no AMD plumbing is needed inside brisvox core. Humans: conversation starts about 0-4 s after pickup (sync-silence cost). Machines: wait for machine_end_*, then speak the message. Async variant to cut the silence: AsyncAmd=true, TwiML <Pause length="N"/> then <Connect><Stream> is NOT recommended (the docs say not to start a stream before the callback; a REST update on callback could start it, behaviour UNVERIFIED).
• Cost: $0.0075 per call (https://www.twilio.com/en-us/voice/pricing/us line "Answering machine detection ... $0.0075 per call", fetched 2026-10-08; the 2019 GA blog says charged when enabled and the called party answers, busy/failed not charged; 2022 changelog: "$0.0075 per completed call"). Media Streams are listed at $0.0044 per minute and conference participants "Starting at $0.0018 / participant per min" on the same page.
• Language/countries: the AMD docs do not mention languages or Turkish (UNVERIFIED for Turkish voicemail greetings). A supported-country list was not found (the 2019 GA blog lists no countries; its example number is +1); the 2017 beta post said US and Canada only (old, from a search summary, UNVERIFIED); pricing pages for other countries list the AMD fee, which suggests availability but is not proof. Test with Turkish carriers (Turkcell, Vodafone, Turk Telekom voicemail) live before trusting it.

2. Telnyx Call Control

2.1 REST basics

• Base URL: https://api.telnyx.com/v2 (OpenAPI server; docs examples https://api.telnyx.com/v2/calls/{call_control_id}/actions/answer). Docs: https://developers.telnyx.com/docs/voice/programmable-voice/sending-commands (fetched 2026-10-08). That page itself only covers base URL, auth header, and HTTP status meanings (200, 403, 404, 422); the facts below on client_state, command_id, response bodies and error codes come from the individual command pages (send-dtmf, transfer-call, bridge-calls, etc.) and the webhooks page.
• Auth: Authorization: Bearer YOUR_API_KEY (API key v2); JSON bodies (Content-Type: application/json in the docs' curl).
• call_control_id identifies the call leg to control (command pages: "Identifier and token for controlling the call"; the claim that it also routes to the node where the call lives, for lower latency, was NOT found on the fetched pages: UNVERIFIED). Every command takes optional client_state (Base64, echoed in all later webhooks) and command_id (send-dtmf page: Telnyx ignores any command with the same command_id for the same call_control_id; the webhooks page adds "within 60 seconds"; this is the idempotency key to use for transfer and DTMF).
• Success: 200 {"data":{"result":"ok"}}. Errors: 422 with an error list (transfer page examples show code, title, detail; the source/meta members are UNVERIFIED); samples: 90015 invalid Call Control ID, 90018 call already ended, 90034 call not answered yet, 10004 missing parameter, 90045 "command can't be issued when media streaming is used"; generic failure 10007. Dial lists 400, 422, 429 (rate limited), 500, 503. Rate limit values: not found (UNVERIFIED).
• Commands exist (index page): send_dtmf, send_sip_info, transfer, bridge, refer, hangup, streaming_start, streaming_stop, playback_*, speak, gather_*, record_*, answer, reject, fork_*, transcription_*, client_state_update; conference commands hold, unhold, join, leave, mute, unmute, play, speak, update. No call-level hold command is listed (hold exists on conferences).

2.2 DTMF

Docs: https://developers.telnyx.com/api-reference/call-commands/send-dtmf (fetched 2026-10-08).

• Send: POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/send_dtmf. Description: "Sends DTMF tones from this leg. DTMF tones will be heard by the other end of the call." Body: digits (required; "Valid digits are 0-9, A-D, *, and #. Pauses can be added using w (0.5s) and W (1s)", example 1www2WABCDw9), duration_millis (100-500, default 250, "for how many milliseconds each digit will be played in the audio stream"), client_state, command_id. Response {"data":{"result":"ok"}}. No webhooks. No maximum number of digits stated (UNVERIFIED).

  curl -X POST https://api.telnyx.com/v2/calls/$CALL_CONTROL_ID/actions/send_dtmf \
    -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
    -d '{"digits":"1www2","duration_millis":250,"command_id":"UUID"}'
  

  Whether this command is rejected (90045) or works while a media stream is active on the same leg: not documented (UNVERIFIED, live-test item 4). Separate commands exist for SIP INFO (send_sip_info, not fetched) and conference participants (/v2/conferences/{id}/actions/send_dtmf, not fetched). send_digits_on_answer (max 64 chars, 0-9 A-D w W * #) on Dial/Transfer; a to may end with ,digits (+18004247767,200); an explicit send_digits_on_answer overrides digits appended to to.
• Receive over the stream: {"event":"dtmf","stream_id":..,"occurred_at":..,"sequence_number":"5","dtmf":{"digit":"1"}} (digits 0-9 * # A B C D; may arrive out of order; order by occurred_at; occurred_at is optional in the schema; full schema in telnyx.md).
• Receive as webhook: call.dtmf.received exists with data.event_type = "call.dtmf.received", data.payload.digit (string), plus call_control_id, call_leg_id, call_session_id, client_state, connection_id, from, to (source: official SDK model telnyx-python types/call_dtmf_received.py, read 2026-10-08). The Voice API webhooks page describes it as "A DTMF digit was received", fired when the caller presses keys during Gather using audio or Gather using speak (paraphrase; the exact earlier-quoted sentence was not verified verbatim), and the Gather command docs list it as an expected webhook; it is NOT documented as a general always-on DTMF event. For a streamed bot, use the dtmf stream frame.
• Mute: mute_dtmf (none|both|self|opposite) on Transfer/Bridge: DTMF is not passed through but DTMF webhooks still fire (Bridge page wording).

2.3 Transfer on Telnyx

• Transfer: POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/transfer (https://developers.telnyx.com/api-reference/call-commands/transfer-call, fetched 2026-10-08). Only to required (DID or SIP URI; ;secure=true|srtp|dtls; ,digits suffix allowed). Selected body fields: from (default the original call's to; E.164), from_display_name (<=128), audio_url/media_name (WAV/MP3 played to the destination on answer, before bridging; mutually exclusive), send_digits_on_answer, early_media (default true), timeout_secs (default 30, 5-600), time_limit_secs (default 14400, 30-14400), park_after_unbridge (self), answering_machine_detection (default disabled; enum below) + answering_machine_detection_config, custom_headers, sip_headers (only User-to-User), sip_transport_protocol, sip_region, preferred_codecs, media_encryption, target_leg_client_state, client_state, command_id, webhook_url(+method), mute_dtmf, record*. Behaviour: bridges the caller (Leg A) to a NEW leg (Leg B) to to. Webhooks: call.initiated, call.bridged (to Leg B), call.answered or call.hangup, and AMD events when requested. On a failed transfer the docs say a call.hangup for Leg B is sent; the original call remains active and can receive further commands (incl. a transfer to an alternate destination). Timeouts/limits produce call.hangup with hangup_cause timeout or time_limit. After the bridge ends, the leg hangs up unless park_after_unbridge: "self". Response {"data":{"result":"ok"}}.

  curl -X POST https://api.telnyx.com/v2/calls/$CALL_CONTROL_ID/actions/transfer \
    -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
    -d '{"to":"+905551112233","from":"+908501234567","timeout_secs":30,"command_id":"UUID"}'
  

• Media stream interplay: the transfer page lists 90045 (media streaming in use) among its 422 examples and says nothing else about streaming. The same 90045 example ("This command can't be issued when media streaming is used.") appears on the streaming_start page. Which commands are blocked by an active stream is NOT stated (UNVERIFIED, live-test item 4). If transfer/bridge is rejected with 90045, issue POST .../actions/streaming_stop first (stream_id optional; omitted = all streams of the call; webhook streaming.stopped), wait for it, then transfer; on failure, streaming_start again. Whether the WebSocket gets a stop frame after streaming_stop: the streaming_stop page does not describe it; the WebSocket reference says Telnyx sends stop "when it stops media streaming for the call" (the media-streaming guide: when the call ends, after the streaming.stopped webhook): treat the exact ordering as UNVERIFIED. Streams: "Currently only one streaming/fork operation is supported per call" (media-streaming page).
• Bridge two legs: POST .../calls/{call_control_id}/actions/bridge with body call_control_id (the other leg; mutually exclusive with queue/video_room_id), park_after_unbridge, hold_after_unbridge, play_ringtone, ringtone, mute_dtmf, prevent_double_bridge, record*, client_state, command_id. Webhooks call.bridged for both legs. Errors incl. 90034 not answered.
• Dial a second leg linked to the first: POST https://api.telnyx.com/v2/calls with required connection_id, to, from; link_to (call control id to share a session with), bridge_intent (requires link_to; overwrites from with the linked call's from), bridge_on_answer (requires link_to), prevent_double_bridge, park_after_unbridge (requires link_to); response data: call_control_id, call_leg_id, call_session_id, is_alive (always false for dial), client_state, record_type:"call", .... Dial also takes the streaming fields (stream_url, stream_track, stream_bidirectional_mode, stream_auth_token, ...) so a CONSULT leg can be streamed to a second brisvox session (same consult pattern as Twilio 1.5.3 shape 1). Fully documented parameters are in the Dial page; shape not live-tested.
• Conference: POST /v2/conferences (call_control_id, name required; start_conference_on_create default true; hold_audio_url/hold_media_name; max_participants 2-800 default 250 (the page's own error examples conflict on this range, UNVERIFIED); duration_minutes; conferences expire after all leave or 4 hours; status init|in_progress|completed; end_reason all_left|ended_via_api|host_left|time_exceeded), POST /v2/conferences/{id}/actions/join (call_control_id required; hold, hold_audio_url, mute, start_conference_on_enter (default false), end_conference_on_exit, soft_end_conference_on_exit, supervisor_role barge|monitor|none|whisper, whisper_call_control_ids, beep_enabled), POST /v2/conferences/{id}/actions/hold (call_control_ids empty = all; audio_url/media_name). Webhooks (create-conference page) conference.created, conference.participant.joined|left, conference.ended, conference.recording.saved, conference.floor.changed. A warm transfer on Telnyx is therefore: conference the caller, hold the caller, dial and join the agent, brief, unhold, hang up the bot leg. As with Twilio, the bot-as-stream sits on the caller's leg, whether it survives conference join is UNVERIFIED.
• SIP REFER: POST .../actions/refer with sip_address (required SIP URI), client_state, command_id, custom_headers, sip_auth_username/password, sip_headers (User-to-User only). Webhooks call.refer.started, call.refer.completed, call.refer.failed (the earlier-noted payload field sip_notify_response was NOT found on the refer page: UNVERIFIED). Whether the call must be answered: not stated (90034 is a listed generic error). The SIP trunking "External transfers" page describes blind (SIP REFER, "Immediate transfer without announcement") and attended transfer (hold, dial, announce, then REFER) for SIP endpoints, with a required Diversion header: that page concerns SIP-trunk endpoints and is not directly the Call Control stream bot case.
• Telnyx's own AI Assistant product has a warm-transfer-acceptance feature (consult leg, built-in complete_transfer tool, 2-minute decision timeout, private|shared context): it is a different product; recorded only as design reference (https://developers.telnyx.com/docs/inference/ai-assistants/warm-transfer-acceptance).
• Price line seen: "Call transfer | $0.10 per invocation" (https://telnyx.com/pricing/voice-api, fetched 2026-10-08); which commands count as a "transfer invocation" is UNVERIFIED.

2.4 AMD on Telnyx

Docs: https://developers.telnyx.com/docs/voice/programmable-voice/answering-machine-detection, Dial and Transfer pages (fetched 2026-10-08).

• Enable with answering_machine_detection on Dial (outbound) or Transfer. (An earlier version of this file quoted the page as saying "outbound call creation or inbound call transfer"; that wording was NOT found on the AMD guide, Dial or Transfer pages: UNVERIFIED.) Modes: disabled (default), detect, detect_beep, detect_words, greeting_end, premium ("recommended" on the guide), premium_ios_call_screening_detection.

  Mode	Webhooks	result values
  detect	call.machine.detection.ended	human, machine, not_sure ("Recommended to treat as if human answered")
  detect_beep	detection.ended; call.machine.greeting.ended only if a beep is detected	greeting: beep_detected
  detect_words	detection.ended; greeting.ended on beep or after a 30 s beep-detection window	greeting: beep_detected or not_sure (timeout)
  greeting_end	both; Transfer page: greeting.ended when the greeting ends "with a beep or silence"	greeting: ended
  premium	call.machine.premium.detection.ended, call.machine.premium.greeting.ended	detection: human_residence, human_business, machine, silence, fax_detected, not_sure; greeting: beep_detected, no_beep_detected
  premium_ios_call_screening_detection	adds call.machine.premium.call_screening.detected	screening; greeting prompt_ended
  Payload (SDK models call_machine_detection_ended.py and call_machine_greeting_ended.py, read 2026-10-08): data.event_type, data.id, data.occurred_at, data.record_type:"event", data.payload.{call_control_id, call_leg_id, call_session_id, client_state, connection_id, from, to, result} (all optional in the SDK);
  result Literal for detection.ended: `human	machine	not_sure; for greeting.ended: beep_detected
  Order: call.initiated -> call.answered -> detection result -> greeting result; callee hang-up gives call.hangup at any point. Premium ordering: if a beep is heard before detection.ended, the greeting webhook is sent first (UNVERIFIED on the current guide fetch, which shows the general order and the iOS order only).

• Config answering_machine_detection_config (Dial page defaults): total_analysis_time_millis 3500, after_greeting_silence_millis 800, between_words_silence_millis 50, greeting_duration_millis 3500, initial_silence_millis 3500, maximum_number_of_words 5, maximum_word_length_millis 3500, silence_threshold 256, greeting_total_analysis_time_millis 5000, greeting_silence_duration_millis 1500, beep tuning (beep_detection_profile both|freq_only, beep_min_frequency_hz 200-4000, beep_max_frequency_hz, beep_min_tone_duration_millis 50-5000, beep_spectral_*), prompt_end_timeout_millis (Dial/Transfer pages: default 5000, 1000-120000; the guide says 30000 default; iOS screening only). For premium only total_analysis_time_millis and greeting_duration_millis apply. The AMD guide quotes premium default analysis timeout 30 s (result not_sure on expiry) while the Dial and Transfer pages list 3500 for the config default: inconsistent (UNVERIFIED which applies to premium). The field descriptions on the Dial page make the heuristics explicit (useful design reference for an in-engine detector): initial silence over initial_silence_millis (3500 ms) = machine; a greeting longer than greeting_duration_millis (3500 ms) = machine; more than maximum_number_of_words (5) words = machine; a single word longer than maximum_word_length_millis (3500 ms) = machine; silence over after_greeting_silence_millis (800 ms) after a greeting = human. (These are descriptions of config fields, not a full algorithm spec.)
• Cost: standard AMD $0.002 per call, premium $0.0065 per call (https://telnyx.com/pricing/voice-api, fetched 2026-10-08); Media Streaming over WebSockets $0.0035 per minute; Voice API outbound "$0.002 per minute + the SIP Trunking fee".
• Language/Turkish: not documented in the AMD guide (UNVERIFIED). Telnyx streaming/AMD webhooks need a Call Control App connection and a public webhook (UNVERIFIED on fetched pages; design assumption).

2.5 Telnyx webhook mechanics (needed for transfer and answering-machine detection if brisvox consumes them)

Docs: https://developers.telnyx.com/docs/voice/programmable-voice/voice-api-webhooks (fetched 2026-10-08).

• Envelope: data.{record_type:"event", event_type, id, occurred_at, payload} and meta.{attempt, delivered_to}.
• Signature headers: Telnyx-Signature-Ed25519 (ED25519 signature) and Telnyx-Timestamp (Unix timestamp); the earlier claim "compatible with the Standard Webhooks specification" is NOT on the fetched webhooks page: UNVERIFIED. Verification steps are on a separate Webhook Fundamentals page (not fetched: UNVERIFIED).
• Delivery: 2xx = ack; 3xx followed up to 3 redirects; 408, 429, 5xx retried; other 4xx not retried; "webhooks may be delivered more than once" -> dedupe on data.id; webhook_timeout_secs 0-30; failover URL webhook_event_failover_url; ack "within a few seconds" and process asynchronously (the "few seconds" wording UNVERIFIED on the latest fetch; retry count/interval not specified on the page). Per-call webhook override via webhook_url (+ webhook_url_method) on commands; webhook_urls/webhook_retries_policies (max 5 retries, total <= 60000 ms) are on the Dial page.
• Correlate with call_leg_id; call_session_id groups related legs (e.g. both sides of a transfer). Ordering guarantees: none documented.

3. Brisvox design for DTMF, transfer and voicemail (Proposal)

3.1 DTMF

• Inbound: already produced by the Twilio adapter (dtmf -> WireEvent::Dtmf) and by the Telnyx adapter (dtmf.digit, order by occurred_at). The design adds: delivery to the turn manager/flows and to tools as an event with timestamp; a debounce/collector (collect_digits { max, terminator '#', timeout } tool or flow node) with an explicit timeout (engine rule); DTMF while the bot speaks counts as barge-in only if configured; DTMF is NOT run through STT.
• Outbound: transport capability flag can_send_dtmf: Telnyx true (REST send_dtmf with command_id); Twilio false over the stream, with two opt-in fallbacks (REST update + reconnect, or in-band synthesis); loopback/WebSocket transports: custom message. send_dtmf tool = SideEffect, idempotency key per (call, digits, sequence), digits validated against [0-9A-D*#wW] and a length limit (Twilio SendDigits 32, Telnyx send_digits_on_answer 64; digits max unspecified).
• Crates: no crate needed. Hand-write the two-tone generator (a few lines, no_std-style, reusable buffer) and a Goertzel check in tests. crates.io check (API, 2026-10-08, re-checked in fact-check): dtmf 0.1.5 (MIT, decoder, last release 2022-11-04, 9820 total downloads: stale), dtmf_tones 1.0.2 and dtmf_table 1.1.4 (MIT, frequency tables only, no audio generation per the repo README; dtmf_tones repo shows 21 commits, 0 stars, no releases; new, tiny, not adopted). twiml-rust 0.1.0 exists (TwiML generator, 180 downloads) but is not needed: TwiML strings here are tiny and must be XML-escaped by a small helper (escape &, <, >, "). reqwest 0.13.5 (MIT OR Apache-2.0, released 2026-09-08) is already a workspace dependency for REST calls.

3.2 Transfer

• Port: CallControl trait (provider-agnostic): transfer(target, mode, ctx) -> TransferOutcome, implemented for Twilio (TwilioCallControl, REST) and Telnyx (TelnyxCallControl, REST), each with timeouts on every HTTP call, a bounded retry policy that never retries a possibly-applied command (use GET status first on Twilio; command_id on Telnyx), and credentials in Secret.
• State machine on the session: Active -> TransferPending(epoch) -> HandedOff | Failed(reason) -> Active|Ended. While pending, the bot stops generating new LLM turns; the farewell audio must be fully played (mark) before the REST call.
• Twilio cold: REST update with <Dial> (1.5.1). Twilio announced: <Dial><Number url=whisper> (1.5.2). Twilio warm: consult-leg pattern (1.5.3, shape 1) or conference; all UNVERIFIED end to end, hence the pending live check.
• Telnyx cold: transfer; warm: dial linked leg (+ streamed consult) and bridge, or conference; remember streaming_stop before commands that fail with 90045.
• Safety (engine invariant: SideEffect never speculative, never twice): transfer_call runs only after the model's tool call finishes (not speculatively), idempotency key = hash(call id, target); destination allow-list or country allow-list in config; log the target redacted.

3.3 Voicemail strategy

Detection layers, in order of authority:

1. Provider AMD when brisvox originates the call (Twilio DetectMessageEnd sync via the user's Url webhook -> answered_by custom parameter; Telnyx greeting_end or premium via the Dial request + webhooks). The result must reach the session (Twilio: custom parameter at start; Telnyx: webhook or client_state).
2. In-engine confirmation (always on, cheap): watch the first seconds of the callee audio with VAD/STT: a single long continuous utterance over the Telnyx-documented 3500 ms, many words, or voicemail phrases in the STT text (Turkish phrases such as "mesaj bırakın", "bip sesinden sonra", "sesli mesaj" are a design suggestion, not from a fetched source) overrides human. A beep cue is only reliably available from the provider (machine_end_beep, beep_detected); an in-engine beep detector would be a new DSP component (not researched).
3. Fallback when AMD says unknown/not_sure: treat as human (Telnyx guide: not_sure "Recommended to treat as if human answered" for standard AMD; for premium the docs give no recommendation); Twilio gives no recommendation (UNVERIFIED), fax -> hang up.

Leave-message flow (state machine):

• Dialing -> Answered -> Classifying(≤ amd_timeout) -> human: normal conversation; machine: WaitGreetingEnd(≤ greeting_timeout) -> Leaving -> Done.
• WaitGreetingEnd ends on Twilio machine_end_beep|machine_end_silence|machine_end_other or Telnyx call.machine.greeting.ended (beep_detected or ended); on a Twilio Enable verdict machine_start do NOT speak yet. On Telnyx detect_words, not_sure after the 30 s window means speak anyway or hang up (policy flag).
• Leaving: play ONE fixed message (pre-rendered or synthesized once, Turkish text from config), barge-in disabled, no LLM turn, no STT-driven interruption; wait for the utterance-end mark (MarkPlayed) with a timeout, then hang up. Message length bounded (config, e.g. 20-30 s; voicemail systems cut off: carrier/system limit UNVERIFIED). The message must not reference data the callee did not consent to (compliance note, not a fetched fact).
• Provider-side alternative for the message itself: Twilio <Say language="tr-TR"> (voices in 1.5.2) or <Play>; Telnyx speak/playback_start (not fetched: UNVERIFIED Turkish voices). Prefer brisvox's own TTS for voice consistency and Turkish quality.
• Metrics/logging: AMD verdict, MachineDetectionDuration (Twilio, ms), time from answer to verdict, time from greeting end to first message audio; counted per call outcome (human|machine_message_left|machine_hangup|unknown|fax).

4. Open items to settle with live tests (need accounts, numbers, public wss URL)

1. Twilio: effect of REST Update (new TwiML) on an active <Connect><Stream>: does Twilio send stop, close the socket, in what order; does a new <Connect><Stream> in the update TwiML start immediately; what does the caller hear in the gap; <Connect action> firing on server close.
2. Twilio: <Play digits> tone duration/level and whether the far-end IVR reliably accepts it; does in-band G.711 DTMF sent on the stream reach an IVR (tone length/gap needed).
3. Twilio: Update Call Twiml length limit; error codes/status for updating an ended call; whether Url update triggers a signed request with the usual X-Twilio-Signature.
4. Telnyx: whether send_dtmf, transfer, bridge are blocked (90045) while a media stream is active; which exact commands; effect of transfer on the stream (stop frame?); whether streaming_stop + transfer + streaming_start is quick enough.
5. Twilio consult-leg and conference warm transfer end to end (hold/unhold, Hold participant update on a leg created by <Dial><Conference>, drop of the bot leg, ConferenceSid discovery by FriendlyName).
6. AMD: sync DetectMessageEnd latency distribution on Turkish carriers and Turkish voicemail greetings (Twilio and Telnyx), false-human/false-machine rate, machine_end_other frequency, behaviour with mobile "arama yönlendirme" announcements; whether async AMD can coexist with a bidirectional stream; whether Turkey is a supported AMD destination at all.
7. Twilio AnsweredBy form-field name in the Url webhook and the AsyncAmdStatusCallbackMethod GET support (docs disagree).
8. Telnyx: premium AMD payload schemas and default total_analysis_time_millis; call.dtmf.received outside Gather.
9. Billing: Twilio parent+child leg billing for <Dial> transfers; Telnyx "Call transfer $0.10 per invocation" scope; conference participant minutes.
10. Rate limits for the REST endpoints on both providers.

Sources (all fetched 2026-10-08)

Twilio

• https://www.twilio.com/docs/usage/requests-to-twilio (and .md)
• https://www.twilio.com/docs/voice/api/call-resource (and .md, full pages incl. Update/Delete sections)
• https://www.twilio.com/docs/voice/tutorials/how-to-modify-calls-in-progress (and .md)
• https://www.twilio.com/docs/voice/twiml (request parameters), /twiml/play, /twiml/dial, /twiml/number, /twiml/conference, /twiml/refer, /twiml/redirect, /twiml/connect, /twiml/stream, /twiml/say (+ /say/text-speech for Turkish voices and limits)
• https://www.twilio.com/docs/voice/media-streams (DTMF statements, four-track limit, stopping a bidirectional stream), https://www.twilio.com/docs/voice/media-streams/websocket-messages
• https://www.twilio.com/docs/voice/api/conference-resource, /conference-participant-resource
• https://www.twilio.com/docs/taskrouter/contact-center-blueprint/call-control-concepts (cold/warm transfer sequences)
• https://www.twilio.com/en-us/blog/developers/tutorials/product/warm-transfer-openai-realtime-programmable-sip (2025-09-08)
• https://www.twilio.com/docs/voice/answering-machine-detection, /answering-machine-detection-faq-best-practices
• https://www.twilio.com/en-us/blog/answering-machine-detection-generally-available (2019-07-17), https://www.twilio.com/en-us/changelog/answering-machine-detection-is-now-available-for-dial-and-post-to-participants-calls (2022-10-07)
• https://www.twilio.com/en-us/voice/pricing/us (AMD, Media Streams, conference participant lines)
• Web search summaries (not primary text): AMD supported countries (2017 beta US/Canada), SIP REFER billing, update-during-stream behaviour (confirmed undocumented). Telnyx
• https://developers.telnyx.com/api-reference/call-commands/send-dtmf (.md), /transfer-call, /bridge-calls, /sip-refer-a-call, /streaming-start, /streaming-stop, /hangup-call, /dial (full page read up to ~100k chars)
• https://developers.telnyx.com/api-reference/conference-commands/create-conference, /join-a-conference, /hold-conference-participants
• https://developers.telnyx.com/docs/voice/programmable-voice/sending-commands, /voice-api-commands-and-resources, /voice-api-webhooks, /answering-machine-detection, /media-streaming
• https://developers.telnyx.com/api-reference/websockets/stream-call-media-over-websocket (stream frames, dtmf)
• https://developers.telnyx.com/docs/voice/sip-trunking/features/external-transfers, https://developers.telnyx.com/docs/inference/ai-assistants/warm-transfer-acceptance
• https://github.com/team-telnyx/telnyx-python (raw src/telnyx/types/call_dtmf_received.py, call_machine_detection_ended.py, call_machine_greeting_ended.py; official SDK models used for webhook field names because the callback doc pages render no schema)
• https://telnyx.com/pricing/voice-api
• crates.io API: reqwest 0.13.5, dtmf 0.1.5, dtmf_tones 1.0.2, dtmf_table 1.1.4, twiml-rust 0.1.0, search dtmf; https://github.com/jmg049/dtmf_tones
• Not fetched: Telnyx Webhook Fundamentals (signature verification steps), send_sip_info, speak, playback_start, Telnyx premium AMD callback pages (render no schema), Twilio Calls list filters (child-call lookup), Twilio SIP REFER billing, per-account rate limits for both providers.

Fact-check log

Fact-checked 2026-10-08: 135 claims checked, 20 corrected. Every cited Twilio and Telnyx page, the four Telnyx SDK model files and the crates.io/GitHub entries were re-fetched on 2026-10-08. Corrections made in place above:

1. Twilio Create Call: Twiml is the parameter ignored when both Twiml and Url are given (file previously said Url was ignored).
2. SendDigits vs MachineDetection: page says MachineDetection "will be ignored"; wording fixed.
3. Update Call description quote "Modifies an active call..." not verbatim on the page; replaced by the actual wording.
4. Parent/child call quotes reworded to the actual page text ("entirely new Call instance", "is considered in-progress by Twilio", "you must use Status=completed").
5. <Stream> TwiML page: the quoted "doesn't say what happens..." was not a page quote; "one Stream per Call" belongs to the media-streams overview page.
6. CallStatus values: initiated is not in the page's list.
7. Twilio AMD page has no example async payload; marked as constructed.
8. "Participants / Dial Number / Dial Sip are async only" not stated on the AMD page; marked UNVERIFIED (changelog says "run in the background").
9. Conference resource quote corrected ("Conference rooms are not directly created from the Programmable Voice API").
10. Twilio blog (2025-09-08): only "no unit tests" is stated; the claims of no briefing/summary and fragile error handling removed.
11. Participants announce URL verb list (<Play>, <Say>, <Pause>, <Redirect>) not confirmed; marked UNVERIFIED.
12. Telnyx 2.1: client_state/command_id/error codes are not on the sending-commands page (re-attributed to command pages); node-routing claim and source/meta error members marked UNVERIFIED; 60-second command_id window added.
13. Telnyx "compatible with the Standard Webhooks specification" not found on the webhooks page; marked UNVERIFIED.
14. Telnyx AMD "outbound call creation or inbound call transfer" wording not found; marked UNVERIFIED.
15. crates.io dtmf downloads: 3108 corrected to 9820.
16. call.dtmf.received verbatim quote replaced by a paraphrase of the webhooks page.
17. Telnyx refer sip_notify_response payload field not on the refer page; marked UNVERIFIED.
18. Twilio FAQ threshold hints: 1800-2000/1400-1500 are for residential/mobile callees (business: SpeechThreshold 1800-3000); clarified.
19. TaskRouter warm-transfer step 2 reworded (new TaskRouter task, then TwiML into conference); Twilio MachineDetectionTimeout range note (Create page lists none) added.
20. Telnyx: stop frame after streaming_stop ordering marked UNVERIFIED; premium event-ordering claim marked UNVERIFIED; added conference max_participants conflict, conference.recording.saved, join default, prompt_end_timeout_millis default conflict (5000 vs 30000).

Remaining UNVERIFIED items: Twilio REST rate limits/idempotency/error body; Update Call Twiml max length and error codes for ended calls; effect of REST update on an active bidirectional stream; whether <Connect action> fires on server close; AnsweredBy field name in the Url webhook; AsyncAmdStatusCallbackMethod GET support; MachineDetectionTimeout range (3-59 vs 3-60); AMD countries/Turkish support (both providers); SIP REFER and <Dial> billing; Twilio machine_start definition; whether DTMF tones are also in the media payload; Telnyx rate limits, call_control_id node routing, send_dtmf max digits and stream interplay (90045 scope), premium AMD payload schemas and default timeout, premium event ordering, sip_notify_response, Standard Webhooks compatibility, Webhook Fundamentals signature steps, call.dtmf.received outside Gather, $0.10 transfer invocation scope, Turkish voices for Telnyx speak; ITU DTMF frequency table except keys 5 and 8; carrier voicemail length limits.

G.711 (mu-law / A-law) — codec reference

• Fetched 2026-10-07. No tool to execute code was available in the research session, so every "DERIVED" value below was hand-computed from the fetched C code. Re-check them with a unit test against the quoted algorithm.
• Primary algorithm source (Sun Microsystems g711.c, as shipped in RAT): https://sources.debian.org/data/main/r/rat/4.2.20-3/codec_g711.c
• Other copies of the same Sun file (seen, only partially extracted): https://sources.debian.org/src/sox/12.16-6/g711.c , https://gnuradio.org/cgit/gnuradio.git/plain/gr-vocoder/lib/g7xx/g711.c , https://www.askapache.com/s/s.askapache.net/wireshark-1.1.3/g711.c
• ITU-T G.191 STL: https://raw.githubusercontent.com/openitu/STL/dev/src/g711/g711.c and g711.h (same dir)
• Format background: https://en.wikipedia.org/wiki/G.711 , https://en.wikipedia.org/wiki/%CE%9C-law_algorithm
• Twilio: https://www.twilio.com/docs/voice/media-streams/websocket-messages ; Telnyx: https://developers.telnyx.com/docs/voice/programmable-voice/media-streaming

License

Sun g711.c header (quoted from the RAT copy): "This source code is a product of Sun Microsystems, Inc. and is provided for unrestricted use. Users may copy or modify this source code without charge." (AS IS, no warranty.) Safe to port. The ITU STL licence text was NOT fetched: UNVERIFIED. No STL code is copied: brisvox implements the standard's behaviour independently (see "Decision" below) and credits the Sun code in codec.rs.

Sun reference algorithm (RAT copy, 16-bit short in/out, arithmetic >>)

#define SIGN_BIT (0x80)   #define QUANT_MASK (0xf)   #define SEG_SHIFT (4)   #define SEG_MASK (0x70)
#define BIAS (0x84)       #define CLIP 8159
seg_aend[8] = {0x1F,0x3F,0x7F,0xFF,0x1FF,0x3FF,0x7FF,0xFFF};
seg_uend[8] = {0x3F,0x7F,0xFF,0x1FF,0x3FF,0x7FF,0xFFF,0x1FFF};
search(val, table, size): first i with val <= table[i]; else return size.

linear2ulaw(short pcm_val):             // output already complemented
  pcm_val = pcm_val >> 2;               // 16 -> 14 bit, arithmetic shift (floor)
  if (pcm_val < 0) { pcm_val = -pcm_val; mask = 0x7F; } else mask = 0xFF;
  if (pcm_val > CLIP) pcm_val = CLIP;
  pcm_val += (BIAS >> 2);               // +33
  seg = search(pcm_val, seg_uend, 8);
  if (seg >= 8) return 0x7F ^ mask;     // out of range -> max code
  uval = (seg << 4) | ((pcm_val >> (seg + 1)) & 0xF);  return uval ^ mask;

ulaw2linear(uchar u_val):               // returns 16-bit scale directly
  u_val = ~u_val;
  t = ((u_val & QUANT_MASK) << 3) + BIAS;
  t <<= ((unsigned)u_val & SEG_MASK) >> SEG_SHIFT;
  return (u_val & SIGN_BIT) ? (BIAS - t) : (t - BIAS);

linear2alaw(short pcm_val):
  pcm_val = pcm_val >> 3;               // 16 -> 13 bit
  if (pcm_val >= 0) mask = 0xD5; else { mask = 0x55; pcm_val = -pcm_val - 1; }
  seg = search(pcm_val, seg_aend, 8);
  if (seg >= 8) return 0x7F ^ mask;
  aval = seg << SEG_SHIFT;
  aval |= (seg < 2) ? ((pcm_val >> 1) & QUANT_MASK) : ((pcm_val >> seg) & QUANT_MASK);
  return aval ^ mask;

alaw2linear(uchar a_val):
  a_val ^= 0x55;
  t = (a_val & QUANT_MASK) << 4;  seg = ((unsigned)a_val & SEG_MASK) >> SEG_SHIFT;
  seg==0: t += 8;  seg==1: t += 0x108;  else: t += 0x108; t <<= seg - 1;
  return (a_val & SIGN_BIT) ? t : -t;

Notes: the RAT file comment says the u-law biasing "shifts the encoding range from (0 - 8158) to (33 - 8191)". The sox 12.16 copy of g711.c is an older variant (single seg_end[8] = {0xFF,0x1FF,...,0x7FFF} table); CPython audioop.c (v3.12.0) defines CLIP 32635 and BIAS 0x84 (a 16-bit-domain form). Do not mix variants; whether the CPython form matches the 14-bit one was NOT checked: UNVERIFIED.

STL (ITU G.191) algorithm — differences

STL ulaw_compress: absno = (x<0 ? (~x)>>2 : x>>2) + 33; if (absno > 0x1FFF) absno = 0x1FFF; then segment by counting bits of absno>>6, low = 0xF - ((absno>>segno)&0xF), sign bit 0x80 set when x >= 0. Header comments say "only 12 MSBits are taken into account" (A-law) and 1's complement for negatives. STL alaw_compress: ix = (x<0 ? ~x : x) >> 4, loop-normalise, ^ 0x55, sign bit 0x80 when x >= 0. Decoders alaw_expand/ulaw_expand produce the same 16-bit scale (peak 32256 / 32124 by hand calc).

• Negative input in mu-law: STL uses ones' complement (~x), Sun uses two's-complement negate after the shift. DERIVED: Sun magnitude = ceil(|x|/4), STL = ceil(|x|/4) - 1, so for negative x the encoders can differ by one quantization step. Example: x = -1 -> Sun 0x7E, STL 0x7F (matches Wikipedia "-1 -> 0x7F" for 14-bit input). Consequently the Sun encoder never emits 0x7F (negative zero); both decode 0x7F as 0.
• A-law encoders: Sun (-p-1 after >>3) and STL (~x >> 4) agree for all 16-bit inputs; VERIFIED exhaustively by brisvox-audio tests (2026-10-08).
• Saturation: Sun clips at 8159 (biased 8192 -> seg 8 -> 0x7F ^ mask), STL clips biased value at 0x1FFF; same code (0x80 positive, 0x00 negative) DERIVED.
• A-law even-bit inversion: Sun/STL XOR 0x55 (sign handled by masks 0xD5/0x55). Wikipedia: "all resulting even bits (LSB is even) are inverted" so silence is 0xD5 (not 0x80). mu-law: all bits complemented, silence 0xFF.
• Zero-code suppression (T1 networks), ITU-T G.711 text (quoted via search snippet and the wikipedia mirror https://wikipedia.classicistranieri.com/en/articles/g/2E/7/G.711.html): "When using mu-law G.711 in networks where suppression of the all 0 character signal is required, the character signal corresponding to negative input values between decision values numbers 127 and 128 should be 00000010 and the value at the decoder output is -7519." (14-bit scale; DERIVED 16-bit scale -30076, vs. 0x00 = -32124). Neither Sun nor STL implements it. Only the encoder would substitute 0x00 -> 0x02; irrelevant for Twilio/Telnyx (IP, no T1 constraint). Do NOT implement.

Vectors

Legend: SRC = stated in a fetched source; DER = hand-derived from the fetched Sun code (confirm by test).

Carrier formats

• Twilio Media Streams (websocket-messages page): encoding "always audio/x-mulaw", sample rate "always 8000", payload "Raw mulaw/8000 audio encoded in base64"; payload "should not contain audio file type header bytes". Mono / 20 ms chunking not stated in the fetched text: UNVERIFIED.
• Telnyx media streaming: start-event example shows "encoding": "PCMU", "sample_rate": 8000, "channels": 1; bidirectional codecs listed: PCMU 8k (default), PCMA 8k, G722, OPUS, AMR-WB, L16 16k; chunk size "20 milliseconds to 30 seconds"; mismatched codec is transcoded. Telnyx uses base64 payloads. Default for non-bidirectional: UNVERIFIED.
• RTP payload types PCMU=0 / PCMA=8: page fetch failed (404), UNVERIFIED here.

Implementation guidance

• Decode: 256-entry [i16; 256] tables built at startup (const fn). Encode: 64K-entry u8 tables or arithmetic form (cheap; no inference pool needed).
• Use >> as arithmetic shift on i16 (Rust matches C here); use the 14-bit Sun form above and test against the vectors; add a test pinning the Sun-vs-STL negative-input difference so a future port does not silently change.

Decision (2026-10-08)

brisvox follows the ITU-T G.191 STL behaviour: for negative input, the μ-law magnitude is the ones' complement ((!x) >> 2) as in STL ulaw_compress, not Sun's negate-after-shift. This matches the standard's reference software and Wikipedia's "-1 -> 0x7F"; Sun differs by one step for some negative inputs (-1 -> 0x7E) and never emits 0x7F. A-law and both decoders are identical in the two. Verified exhaustively by brisvox-audio tests (all 65 536 inputs): the table encoders equal a const reference encoder and an independent STL-formulation encoder; the hand-derived vectors above (0xFE -> 8, 0x7E -> -8, 0x02 -> -30076, extremes, silence codes) hold. Verification status (2026-10-08): the decoders equal STL-formulation expanders for all 256 codes of both laws, and every reconstruction level lies inside its code's quantization interval (exhaustive tests in crates/brisvox-audio/src/codec.rs). The STL-formulation test codecs were written from the algorithm summary above, not from the STL source.

Operating brisvox-server

How the server process starts, hosts its call listeners, reports its health and shuts down . Code: brisvox_server::{settings, hosting, runner, providers, tools, health, lifecycle}, crates/brisvox-server/src/main.rs.

The binary loads one agent definition (BRISVOX_AGENT_FILE, docs/CONFIG.md), builds its STT, LLM and TTS adapters once (their keys come from the environment variables the definition names), starts the inference pool (half the cores) and binds the call listeners below. Every call runs the engine (run_call) as one session of the session manager, with the bundled Silero VAD (feature silero-tract, on by default). The generic websocket, Twilio, Telnyx, RTVI and (with the sip / webrtc features) SIP and WebRTC listeners are hosted. The provider adapters are cargo features of brisvox-server (provider-*, or all-providers); the default build has none, so build the binary with the ones the agent names (cargo build --release -p brisvox-server --features all-providers), otherwise the definition is refused at startup with the feature to turn on.

Tools (docs/TOOLS.md "In the server binary"): every tool the definition lists in agent.tools must exist, or the start fails with the tool's position in the file and what would provide it. The binary provides the telephony tools transfer_call, send_dtmf and end_call when a carrier's call control is configured (BRISVOX_CALL_CONTROL, cargo feature call-control) and, with the cargo feature demo-tools (never for callers), canned lookup_order and book_appointment for the examples. An application's own tools plug in through brisvox_server::tools::AppTools in its own main, one line over this library: brisvox_server::app::run_with_tools(Arc::new(MyTools)) (docs/TOOLS.md "Rust tools in your own binary", examples/rust-tools).

Command line. brisvox-server with no arguments runs the server. brisvox-server check <agent-file> [--require-secrets] validates an agent file offline (docs/CONFIG.md "Checking a file"; exit 0 ok, 1 errors), --version and --help print and exit, and any other argument is refused with exit status 2 instead of starting a server.

Smart Turn (cargo feature smart-turn-ort; the ONNX Runtime binaries are downloaded at build time): an agent whose turn policy is adaptive (the default) gets the Smart Turn v3.2 model, loaded at startup from BRISVOX_SMART_TURN_MODEL (default $BRISVOX_MODELS_DIR/smart-turn-v3.2-cpu.onnx, models/ when unset; fetch it with scripts/models/fetch_models.py). A model that does not load stops the start; off runs without it. A build without the feature logs a warning and adaptive turns end at their fallback deadline. The analyses run on an executor of their own (BRISVOX_SMART_TURN_THREADS): its queue holds 32 analyses per thread and refuses the rest, and a refused analysis makes that turn end at its fallback deadline (logged as smart turn analysis failed); the VAD's pool, and the admission control reading it, are not affected, so watch brisvox_smart_turn_rejected_total and brisvox_smart_turn_timed_out_total (see Metrics). The executor's threads are named brisvox-turn-<i>.

Provider resilience: every call runs its STT, LLM and TTS behind the resilience layer with its default settings. The circuit breakers are per provider instance and shared by all calls (5 consecutive failures open one for 30 s), retries are budgeted per call (3) and per process (50), a dead STT or TTS session is recovered in place, and an idle TTS session is replaced at 80 % of the provider's idle limit (Cartesia: 4 of its 5 minutes). Nothing is configured for this; a second provider per stage to fail over to is the agent definition's [stt|llm|tts].secondary (docs/CONFIG.md), whose API keys must be set like the primaries'.

Build for a phone deployment with everything: cargo build --release -p brisvox-server --features all-providers,call-control,smart-turn-ort.

Settings (environment)

Agent definitions (docs/CONFIG.md) describe agents; the process itself is configured by environment variables. Unset or blank means the default; an invalid value stops the start with exit status 1 and a message naming the variable.

A listener address is host:port or off. Without any listener (BRISVOX_WS_ADDR=off and the others unset) the binary serves its health endpoints only and needs no agent file.

Port placeholder. The listener address variables (BRISVOX_HEALTH_ADDR, BRISVOX_WS_ADDR, BRISVOX_TWILIO_ADDR, BRISVOX_TELNYX_ADDR, BRISVOX_RTVI_ADDR, BRISVOX_SIP_ADDR, BRISVOX_SIP_TLS_ADDR, BRISVOX_WEBRTC_ADDR, BRISVOX_WEBRTC_UDP_ADDR, BRISVOX_WEBRTC_TCP_ADDR, BRISVOX_CALLBACK_ADDR) accept the exact token ${PORT}, replaced by the PORT variable that PaaS hosts (Railway, Heroku, Fly, Cloud Run) inject: BRISVOX_WS_ADDR=[::]:${PORT}. No other expansion happens ($PORT, ${port}). A value that uses the token while PORT is unset or not a number from 1 to 65535 stops the start with a message naming both variables. A value without the token never reads PORT.

Agent definition in a variable. BRISVOX_AGENT_DEFINITION holds the text of the agent definition instead of a file path (docs/CONFIG.md, "The agent definition from the environment"); brisvox-server check --env validates it offline.

Authentication (docs/SECURITY.md). The generic websocket protocol has no authentication of its own (docs/WEBSOCKET_PROTOCOL.md), and its connections take the same session reservations as every other listener's: anyone who reaches an open one can run the agent on your STT/LLM/TTS keys, and a few hundred idle sockets (each holds a reservation for its 5 s handshake) fill BRISVOX_MAX_SESSIONS, so that signed Twilio calls get 503. That is why it is never on by default next to another listener, and listens on loopback only when it is the only one. And the generic websocket, RTVI, WebRTC signaling and Telnyx listeners refuse to start on a non-loopback address without authentication: set BRISVOX_SESSION_SECRET (your backend mints short-lived single-use tokens; the production way) or the listener's static token (BRISVOX_WS_TOKEN, BRISVOX_RTVI_TOKEN, BRISVOX_WEBRTC_TOKEN, BRISVOX_TELNYX_STREAM_TOKEN; development, logged as a warning), or accept the risk with BRISVOX_INSECURE_LISTENERS=1 (logged as a warning per exposed listener). Loopback binds need nothing. Twilio always verifies its signature; SIP has its own source ACL and digest rule. Terminate TLS in a reverse proxy in front of every public listener.

The WebRTC listener (feature webrtc: cargo build -p brisvox-server --features all-providers,webrtc, which compiles libopus and needs a C compiler and cmake, docs/TESTING.md) hosts brisvox_transport::webrtc (docs/ARCHITECTURE.md "WebRTC transport"; a runnable page: examples/web-assistant). Media is UDP on one shared socket: forward BRISVOX_WEBRTC_UDP_ADDR and set BRISVOX_WEBRTC_CANDIDATE_IP to the address browsers reach. A network that blocks UDP connects through ICE-TCP (BRISVOX_WEBRTC_TCP_ADDR) or a browser-side TURN relay (BRISVOX_TURN_PROVIDER); a server host with no inbound UDP (a one-port PaaS such as Railway) uses the WebSocket fallback or the server's own TURN relay (BRISVOX_WEBRTC_TURN_RELAY, the server allocates a relayed address on a TURN service over TLS/443). All of it is in docs/DEPLOY.md. Differences from the websocket listeners:

• No gate before the handshake. A call reaches the engine once its ICE and DTLS completed and is admitted then; with no room (BRISVOX_MAX_SESSIONS, overload, provider budget, draining) the browser connects and the call is hung up at once, logged as call without a reservation refused. The transport's own call limit (twice the manager's) bounds the sockets.
• Authentication. Signaling needs BRISVOX_SESSION_SECRET (a session token per call in Authorization: Bearer) or BRISVOX_WEBRTC_TOKEN (shared, for development) on a non-loopback address, like the other exposed listeners (above): anyone who reaches an open one runs the agent on your provider keys. Signaling must be served over HTTPS (a proxy in front of the TCP port): the DTLS fingerprint travels in the SDP, and over plain HTTP an on-path attacker can swap it and hear the call. DELETE is authorized by the session URL when session tokens are in use. A session token's max_s caps the call.
• Flood limits. Per client address: 5 offers a minute (BRISVOX_WEBRTC_OFFERS_PER_MINUTE, 429), 8 calls at once (BRISVOX_WEBRTC_MAX_CALLS_PER_IP, 429); calls still handshaking are capped at a quarter of BRISVOX_MAX_SESSIONS (BRISVOX_WEBRTC_MAX_HANDSHAKING, 503). Behind a proxy set BRISVOX_TRUSTED_PROXIES so the address is the visitor's, not the proxy's. The counters are in WebRtcServer::stats().
• Codec on the inference pool. The Opus work of every call (90 to 376 us a frame) runs on the server's inference pool, never on tokio workers.
• Like every listener it stops with the server: the cancel stage ends its calls.

The SIP listener needs BRISVOX_SIP_ALLOWED_SOURCES or the digest credentials (or both): an open SIP port is scanned within minutes, and the binary refuses to start without either. For a trunk across the internet add SIPS and SRTP: BRISVOX_SIP_TLS_ADDR (5061) with BRISVOX_SIP_TLS_CERT and BRISVOX_SIP_TLS_KEY, and BRISVOX_SIP_SRTP=required. SDES keys are only ever taken from TLS signaling, so with required the cleartext UDP/TCP port refuses every call (488); keep it for health checks or close it with the ACL. The certificate must be one the carrier trusts (a public CA for Twilio and Telnyx). SipStats counts tls_connections, tls_rejected, tls_handshake_failures, tls_idle_closed, srtp_calls, rejected_insecure, srtp_packets_rejected, srtp_flood_hangups and insecure_dialog_requests (in-dialog requests of a TLS dialog that did not come over TLS: refused or stripped of their SDP; a steady count means someone on the signaling network is probing). Never run the server with RUST_LOG lifting rsipstack (it cannot: the filter is fixed, see BRISVOX_LOG_SIP_STACK). A start-up warning from rsipstack about an unsupported listener type is expected with SIPS (the placeholder that makes requests to TLS callees carry a TLS Via).

Durations are a whole number with ms, s or m (500ms, 45s, 10m); a bare number is seconds; at most one day.

Callback listener

With a carrier's call control (BRISVOX_CALL_CONTROL, feature call-control) and BRISVOX_CALLBACK_ADDR set, the binary serves a small HTTP listener through which the world tells a live call what the carriers' REST call control cannot return (the endpoints, the authentication and the limits are in brisvox_server::callbacks):

{call} is the carrier's id of the caller's call: Twilio's CallSid, Telnyx's call_control_id. The application that originates or receives the call has it; it is also in the call's stream metadata.

Every request needs the shared secret as Authorization: Bearer <secret>, or as the password of Authorization: Basic for carriers that can only put credentials in a URL (https://user:<secret>@host/v1/amd/twilio); the compare is constant time and a request without it gets 401 before its body is read. The secret travels in a header: serve the listener over TLS (a proxy) and keep it on a private address when you can. Carrier webhooks are not signature-checked by this listener. Errors are {"error":"<code>","message":"..."}: 404 no_such_call (the call ended, or never was), 409 no_warm_transfer / no_voicemail, 502 carrier_error, 504 timeout, 400/413/431/501 for malformed requests.

The listener is bounded: 32 requests at once (more are closed unanswered), 5 s to read a request or write the answer, 25 s for the handler, head 8 KiB, body 16 KiB, no keep-alive and no chunked bodies. It serves through the drain (a call that is still running may need its callbacks) and stops after the transports. It is a separate port from the health probes on purpose: it changes calls and is authenticated; the probes are neither.

A warm transfer nobody finishes does not leave the caller alone: when the call's session ends (the stream's linger passed, shutdown) with the transfer pending, the server aborts it and hangs the caller up.

Agent process