Twilio Conference Calls

Overview

Conference 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.

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
• For agent routing: TaskRouter — see twilio-taskrouter-routing

Quickstart

Step 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, requestfrom 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's VoiceResponse builder for any dynamic content.

Python

# Called from your assignment callback or agent connect logicdef 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",    });}

Key Patterns

Warm Transfer

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

Cold Transfer

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>'    )

Hold vs Mute

# Hold — plays music to the held participantclient.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 hearclient.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.

Coaching (Supervisor Whisper)

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 hears both caller and agent
• Supervisor can speak to agent only (caller cannot hear)
• Coach audio is NOT captured in conference recording — record separately if needed
• To switch from coach to barge (speak to everyone), update the participant

Supervisor Barge

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>'    )

Participant Management

# List all participants in a conferenceparticipants = client.conferences(conference_sid).participants.list()for p in participants:    print(f"CallSid: {p.call_sid}, Muted: {p.muted}, Hold: {p.hold}")
# Remove a participantclient.conferences(conference_sid).participants(call_sid).update(status="completed")
# End the entire conferenceclient.conferences(conference_sid).update(status="completed")

Gotchas

1. Conference Requires 2+ Participants to "Exist"

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.

2. Coach Audio Not in Recording

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.

3. endConferenceOnExit Behavior

If endConferenceOnExit=True for any participant, the conference ends when they leave — dropping all other participants. Set this carefully:

• Caller: Usually False (so agents can wrap up)
• Agent: Usually False (so caller can be transferred)
• Supervisor: Always False

4. Conference Name Is Account-Scoped

Conference 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

CANNOT

• Cannot use <Gather> inside a Conference — DTMF goes into the audio mix, not a handler. Gather before joining the conference.
• Cannot rely on speaker events for app logic — Speaker events fire too frequently to be actionable in real-time routing.
• Cannot get post-flight participant data from REST API — Completed conferences return empty participant lists. Use Voice Insights for historical data.
• Coach audio is NOT in the conference recording — Supervisor whisper audio is excluded from the recorded mix. Record the supervisor's call leg separately if needed.
• Cannot filter Insights list endpoint by processing_state — Must fetch by Conference SID directly.
• Cannot use PII in friendlyName — Compliance requirement, not just a suggestion.
• Cannot create a conference with 0 call legs and get Insights data — Insights requires at least 1 participant call attempt.
• Cannot poll Insights immediately after conference end — Takes 15-30+ minutes for data to appear, even for in_progress state.
• Cannot exceed 250 participants per conference — Hard limit
• Cannot pre-add phone numbers to a conference — Participants must be active calls
• Cannot use a private URL for hold music — Hold music URL must be publicly accessible
• Cannot get per-participant recordings from conference recording — Recording is per-conference (mono mixed). Use dual-channel recording for QA — see twilio-call-recordings

Next Steps

• Route calls to agents: twilio-taskrouter-routing
• Record calls: twilio-call-recordings
• IVR before conferencing: twilio-voice-twiml
• AI agent with escalation: twilio-voice-conversation-relay