# Twilio Media Streams で電話を音声 AI につなぐ：Connect・Stream・action

> Twilio の電話を音声 AI につなぐには、TwiML の Connect と Stream で通話の音声を WebSocket に流し、終わったら Connect の action で通話を自分の流れに戻します。Start との違い、Parameter の渡し方、音声の形式、止まったときの備えを説明します。

公開日: 2026-10-17
Source: https://voicast.jp/blog/twilio-media-streams-voice-ai

## 要点

- Twilio の通話を音声 AI につなぐには、TwiML の <Connect><Stream> で通話の音声を双方向の WebSocket に流します。<Start><Stream> は一方向なので、AI の声を通話に返せません。
- Stream の url にはクエリ文字列を付けられないので、テナントや鍵などの値は <Parameter> で渡します。値は WebSocket の start のメッセージで届きます。
- <Connect> に action を付けると、WebSocket が閉じたあと action の URL が呼ばれます。そこで AI の結果を見て、人への転送や切断などの次の手順を決めます。

Twilio の電話を音声 AI につなぐには、着信の Webhook で `<Connect><Stream>` を含む TwiML を返し、通話の音声を音声 AI の WebSocket に流します。AI との会話が終わって WebSocket が閉じると、Twilio は `<Connect>` の `action` の URL を呼ぶので、そこで AI の結果を見て、人に転送するか電話を切るかを決めます。電話番号と回線は Twilio のまま、会話の部分だけを AI に任せる形です。

## Connect と Start の違い

