ブログ · · 約 7 分で
Twilio Media Streams で電話を音声 AI につなぐ:Connect・Stream・action
Twilio の
要点
- Twilio の
通話を 音声 AI に つなぐには、 TwiML の で 通話の 音声を 双方向の WebSocket に 流します。 は 一方向なので、 AI の 声を 通話に 返せません。 - Stream の
url には クエリ文字列を 付けられないので、 テナントや 鍵などの 値は で 渡します。 値は WebSocket の start の メッセージで 届きます。 に action を 付けると、 WebSocket が 閉じた あと action の URL が 呼ばれます。 そこで AI の 結果を 見て、 人への 転送や 切断などの 次の 手順を 決めます。
Twilio の<Connect><Stream> を<Connect> のaction の
Connect と Start の違い
AI と<Connect><Stream> を
<Start><Stream> |
<Connect><Stream> |
|
|---|---|---|
| 音声の |
通話 → WebSocket の |
双方向 |
| 次の |
すぐに |
WebSocket が |
| 向いている |
録音・文字起こし・分析 | 音声 AI との |
<Start><Stream> は<Connect><Stream> なら、
つなぐ TwiML
基本の
<?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>押さえて
urlは で、クエリ文字列をwssだけ付けられません (TwiML Stream) 。 その ため、 だれの 電話か・どの 設定を 使うかと いった 値は <Parameter>で渡します。 <Parameter>の値は、 WebSocket に 届く startのメッセージの 中で 受け取れます。 actionを付けると、 <Connect>が終わった ときに Twilio が その URL を 呼びます。 付けなければ、 次の 動詞へ 進み、 無ければ 会話が 終わります (TwiML Connect) 。
WebSocket で流れるもの
音声 AI の
| 向き | メッセージ | 中身 |
|---|---|---|
| Twilio → AI | connected |
接続が |
| Twilio → AI | start |
ストリームの<Parameter> の |
| Twilio → AI | media |
通話の |
| Twilio → AI | dtmf |
押された |
| Twilio → AI | mark |
AI が |
| Twilio → AI | stop |
ストリームが |
| AI → Twilio | media |
通話に |
| AI → Twilio | mark |
流し終えたら |
| AI → Twilio | clear |
ためてある |
音声はclear を
action で通話を戻す
AI とのaction のCallSid などの
- AI が
用件を 聞き取って 締めの あい さつまで 済ませた → <Hangup/>で切る - AI が
人に 引き継ぐと 決めた → <Dial>でスタッフの 電話へ 転送する - AI に
つながらなかった・ エラーに なった → いつもの 流れ (スタッフの 呼び出しなど) へ
action の
止まったときの備え
音声 AI に
- AI の
WebSocket の 側は、 鍵が 違う・中で 問題が 起きたなどの ときにすぐ 閉じる ようにします。Twilio は <Connect>を終えて actionへ進みます。 actionの受け口では、結果が 取れない 、ときを 失敗と して 扱い スタッフの 呼び出しに 回します。 actionの受け口 その ものが 失敗した ときに 備えて、 Twilio の 番号の 設定で、 Webhook の 失敗の ときに 使う URL (Fallback URL) も 決めて おきます。
AI が
voicast につなぐコード
voicast のwss://voice.voicast.jp/ws です。<Parameter> で、vts_…)action のGET /v1/calls/by-provider/{CallSid} をoutcome で
import express from 'express';
const app = express();
app.use(express.urlencoded({ extended: false }));
const esc = (s: string) =>
s.replace(/[&<>"']/g, (c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[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);接続キーはX-Twilio-Signature で
よくある質問
Stream の url にテナントの ID を付けてもよいですか。
付けられません。url は<Parameter> でstart の
action を付けないとどうなりますか。
<Connect> がaction を
音声 AI が止まっているとき、電話はどうなりますか。
AI のaction へ