電話でつなぐ
電話を
電話番号と<Connect><Stream> のaction の
着信 → サービスの TwiML(<Connect><Stream>)→ voicast の AI が応対
→ AI が会話を終える → Twilio が action を呼ぶ → 結果を見て <Dial> か <Hangup/>TwiML#
<?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="ten_…" />
<Parameter name="secret" value="vts_…" />
<Parameter name="from" value="+819012345678" />
</Stream>
</Connect>
</Response>| Parameter | 必須 | 内容 |
|---|---|---|
tenant |
○ | テナントのten_…) |
secret |
○ | テナントのvts_…。 |
agent |
エージェントのagt_…) |
|
from |
かけてきたfrom に |
Twilio の<Parameter> はfrom などは
Node.js の例#
Twilio のhttps://saas.example.com/twilio/voice を
import express from 'express';
const app = express();
app.use(express.urlencoded({ extended: false }));
const xml = (s) => String(s).replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`);
// 着信: かかってきた番号(To)から、自社の顧客と voicast のテナントを引く
app.post('/twilio/voice', async (req, res) => {
const t = await findTenantByNumber(req.body.To); // { voicastTenantId, voicastSecret }
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="${xml(t.voicastTenantId)}" />
<Parameter name="secret" value="${xml(t.voicastSecret)}" />
<Parameter name="from" value="${xml(req.body.From)}" />
</Stream>
</Connect>
</Response>`);
});引き継ぎ#
AI がoutcome)<Connect> のaction をCallSid 付きでGET /v1/calls/by-provider/{CallSid} で
// AI の応対のあと: 結果を見て、人に転送するか切る
app.post('/twilio/after', async (req, res) => {
const r = await fetch(`https://api.voicast.jp/v1/calls/by-provider/${req.body.CallSid}`, {
headers: { Authorization: `Bearer ${process.env.VOICAST_API_KEY}` },
});
const call = r.ok ? await r.json() : null;
// 記録が無い(つながらなかった)・引き継ぎ・途中の障害は、人につなぐ
const toHuman = !call || call.outcome === 'handoff' || call.outcome === 'error';
res.type('text/xml').send(
toHuman
? '<Response><Say language="ja-JP">担当者におつなぎします。</Say><Dial>+81312345678</Dial></Response>'
: '<Response><Hangup/></Response>',
);
});outcome |
次の |
|---|---|
handoff |
担当者・<Dial> |
completed・answered |
<Hangup/>fields と |
error |
人へ |
hangup |
何もしない |
time_limit |
人へ<Hangup/> |
| 記録が |
人へ |
引き継ぐreason に、fields にcall.handoff_requested でもaction で
断られたとき#
次のaction に
tenantかsecretが違う、 テナントが 止まっている ( status: disabled)- 残高が
0 以下で、 新しい 会話を 断っている とき (料金と 請求 ) - 音声サーバーが
混み合っていて、 同時の 会話が 上限に 達している とき (エラーと 制限 )
始まった
シークレットの再発行#
POST /v1/tenants/{id}/secret で
音声と動き#
- 音声は
Twilio の Media Streams (8kHz の μ-law) です。 voicast が Twilio の REST で 通話を 切る ことは ありません (通話の 制御は サービスの 側の Twilio が 持ちます) 。 - 相手が
話し始めると、 AI は 話している 途中でも 止めて 聞きます。 - 相手が
しばらく 黙っていると 聞き直し、 それでも 返事が 無ければ hangupで終えます。 - 会話の
長さの 上限 (エージェント設定の max_call_minutes。既定 30 分) の 少し 前に、 決まった 締めの 言葉を 言って time_limitで終えます。 - 同じ
CallSidで音声の 接続が つなぎ直された とき (音声サーバーの 再起動など) は、 同じ 会話記録を 使い続けます。
クラウドの電話・CTI から#
Twilio の<Connect><Stream> をaction で
- 番号ごと
・時間帯ごとに テナントや エージェント ( agent)を 替えられます。 夜間だけ AI に 出て もらう、 と いった 使い方が できます。 actionを置けない 構成では、 </Connect>のあとに 続けたい 動詞 ( <Dial>など)を 書きます。 音声の 接続が 閉じると Twilio は 次の 動詞に 進みます。 - Twilio 以外の
電話の 仕組みから つなぐ ときは、 下の 「Twilio 以外から」 を 見てください。
Twilio 以外から#
Twilio の
| 送ってくる |
接続先 | テナントの |
|---|---|---|
Telnyxstreaming_start・TeXML の<Stream>) |
wss://voice.voicast.jp/ws/telnyx |
custom_parameters にtenantagent・from)stream_auth_token に |
Plivo<Stream bidirectional="true">) |
wss://voice.voicast.jp/ws/plivo |
extraHeaders にtenant=…;secret=…ten_・vts_ の |
Vonageconnect、type はwebsocket) |
wss://voice.voicast.jp/ws/vonage |
endpoint のheaders にtenantagent・from・uuid)authorization をtype: custom に |
| Exotel |
wss://voice.voicast.jp/ws/exotel?tenant=…&secret=… |
URL のcustom_parameters に |
| Genesys Cloud |
wss://voice.voicast.jp/ws/genesys/ + 接続の |
API キーにX-API-KEY) |
| PBX など |
wss://voice.voicast.jp/ws |
開始のstart のcustomParameters にtenant・secret |
| Asterisk |
wss://voice.voicast.jp/ws/asterisk |
Dial(WebSocket/<接続>/c(ulaw)f(json)v(tenant=…,secret=…)) |
- どの
相手でも、 上の 渡し方の かわりに URL の クエリ ( ?tenant=…&secret=…&agent=…&from=…)でも 渡せます。 両方あれば 相手ごとの 渡し方を 使います。 - 音声の
形は 相手ごとの 決まりの まま 受けます (Telnyx・Plivo は 8kHz の μ-law、 Vonage は 16kHz の L16、 Exotel は 8kHz の PCM、 Genesys は 8kHz の μ-law、 Asterisk は c(ulaw))。 - 相手が
黙っている 間も、 無音の 音声を 流し続けてください。 音声が 止まると、 話し終えたかを 判定できません。 ふつうの 電話の 通話では 流れ続けます。 - Plivo は
keepCallAlive="true"にすると、 接続が 閉じた あと 次の XML に 進みます。 - 発信
(AI から 電話を かける こと) は しません。 こちらから サービスの 回線に 登録しに 行く 形 (SIP の REGISTER) も ありません。 PBX から SIP で 送る ときは、 下の 「SIP で」 を 見てください。
SIP で(PBX・クラウド PBX から)#
外へsip.voicast.jp)
- テナントに
SIP の 接続情報を 作ります ( POST /v1/tenants/{id}/sip-credentials。MCP は create_sip_credential)。 username・passwordはこの ときだけ返ります。 - PBX の
外向きの SIP (トランク) を 次のように 設定し、 AI に 渡したい 着信を そこへ 送ります。
| 項目 | 値 |
|---|---|
| 送り先 | sip.voicast.jp |
| 認証 | Digest。usernamesipc_…)password、voicast |
| 声 | G.711 |
| 声の |
SRTP。RTP/SAVP とa=crypto。UDP/TLS/RTP/SAVP とa=fingerprinta=setup。AES_CM_128_HMAC_SHA1_80・_32 |
| TLS | 5061。sip.voicast.jp |
| 登録 |
要りません |
| 送り元の |
From の |
- 接続情報ごとに
エージェントを 決められます ( agent_id)。 省くと テナントの エージェントで 受けます。 - 接続情報に
転送先 ( transfer_to。内線番号か SIP の URI) を 入れると、 AI が 担当者に 渡すとき ( outcome: handoff)に、 締めの 言葉を 言い 終えてから PBX に REFERを送り、 PBX が その 宛先に 転送します。 転送先が 無い・PBX が 転送できなかった ときは BYEで切ります。 - 混み合っている
ときは 486 Busy Here、テナントが 止まっている ・残高が 無いときは 403 Forbiddenを返します。 PBX の 側で 次の 宛先 (担当者・留守番電話など) に 回してください。 - 認証の
失敗が 短い 時間に 続いた 送り元からは、 しばらく 受け付けません (返事を しません) 。 パスワードを 直しても 通らない ときは、 少し 時間を おいてから 試してください。 - AI が
会話を 終えると、 締めの 言葉を 言い 終えてから voicast が BYEで切ります (転送する ときは 上の とおり REFER)。 - 声は
相手が 黙っている 間も 流し続けてください (ふつうの 通話では 流れ続けます) 。 - voicast から
サービスの 回線に 登録しに 行く 形 (SIP の REGISTER) は ありません。
試すとき#
テストの