ページの一覧

ドキュメント

電話でつなぐ

電話を voicast につなぐ手順。Twilio の Media Streams(TwiML の例)、Telnyx・Plivo・Vonage・Exotel・Genesys・Asterisk など Twilio 以外からのつなぎ方、PBX から SIP で送る方法、人への引き継ぎと転送。

Markdown で見る

電話番号と回線はサービスの側(Twilio など)が持ちます。着信の途中で <Connect><Stream> の TwiML を返すと、会話の音声が voicast の音声サーバーに届き、AI が応対します。AI が会話を終えると音声の接続が閉じ、Twilio は action の URL を呼ぶので、そこで結果を見て人への転送や切断を決めます。

着信 → サービスの TwiML(<Connect><Stream>)→ voicast の AI が応対
     → AI が会話を終える → Twilio が action を呼ぶ → 結果を見て <Dial> か <Hangup/>

TwiML#

xml
<?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 ○ テナントの ID(ten_…)
secret ○ テナントの接続シークレット(vts_…。テナントを作ったときに返るもの)
agent エージェントの ID(agt_…)。省くとテナントの既定
from かけてきた番号。会話記録の from に残り、会話中のツールで顧客を探すのに使えます

Twilio の <Parameter> は値をそのまま送るので、from などはサーバーで TwiML を作るときに入れます。

Node.js の例#

Twilio の番号の「A call comes in」に https://saas.example.com/twilio/voice を設定します。

js
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 が会話を終えると、voicast は結果(outcome)を書いてから音声の接続を閉じます。Twilio は <Connect> の action を CallSid 付きで呼ぶので、GET /v1/calls/by-provider/{CallSid} で結果を引き、次の TwiML を返します。

js
// 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 人へ転送(AI の応対が途中で切れた)
hangup 何もしない(相手はもう切っている)
time_limit 人へ転送するか、<Hangup/>(AI が締めの言葉を言って終えた)
記録が無い(404) 人へ転送(下の「断られたとき」)

引き継ぐ理由は reason に、そこまでに聞き取った項目は fields に入っています。担当者の画面に出すと、同じことを聞き直さずに済みます。Webhook の call.handoff_requested でも届きますが、届く順は保証しないので、転送の判断には action で引いた結果を使います。

断られたとき#

次のときは、音声サーバーがすぐに接続を閉じ、会話記録は作られません。Twilio は action に進むので、上の例のように人へ転送します。

  • tenant か secret が違う、テナントが止まっている(status: disabled)
  • 残高が 0 以下で、新しい会話を断っているとき(料金と請求)
  • 音声サーバーが混み合っていて、同時の会話が上限に達しているとき(エラーと制限)

始まった会話は、残高が尽きても途中で切りません。

シークレットの再発行#

POST /v1/tenants/{id}/secret で接続シークレットを再発行できます。古いシークレットも 24 時間は通るので、そのあいだにサービスの側の設定を差し替えます。

音声と動き#

  • 音声は Twilio の Media Streams(8kHz の μ-law)です。voicast が Twilio の REST で通話を切ることはありません(通話の制御はサービスの側の Twilio が持ちます)。
  • 相手が話し始めると、AI は話している途中でも止めて聞きます。
  • 相手がしばらく黙っていると聞き直し、それでも返事が無ければ hangup で終えます。
  • 会話の長さの上限(エージェント設定の max_call_minutes。既定 30 分)の少し前に、決まった締めの言葉を言って time_limit で終えます。
  • 同じ CallSid で音声の接続がつなぎ直されたとき(音声サーバーの再起動など)は、同じ会話記録を使い続けます。

クラウドの電話・CTI から#

Twilio の上に作られたクラウドの電話・コールセンターのシステム・IVR なら、AI に渡したい場面で上と同じ <Connect><Stream> を返すだけでつながります。IVR の 1 つの部品として「AI の受付」を置き、終わったら action で元の流れ(着信グループ・留守番電話など)に戻す形が扱いやすい方法です。

  • 番号ごと・時間帯ごとにテナントやエージェント(agent)を替えられます。夜間だけ AI に出てもらう、といった使い方ができます。
  • action を置けない構成では、</Connect> のあとに続けたい動詞(<Dial> など)を書きます。音声の接続が閉じると Twilio は次の動詞に進みます。
  • Twilio 以外の電話の仕組みからつなぐときは、下の「Twilio 以外から」を見てください。

Twilio 以外から#

Twilio のほかに、次の電話の仕組みから音声を WebSocket で送ってもらえます。どれも電話番号・回線・通話の制御はサービスの側が持ち、voicast からは通話を切りません(AI が会話を終えると音声の接続を閉じ、そのあとはサービスの側の流れに進みます)。

送ってくる側 接続先 テナントの渡し方
Telnyx(streaming_start・TeXML の <Stream>) wss://voice.voicast.jp/ws/telnyx custom_parameters に tenant(・agent・from)、stream_auth_token に接続シークレット
Plivo(<Stream bidirectional="true">) wss://voice.voicast.jp/ws/plivo extraHeaders に tenant=…;secret=…(英数字だけなので、ten_・vts_ の頭は省けます)
Vonage(NCCO の connect、endpoint の type は websocket) wss://voice.voicast.jp/ws/vonage endpoint の headers に tenant(・agent・from・uuid)、authorization を type: custom にして値に接続シークレット
Exotel(Voicebot アプレット) wss://voice.voicast.jp/ws/exotel?tenant=…&secret=… URL のクエリ(custom_parameters に入ります)
Genesys Cloud(Audio Connector) wss://voice.voicast.jp/ws/genesys/ + 接続の ID にテナントの ID API キーに接続シークレット(X-API-KEY)
PBX など(Twilio と同じ形) wss://voice.voicast.jp/ws 開始の start の customParameters に tenant・secret(上の Twilio と同じ)
Asterisk(20.18・22.8・23.2 以降の chan_websocket) 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 で電話を送れる PBX・クラウド PBX なら、voicast(sip.voicast.jp)に SIP で電話を送れます。電話番号と回線は PBX の側のままで、AI に渡したい着信(時間外・あふれ・代表番号など)だけを送ります。

  1. テナントに SIP の接続情報を作ります(POST /v1/tenants/{id}/sip-credentials。MCP は create_sip_credential)。username・password はこのときだけ返ります。
  2. PBX の外向きの SIP(トランク)を次のように設定し、AI に渡したい着信をそこへ送ります。
項目 値
送り先 sip.voicast.jp(UDP・TCP の 5060、TLS の 5061)
認証 Digest。ユーザー名は username(sipc_…)、パスワードは password、realm は voicast
声 G.711(μ-law・A-law)。20ms
声の暗号化 SRTP。鍵の渡し方は 2 つです。SDES(SDP の RTP/SAVP と a=crypto。鍵が SDP に載るので、TLS で送るときに使ってください)と DTLS-SRTP(SDP の UDP/TLS/RTP/SAVP と a=fingerprint(sha-256)・a=setup。鍵は声と同じ口で DTLS で交わします)。形は AES_CM_128_HMAC_SHA1_80・_32
TLS 5061。証明書は sip.voicast.jp(Let's Encrypt)。SNI を送らない機器からも受けます
登録(REGISTER) 要りません(PBX が登録してから送る設定でも受けます)
送り元の番号 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)はありません。

試すとき#

テストの環境のテナントで、Twilio の試用の番号から試せます。会話の秒数はテストの環境でも数えます。電話をかけずにエージェント設定を確かめるには、Web・アプリから話すのが手早い方法です。