Listen to a live call

Voicesilent call monitoring

Attach to a call in progress and hear both sides without joining it.

Also called call monitoring, silent monitor, live call listening

tapmedia-streaming

The claim

Call audio forked to a WebSocket you own, in real time, with nothing added to the call. Nobody is conferenced in and nothing is announced, because a tap copies media rather than joining the room.

Why it holds

This is how you build a monitoring console. Speaking to the people on the call is a different mechanism entirely, and it is a conference.

How it works

tap takes a uri, and that is its only required field. The scheme decides the transport: ws://, wss:// or rtp://.

- tap:
    uri: "wss://your-host.example.com/ws/audio"
    direction: both
    codec: PCMU
    control_id: supervisor-audio

tap comes before connect. connect owns the bridge until the far leg ends, so a tap placed after it does not start until the conversation is over. That ordering is the same trap record_call and live_transcribe have.

direction decides whose audio you receive. listen is what the party hears, speak is what they say, and both is the conversation. A console that only gets speak records half a call and sounds broken.

codec is PCMU or PCMA. Whatever is on the other end of the socket has to decode it, and PCMU is the default for a reason.

control_id is the handle stop_tap needs. Without one the tap runs for the life of the call and there is no way to end it early.

Limitations

You have to run the socket. A tap with nowhere to connect is a call that works and a console that is silent. The failure is on your side of the wire.

The audio is raw PCMU frames, not a file and not a transcript. Turning it into words is start-live-transcription, which is a different verb and does not need a socket at all.

What to change first

Move tap below connect and call the number. The console stays silent for the whole conversation, and the tap starts as the call ends.

python/app.py

"""Listen to a live call.

`tap` forks the call's audio to a socket you own while the call continues. The
participants hear nothing: this is a copy of the media, not a third party in
the room.

It runs before `connect`, so the leg the bridge adds is inside the tap. After
`connect` it would not run until the bridge had already ended.

`direction` decides whose audio you get. `listen` is what the party hears,
`speak` is what they say, and `both` is the conversation.

Written against signalwire-sdk 3.0.1 (SWMLService) and Flask.
"""
import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request
from signalwire import SWMLService

# the SDK does not read .env for you
load_dotenv()

PUBLIC_URL = os.getenv("PUBLIC_URL", "https://your-host.example.com")
AUDIO_WS = os.getenv("AUDIO_WS", "wss://your-host.example.com/ws/audio")
AGENT = os.getenv("AGENT_NUMBER", "+15550100001")

app = Flask(__name__)
taps = {}   # control_id -> last status seen


def build(service=None):
    service = service or SWMLService(name="listen", route="/listen")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("tap", {
        # where the copy goes: ws://, wss:// or rtp://
        "uri": AUDIO_WS,
        # both sides, so the socket receives the conversation
        "direction": "both",
        # PCMU is the default and what most decoders expect
        "codec": "PCMU",
        # a handle for stop_tap
        "control_id": "supervisor-audio",
        "status_url": f"{PUBLIC_URL}/tap-status",
    })
    # before connect: a tap placed after it never runs while anyone is talking
    service.add_verb("connect", {"to": AGENT})
    service.add_verb("hangup", {})
    return service


@app.route("/listen", methods=["GET", "POST"])
def swml():
    return jsonify(build().get_document())


@app.post("/tap-status")
def tap_status():
    event = request.get_json(force=True, silent=True) or request.form.to_dict()
    control_id = event.get("control_id") or "unknown"
    taps[control_id] = event.get("state") or event.get("status") or "unknown"
    return "", 204


if __name__ == "__main__":
    app.run(port=int(os.getenv("PORT", "8080")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set AUDIO_WS
python app.py

Point a phone number’s SWML webhook at https://<your-host>/listen. The socket at AUDIO_WS has to be accepting connections before the call arrives.

Verify it

No network, no account:

python verify.py          # from the recipe folder, not python/

The document validates against the SWML schema. The verifier asserts:

the verbs are answer, tap, connect, hangup, in that order
tap precedes connect, so the bridged leg is inside the tap
the URI is one of the documented schemes, and a WebSocket one here
direction is both and the codec is documented
a control_id is set, so the tap can be stopped
no play, prompt, join_conference or say appears anywhere. That is what “the participants hear nothing” means in an artifact
the status webhook records the tap’s state under its control id

Report an issue