Terminal
Terminal/Skill
Shows how to build multi-party Twilio calls for contact centers, including warm and cold transfers, whisper coaching, holds, and supervisor barge in.
By Twilio
Works with
npx skills add twilio/ai --skill twilio-conference-callsConference is the foundation of contact center call handling. The key insight: every call that might need a transfer should start as a Conference, not a direct <Dial>. A Conference supports hold, transfer, coaching, and recording — a direct Dial does not.
Caller ──→ Conference Room ←── Agent
↑
Supervisor (coach mode: speaks to agent only)
Contact center best practice: Every multi-agent call should use Conference, not direct Dial.
twilio-account-setupTWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN — see twilio-iam-auth-setuppip install twilio / npm install twiliotwilio-taskrouter-routingStep 1 — Put the inbound caller into a Conference
When a call comes in, place the caller into a named Conference room.
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():
call_sid = request.form["CallSid"]
response = VoiceResponse()
dial = response.dial()
dial.conference(
f"room-{call_sid}",
start_conference_on_enter=True,
end_conference_on_exit=False, # Keep conference alive when caller disconnects (for wrap-up)
wait_url="http://twimlets.com/holdmusic?Bucket=com.twilio.music.classical",
status_callback="https://yourapp.com/conference-events",
status_callback_event="join leave",
record="record-from-start"
)
return str(response)
Node.js (Express)
app.post("/voice", (req, res) => {
const callSid = req.body.CallSid;
const response = new VoiceResponse();
const dial = response.dial();
dial.conference(
`room-${callSid}`,
{
startConferenceOnEnter: true,
endConferenceOnExit: false,
waitUrl: "http://twimlets.com/holdmusic?Bucket=com.twilio.music.classical",
statusCallback: "https://yourapp.com/conference-events",
statusCallbackEvent: "join leave",
record: "record-from-start",
}
);
res.type("text/xml").send(response.toString());
});
Step 2 — Connect an agent to the same Conference
After TaskRouter assigns a worker, dial the agent into the conference:
Security: Never interpolate untrusted user input into inline
twiml=strings. Use the SDK'sVoiceResponsebuilder for any dynamic content.
Python
# Called from your assignment callback or agent connect logic
def connect_agent(conference_name, agent_phone):
client.calls.create(
to=agent_phone,
from_="+15551234567", # your Twilio number
twiml=f'''<Response>
<Dial>
<Conference>{conference_name}</Conference>
</Dial>
</Response>''',
status_callback="https://yourapp.com/agent-call-status"
)
Node.js
async function connectAgent(conferenceName, agentPhone) {
await client.calls.create({
to: agentPhone,
from: "+15551234567",
twiml: `<Response><Dial><Conference>${conferenceName}</Conference></Dial></Response>`,
statusCallback: "https://yourapp.com/agent-call-status",
});
}
Put caller on hold → dial new agent into Conference → original agent briefs new agent → original agent drops.
Python
def warm_transfer(conference_sid, original_agent_call_sid, new_agent_phone, conference_name):
# Step 1: Put caller on hold (hold = hears music, can't hear agents)
caller_participant = client.conferences(conference_sid) \
.participants(caller_call_sid) \
.update(hold=True)
# Step 2: Dial new agent into the same conference
client.calls.create(
to=new_agent_phone,
from_="+15551234567",
twiml=f'<Response><Dial><Conference>{conference_name}</Conference></Dial></Response>',
status_callback="https://yourapp.com/transfer-agent-status"
)
# Step 3: Original agent briefs new agent (caller is on hold, can't hear)
# ... agents talk ...
# Step 4: Take caller off hold
client.conferences(conference_sid) \
.participants(caller_call_sid) \
.update(hold=False)
# Step 5: Original agent leaves
client.conferences(conference_sid) \
.participants(original_agent_call_sid) \
.update(status="completed") # Removes from conference
Simpler — just redirect the caller to a new agent without briefing.
Python
def cold_transfer(conference_sid, original_agent_call_sid, new_agent_phone, conference_name):
# Remove original agent
client.conferences(conference_sid) \
.participants(original_agent_call_sid) \
.update(status="completed")
# Dial new agent into conference
client.calls.create(
to=new_agent_phone,
from_="+15551234567",
twiml=f'<Response><Dial><Conference>{conference_name}</Conference></Dial></Response>'
)
| Feature | Hold | Mute |
|---|---|---|
| Participant hears | Hold music | Everything (but can't speak) |
| Other participants hear | Nothing from held party | Nothing from muted party |
| Use when | Transfer briefing, agent lookup | Quick aside (agent mutes self to cough) |
| API | hold=True | muted=True |
# Hold — plays music to the held participant
client.conferences(conf_sid).participants(participant_sid).update(hold=True)
client.conferences(conf_sid).participants(participant_sid).update(hold=False)
# Mute — silences the participant but they still hear
client.conferences(conf_sid).participants(participant_sid).update(muted=True)
client.conferences(conf_sid).participants(participant_sid).update(muted=False)
Critical distinction: Hold plays music. Mute just silences. Using mute when you mean hold exposes agent-side conversations to the caller.
Supervisor joins the Conference and can speak to the agent only — the caller cannot hear the supervisor.
Python
def add_coach(conference_sid, supervisor_phone, conference_name):
"""Add supervisor as coach — speaks to agent only, caller can't hear."""
client.calls.create(
to=supervisor_phone,
from_="+15551234567",
twiml=f'''<Response>
<Dial>
<Conference
coach="{agent_call_sid}"
statusCallback="https://yourapp.com/coach-events"
>{conference_name}</Conference>
</Dial>
</Response>'''
)
Node.js
async function addCoach(conferenceSid, supervisorPhone, conferenceName, agentCallSid) {
await client.calls.create({
to: supervisorPhone,
from: "+15551234567",
twiml: `<Response>
<Dial>
<Conference coach="${agentCallSid}">${conferenceName}</Conference>
</Dial>
</Response>`,
});
}
Coach behavior:
Supervisor joins and speaks to everyone — useful for escalation or takeover.
def barge_in(conference_sid, supervisor_phone, conference_name):
"""Supervisor joins as full participant — everyone hears them."""
client.calls.create(
to=supervisor_phone,
from_="+15551234567",
twiml=f'<Response><Dial><Conference>{conference_name}</Conference></Dial></Response>'
)
# List all participants in a conference
participants = client.conferences(conference_sid).participants.list()
for p in participants:
print(f"CallSid: {p.call_sid}, Muted: {p.muted}, Hold: {p.hold}")
# Remove a participant
client.conferences(conference_sid).participants(call_sid).update(status="completed")
# End the entire conference
client.conferences(conference_sid).update(status="completed")
A Conference with only one participant is in a waiting state. The single participant hears hold music. API calls to the Conference may behave unexpectedly until a second participant joins.
Conference recordings capture the main audio mix only. Coach/whisper audio is NOT recorded. If you need to record coaching sessions for QA, add a separate recording on the supervisor's call leg.
If endConferenceOnExit=True for any participant, the conference ends when they leave — dropping all other participants. Set this carefully:
False (so agents can wrap up)False (so caller can be transferred)FalseConference names must be unique within your account at any given time. Use a unique identifier (like CallSid) in the name to prevent collisions:
conference_name = f"room-{call_sid}" # unique per call
<Gather> inside a Conference — DTMF goes into the audio mix, not a handler. Gather before joining the conference.processing_state — Must fetch by Conference SID directly.friendlyName — Compliance requirement, not just a suggestion.in_progress state.twilio-call-recordingstwilio-taskrouter-routingtwilio-call-recordingstwilio-voice-twimltwilio-voice-conversation-relay