AI と会話させるなら、**`<Connect><Stream>` を使います**。Twilio の Stream には 2 つの使い方があります（[TwiML Stream](https://www.twilio.com/docs/voice/twiml/stream)）。

| | `<Start><Stream>` | `<Connect><Stream>` |
|---|---|---|
| 音声の向き | 通話 → WebSocket の一方向 | 双方向（WebSocket から通話に音声を返せる） |
| 次の TwiML | すぐに次の動詞へ進む | WebSocket が閉じるまで次へ進まない |
| 向いている用途 | 録音・文字起こし・分析 | 音声 AI との会話 |

`<Start><Stream>` は通話を聞くだけなので、AI の声を通話に返せません。`<Connect><Stream>` なら、AI の声を同じ WebSocket で通話に流せます。

## つなぐ TwiML

基本の形は次のとおりです。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect action="https://saas.example.com/twilio/after">
    <Stream url="wss://voice.example.com/ws">
      <Parameter name="tenant" value="ten_123" />
      <Parameter name="from" value="+819012345678" />
    </Stream>
  </Connect>
</Response>
```

押さえておく点は 3 つです。

1. **`url` は `wss` だけ**で、**クエリ文字列を付けられません**（[TwiML Stream](https://www.twilio.com/docs/voice/twiml/stream)）。そのため、だれの電話か・どの設定を使うかといった値は `<Parameter>` で渡します。
2. `<Parameter>` の値は、WebSocket に届く `start` のメッセージの中で受け取れます。
3. `action` を付けると、`<Connect>` が終わったときに Twilio がその URL を呼びます。付けなければ、次の動詞へ進み、無ければ会話が終わります（[TwiML Connect](https://www.twilio.com/docs/voice/twiml/connect)）。

## WebSocket で流れるもの

音声 AI の側では、Twilio から次のメッセージを受け取ります（[WebSocket messages](https://www.twilio.com/docs/voice/media-streams/websocket-messages)）。

| 向き | メッセージ | 中身 |
|---|---|---|
| Twilio → AI | `connected` | 接続ができた |
| Twilio → AI | `start` | ストリームの情報と、`<Parameter>` の値 |
| Twilio → AI | `media` | 通話の音声（base64） |
| Twilio → AI | `dtmf` | 押されたボタン |
| Twilio → AI | `mark` | AI が送った音声を流し終えた |
| Twilio → AI | `stop` | ストリームが終わった |
| AI → Twilio | `media` | 通話に流す音声 |
| AI → Twilio | `mark` | 流し終えたら知らせてほしい印 |
| AI → Twilio | `clear` | ためてある音声を捨てる（割り込まれたとき） |

音声はいつも 8,000 Hz の μ-law です。音声認識や音声合成の API が別の形式を使うなら、変換が要ります。相手が話し始めたときに AI の声を止めるには `clear` を送ります。

## action で通話を戻す

AI との会話が終わると、AI の側が WebSocket を閉じます。すると Twilio は `action` の URL を、`CallSid` などのいつもの値と一緒に呼びます。ここで返した TwiML で、通話の続きが決まります。

- AI が用件を聞き取って締めのあいさつまで済ませた → `<Hangup/>` で切る
- AI が人に引き継ぐと決めた → `<Dial>` でスタッフの電話へ転送する
- AI につながらなかった・エラーになった → いつもの流れ（スタッフの呼び出しなど）へ

`action` の受け口で AI の結果を取りに行き、その結果で分けるのが基本の形です。

## 止まったときの備え

音声 AI につながらないときも、電話を止めない作りにします。

1. AI の WebSocket の側は、鍵が違う・中で問題が起きたなどのときに**すぐ閉じる**ようにします。Twilio は `<Connect>` を終えて `action` へ進みます。
2. `action` の受け口では、**結果が取れないときを失敗として扱い**、スタッフの呼び出しに回します。
3. `action` の受け口そのものが失敗したときに備えて、Twilio の番号の設定で、Webhook の失敗のときに使う URL（Fallback URL）も決めておきます。

AI が止まっても、電話はスタッフに届く、という形にしておけば、試しに入れるときも安心です。フォールバックの設計は [音声 AI が止まっても電話を止めない](https://voicast.jp/blog/voice-ai-fallbacks) で扱います。

## voicast につなぐコード

voicast の音声の接続先は `wss://voice.voicast.jp/ws` です。`<Parameter>` で、テナント（実際に電話を受ける会社）の ID と接続キー（`vts_…`）、かけてきた番号を渡します。会話が終わったら、`action` の受け口で `GET /v1/calls/by-provider/{CallSid}` を呼び、`outcome` で次を決めます。次は Express の例です。

```ts
import express from 'express';

const app = express();
app.use(express.urlencoded({ extended: false }));

const esc = (s: string) =>
  s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]!);

// 着信: 番号からテナントを引き、voicast に音声を流す
app.post('/twilio/voice', async (req, res) => {
  const t = await findTenantByNumber(req.body.To); // 自社の DB。{ voicastTenantId, voicastSecret, staffNumber }
  res.type('text/xml').send(`<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect action="https://saas.example.com/twilio/after">
    <Stream url="wss://voice.voicast.jp/ws">
      <Parameter name="tenant" value="${esc(t.voicastTenantId)}" />
      <Parameter name="secret" value="${esc(t.voicastSecret)}" />
      <Parameter name="from" value="${esc(req.body.From ?? '')}" />
    </Stream>
  </Connect>
</Response>`);
});

// 会話のあと: 結果で次の手順を決める
app.post('/twilio/after', async (req, res) => {
  const t = await findTenantByNumber(req.body.To);
  const r = await fetch(
    `https://api.voicast.jp/v1/calls/by-provider/${encodeURIComponent(req.body.CallSid)}`,
    { headers: { Authorization: `Bearer ${process.env.VOICAST_API_KEY}` } },
  );
  const call = r.ok ? await r.json() : null;

  let twiml: string;
  if (call?.outcome === 'completed' || call?.outcome === 'answered' || call?.outcome === 'hangup') {
    twiml = '<Hangup/>';
  } else {
    // handoff・error・結果が取れないときは、スタッフへ
    twiml = `<Dial>${esc(t.staffNumber)}</Dial>`;
  }
  res.type('text/xml').send(`<?xml version="1.0" encoding="UTF-8"?><Response>${twiml}</Response>`);
});

app.listen(3000);
```

接続キーは SaaS のサーバーだけに置き、TwiML を返すときに入れます。Twilio からの Webhook は、`X-Twilio-Signature` で Twilio から届いたものかを確かめます（[Webhooks security](https://www.twilio.com/docs/usage/webhooks/webhooks-security)）。voicast は電話番号・回線を持たないので、番号の設定や転送の流れは、これまでどおり SaaS の側で決めます。全体の流れは [導入の流れ](https://voicast.jp/#how) をご覧ください。

## よくある質問

### Stream の url にテナントの ID を付けてもよいですか。

付けられません。Twilio の Stream の `url` はクエリ文字列に対応していません。テナントの ID や鍵などの値は `<Parameter>` で渡し、WebSocket の `start` のメッセージで受け取ります。

### action を付けないとどうなりますか。

`<Connect>` が終わると、TwiML の次の動詞へ進みます。次の動詞が無ければ会話が終わります。AI の結果で転送を分けたいなら、`action` を付けて受け口で結果を見る形にします。

### 音声 AI が止まっているとき、電話はどうなりますか。

AI の側の WebSocket がすぐ閉じれば、Twilio は `action` へ進みます。受け口で結果が取れないときをスタッフの呼び出しに回しておけば、電話はスタッフに届きます。
