X Openai Twilio Conference Calls 4e242fe

---
name: x-openai-twilio-conference-calls-4e242fe
description: Build multi-party calls using Twilio Conference. Covers warm transfer, cold transfer, coaching (whisper), hold vs mute, participant modes, and supervisor barge. Use this skill for any contact center, support line, or scenario requiring transfers, holds, or multi-party calls.
---

### 导出副本边界与技能别名

迁移、安装、修复和经验回写只作用于当前加载的目标宿主技能副本。原 Codex 技能/MCP、下载的源码和 `original-skills` 均为来源材料，不因执行本副本而写入；只有用户另行明确要求配置 Codex 产品本身时，才按该产品流程处理指定目标。脚本需要安装目录或状态目录时，显式提供目标路径；不得从 `CODEX_HOME` 隐式推断写入位置。

跨技能名称可能沿用源库别名。先查 [技能别名表](../../skill-aliases.json)，优先选择同来源、同插件的条目，再使用其 `id` 调用或读取对应入口；不得假定旧 `$skill`、`superpowers:skill` 名称在新宿主直接注册。不能确定目标时先核对，不替换真实产品命令或 Shell 环境变量。

## 跨宿主使用约定

本副本供支持 Agent Skills 的客户端使用。先检查当前宿主实际提供的工具、权限和已连接服务，再执行正文工作流。原文中的宿主工具标识是能力参考；只有实际发现该工具时才可调用，其他宿主应使用经核验的等价 MCP、CLI 或 API。没有等价能力的步骤必须报告不可用，不能虚构调用或完成状态。

技能资源以本技能目录为基准；输出写入当前项目中用户指定的位置。通过技能名称或自然语言触发，具体快捷命令由宿主决定。涉及真实产品、模型 API、协议字段和官方网址的名称保持原意。授权、审批、隐私和工具范围限制在迁移后仍然有效；不得为兼容而扩大权限。具体依赖与迁移说明见同目录 `PORTABILITY.md`。

## 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)**
```python
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)**
```node
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**
```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**
```node
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**
```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**
```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

| 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` |

```python
# 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.

### Coaching (Supervisor Whisper)

Supervisor joins the Conference and can speak to the agent only — the caller cannot hear the supervisor.

**Python**
```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**
```node
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.

```python
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

```python
# 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")
```

---

## 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:
```python
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`