twilio-call-recordings

✓ Official★ 4,081

by openai · part of openai/plugins

Record Twilio voice calls correctly. Covers the critical distinction between Record verb (voicemail) and Dial record (call recording), dual-channel for QA, mid-call pause for PCI, Conference recording, and the ConversationRelay workaround. Use this skill whenever you need to capture call audio for compliance, QA, or analytics.

🧩 One of 7 skills in the openai/plugins package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

Overview

Twilio offers multiple recording methods. Choosing the wrong one is the #1 developer mistake in voice — using <Record> when you mean <Dial record> produces voicemail behavior instead of call recording.

Method	What it does	Use when
`<Record>` verb	Records the CALLER only (voicemail-style)	Leaving a message, capturing input
`<Dial record>`	Records BOTH parties on a call	Call recording for two-party calls
`<Start><Recording>`	Starts a recording alongside other verbs	ConversationRelay, multi-verb flows
Conference `record`	Records the conference mix	Multi-party calls
Recordings REST API	Programmatic control mid-call	Pause during payment (PCI)

Key Patterns

Recording Modes for `<Dial record>`

Mode	What's recorded	Use case
`record-from-answer`	Single channel, both parties mixed	Simple recording
`record-from-answer-dual`	Dual channel — caller on left, agent on right	QA (separate agent/caller audio)
`record-from-ringing`	Records from ring, not answer	Capture ring time + full call
`record-from-ringing-dual`	Dual channel from ring	QA with ring time

Always use dual for QA and analytics. Dual-channel lets speech analytics tools (like Conversation Intelligence) distinguish agent from caller.

Conference Recording

Record multi-party calls via the Conference:

Python

response = VoiceResponse()
dial = response.dial()
dial.conference(
    "support-room-123",
    record="record-from-start",  # Records from when conference starts
    recording_status_callback="https://yourapp.com/conf-recording-status"
)

Note: Conference recording captures the main audio mix. Coach/whisper audio is NOT included. See twilio-conference-calls.

ConversationRelay Recording

Critical: record:true on the REST API call is silently ignored with ConversationRelay. No error. No recording.

Correct approach: Use <Start><Recording> in TwiML before <Connect>:

Python

@app.route("/voice", methods=["POST"])
def voice():
    response = VoiceResponse()
    response.say("This call may be recorded.")
    
    # Start recording BEFORE connecting ConversationRelay
    start = Start()
    start.recording(
        recording_status_callback="https://yourapp.com/recording-status",
        recording_status_callback_event="completed"
    )
    response.append(start)
    
    # Now connect ConversationRelay
    connect = Connect()
    connect.conversation_relay(url="wss://yourapp.com/ws/voice")
    response.append(connect)
    
    return str(response)

Node.js

app.post("/voice", (req, res) => {
    const response = new VoiceResponse();
    response.say("This call may be recorded.");
    
    const start = response.start();
    start.recording({
        recordingStatusCallback: "https://yourapp.com/recording-status",
        recordingStatusCallbackEvent: "completed",
    });
    
    const connect = response.connect();
    connect.conversationRelay({ url: "wss://yourapp.com/ws/voice" });
    
    res.type("text/xml").send(response.toString());
});

Mid-Call Pause for PCI Compliance

Pause recording when a customer provides payment information:

Python

def pause_recording_for_payment(call_sid, recording_sid):
    """Pause recording during credit card capture."""
    client.calls(call_sid).recordings(recording_sid).update(
        status="paused"
    )

def resume_recording(call_sid, recording_sid):
    """Resume recording after payment processed."""
    client.calls(call_sid).recordings(recording_sid).update(
        status="in-progress"
    )

Node.js

async function pauseForPayment(callSid, recordingSid) {
    await client.calls(callSid).recordings(recordingSid).update({
        status: "paused",
    });
}

async function resumeRecording(callSid, recordingSid) {
    await client.calls(callSid).recordings(recordingSid).update({
        status: "in-progress",
    });
}

PCI DSS: Never record card numbers. Use Twilio's <Pay> verb when possible. If collecting verbally, pause recording for the duration. PCI Mode is IRREVERSIBLE and account-wide — use a sub-account if only some calls need PCI.

Accessing Recordings

Python

# List recordings for a specific call
recordings = client.recordings.list(call_sid=call_sid)

for recording in recordings:
    print(f"SID: {recording.sid}")
    print(f"Duration: {recording.duration}s")
    print(f"URL: https://api.twilio.com{recording.uri.replace('.json', '.mp3')}")

# Download a recording
import requests as req
audio = req.get(
    f"https://api.twilio.com/2010-04-01/Accounts/{account_sid}/Recordings/{recording_sid}.mp3",
    auth=(account_sid, auth_token)
)
with open("recording.mp3", "wb") as f:
    f.write(audio.content)

# Delete a recording (GDPR right to deletion)
client.recordings(recording_sid).delete()

Recording Storage & Retention

