Record a call

Voicecall recording

Start a recording and pick it up from the completion webhook.

recording

The claim

record_call starts a background recording and returns immediately, so the verbs after it, including the connect that brings in the agent, run inside the recording. The recording URL is not in the SWML response and not in the call; it arrives at status_url when the recording finishes.

How it works

- answer: {}
- record_call:
    format: wav
    stereo: true        # caller on one channel, agent on the other
    direction: both
    status_url: "https://<your-host>/recording-status"
- play: { url: "say:This call is recorded for quality purposes." }
- connect: { to: "+1555..." }

Order matters: record_call before connect. The Python surface builds the same document with SWMLService and adds a Flask route for status_url that stores the URL only when state is finished.

Stopping early is stop_record_call; recordings are listed and deleted over REST (/api/relay/rest/recordings). To send recordings to your own storage instead of SignalWire’s, see export-recordings-and-enforce-retention. That path exists only in the Compatibility API’s <Record storageUrl>.

What to change first

Add get-recording-consent-before-recording in front: move record_call into a tool result so recording starts only after the caller agrees.

Where this sits

Before this

Answer an inbound call

Get recording consent before recording

Start live transcription and consume the webhook

Seen in a build

One of 7 recipes composed by IVR navigator: an AI agent that works through phone menus to reach a human.

python/app.py

"""Record a call.

Background recording starts before the bridge, so the recording covers both
legs of the conversation. When it finishes, SignalWire POSTs the recording URL
to status_url; the Flask route below receives it.

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")
AGENT = os.getenv("AGENT_NUMBER", "+15550100001")

app = Flask(__name__)


def build(service=None):
    service = service or SWMLService(name="record", route="/record")
    service.reset_document()
    service.add_verb("answer", {})
    # Before connect: the bridged leg is inside the recording.
    service.add_verb("record_call", {
        "format": "wav",
        "stereo": True,          # caller on one channel, agent on the other
        "direction": "both",
        "status_url": f"{PUBLIC_URL}/recording-status",
    })
    service.add_verb("play", {"url": "say:This call is recorded for quality purposes."})
    service.add_verb("connect", {"to": AGENT})
    service.add_verb("hangup", {})
    return service


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


recordings = {}


@app.post("/recording-status")
def recording_status():
    """The recording URL arrives here, not in the SWML fetch."""
    p = request.get_json(silent=True) or request.form.to_dict()
    call_id = p.get("call_id")
    if p.get("state") == "finished" and p.get("url"):
        recordings[call_id] = {"url": p["url"], "duration": p.get("duration")}
    return "", 204


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

# Record a call - background recording that covers the bridged leg too.
# record_call starts before connect, so the whole conversation is recorded.
# The recording URL arrives at status_url when the recording finishes.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - record_call:
        format: wav
        stereo: true
        direction: both
        status_url: "https://your-host.example.com/recording-status"
    - play: { url: "say:This call is recorded for quality purposes." }
    - connect: { to: "+15550100001" }
    - hangup: {}

Run it

Markup only: paste swml/agent.yaml into a SWML Script, replace the number and status_url, assign a phone number.

Python:

cd python
pip install -r requirements.txt
PUBLIC_URL=https://<your-host> AGENT_NUMBER=+1555... python app.py

Point a phone number’s SWML webhook at https://<your-host>/record.

Verify it

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

Both surfaces validate against the SWML schema. The verifier asserts record_call precedes connect, records both directions in stereo and names a status_url, and that the webhook stores a URL only for a finished recording.

Report an issue