Agent Skills
› fanfan-de/anybox
› twilio-call-recordings
twilio-call-recordings
GitHub指导如何正确录制Twilio语音通话，区分Record与Dial record，支持双通道、PCI合规暂停及会议录制。涵盖Python/Node.js实现、回调处理及安全验证，用于合规、质检或分析场景。
Trigger Scenarios
需要录制Twilio电话通话
配置通话录音以符合合规要求
实现双通道录音进行质检
在支付环节暂停录音以满足PCI标准
Install
npx skills add fanfan-de/anybox --skill twilio-call-recordings -g -y
SKILL.md
Frontmatter
{
"name": "twilio-call-recordings",
"description": "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."
}
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) |
Prerequisites
- Twilio account with a voice-capable phone number — see
twilio-account-setup TWILIO_ACCOUNT_SIDandTWILIO_AUTH_TOKEN— seetwilio-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-Signatureon 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
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 |
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 |
CANNOT
recordingTrackhas no observable effect via TwiML — The<Start><Recording>TwiML parameterrecordingTrackdoes not isolate tracks. Use the Recordings REST API withrecordingTrackfor actual track isolation.- Cannot start API recordings on ConversationRelay calls — REST API
record:trueis 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 (
updatewithstatus="paused"orstatus="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=truedefaults to mono. Must specifyrecordingChannels: '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
Version History
- 08dc189 Current 2026-07-05 19:08