Feature	Default	Notes
Storage location	Twilio cloud	Can configure external storage (S3, GCS)
Retention	Indefinite	Delete manually via API or set auto-delete policy
Formats	WAV (default), MP3	Request MP3 by appending `.mp3` to URL
Encryption	At rest	Additional encryption with PCI Mode

CANNOT

recordingTrack has no observable effect via TwiML — The <Start><Recording> TwiML parameter recordingTrack does not isolate tracks. Use the Recordings REST API with recordingTrack for actual track isolation.
Cannot start API recordings on ConversationRelay calls — REST API record:true is silently ignored ("not eligible for recording"). Must use <Start><Recording> before <Connect> in TwiML.
Cannot pause/resume recordings via TwiML — Only available via the REST API (update with status="paused" or status="in-progress").
Cannot get dual-channel conference recordings — Conference recording is always mono (mixed).
Cannot get dual-channel from Calls API without explicit param — Record=true defaults to mono. Must specify recordingChannels: 'dual'.
Cannot transcribe PCI-mode recordings — Recordings created while PCI mode was enabled cannot be transcribed, even after PCI is disabled.
Cannot use <Record> verb for call recording — <Record> captures the caller only (voicemail-style). Use <Dial record> or <Start><Recording> for call recording.
Cannot capture coach/whisper audio in conference recordings — Supervisor whisper is excluded from the mix
Cannot reverse PCI Mode — PCI Mode is irreversible and account-wide. Once enabled, all recordings are encrypted.
Cannot auto-delete recordings without configuration — Recordings are retained indefinitely unless you configure auto-deletion
Cannot avoid larger file sizes with dual-channel — Dual-channel recordings are ~2x the size of mono. Factor into storage costs.

Next Steps

Conference calls: twilio-conference-calls
Agent routing: twilio-taskrouter-routing
Compliance: twilio-compliance-traffic
Debug recording issues: twilio-debugging-observability

Copy & paste — that's it

npx skills add https://github.com/openai/plugins --skill twilio-call-recordings

Run this in your project — your agent picks the skill up automatically.

Prerequisites

Twilio account with a voice-capable phone number — see twilio-account-setup
TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN — see twilio-iam-auth-setup
SDK: pip install twilio / npm install twilio
A webhook endpoint for recording status callbacks
Compliance check: Recording consent requirements vary by jurisdiction — see twilio-compliance-traffic

Quickstart

Record a Two-Party Call (Most Common)

Use <Dial record> — NOT <Record>.

Python (Flask)

from flask import Flask, request
from twilio.twiml.voice_response import VoiceResponse

app = Flask(__name__)

@app.route("/voice", methods=["POST"])
def incoming_call():
    response = VoiceResponse()
    response.say("This call may be recorded for quality assurance.")
    dial = response.dial(
        record="record-from-answer-dual",  # dual-channel: agent on one, caller on other
        recording_status_callback="https://yourapp.com/recording-status"
    )
    dial.number("+15558675310")  # agent's phone
    return str(response)

Node.js (Express)

app.post("/voice", (req, res) => {
    const response = new VoiceResponse();
    response.say("This call may be recorded for quality assurance.");
    const dial = response.dial({
        record: "record-from-answer-dual",
        recordingStatusCallback: "https://yourapp.com/recording-status",
    });
    dial.number("+15558675310");
    res.type("text/xml").send(response.toString());
});

Handle the Recording Status Callback

Security: Validate X-Twilio-Signature on recording callbacks in production. Without validation, attackers could POST fake recording URLs to your endpoint.

Python (Flask)

@app.route("/recording-status", methods=["POST"])
def recording_status():
    recording_sid = request.form["RecordingSid"]
    recording_url = request.form["RecordingUrl"]
    call_sid = request.form["CallSid"]
    status = request.form["RecordingStatus"]  # "completed", "failed"
    duration = request.form.get("RecordingDuration", 0)

    if status == "completed":
        # Store recording reference
        save_recording(call_sid, recording_sid, recording_url, duration)

    return "", 200

Common Errors

Symptom	Cause	Fix
Recording captures only caller (no agent)	Used `<Record>` verb instead of `<Dial record>`	Switch to `<Dial record="record-from-answer">`
No recording at all	Used REST API `record:true` with ConversationRelay	Use `<Start><Recording>` in TwiML
Recording is empty / silent	Webhook endpoint unreachable, recording never started	Check StatusCallback URL reachability
Recording has both parties on same channel	Used `record-from-answer` (mono)	Use `record-from-answer-dual` for separate channels
Coach audio missing from conference recording	Expected behavior — coach audio isn't in the mix	Record coach's call leg separately

Overview

Key Patterns

Recording Modes for <Dial record>

Conference Recording

ConversationRelay Recording

Mid-Call Pause for PCI Compliance

Accessing Recordings

Recording Storage & Retention

CANNOT

Next Steps

Prerequisites

Quickstart

Record a Two-Party Call (Most Common)

Handle the Recording Status Callback

Common Errors

Recording Modes for `<Dial record>`