はじめに
みなさん、こんにちは。KDDI ウェブコミュニケーションズで CPaaS のエバンジェリストをしている高橋です。
この記事では、AI Studio の着信フロー（Incoming Agent）を外部サーバーから呼び出す方法について解説をします。
本記事の対象となる読者
- Vonage の AI Studio を利用している方
- 1つの電話番号で VCR（Vonage Cloud Runtime）と AI Studio を両方使いたい方
- 外部のサーバーから、AI Studio の着信フローにリダイレクトをしたい方
なぜこの記事を書いたのか
Vonage AI Studioは、ノーコード・ローコードでコールフローが作成できるため、エンジニアでない方でも Vonage を使った発着信処理を作ることができます。
AI Studio について詳しく知りたい方は、以下の記事を参考にしてください。
Vonage の AI Studio は独立したアプリケーションとして実装されるため、通常は AI Studio のアプリケーションにリンクした電話番号を使って処理を行います。
しかし以下のような理由から、AI Studio にリンクした番号以外を使って着信フローを呼び出したいケースがあります。
- AI Studio の実行回数を制限したい（実行回数が1万回/月までが無料）
- AI Studio の着信フローを呼び出す前に条件分岐を入れたい
- 外部サーバーで着信した通話を AI Studio で処理したい
- AI Studio と InApps （ブラウザフォン）を共存させたい
これらの要件を実現するためには、AI Studio とは別のアプリケーション（App_Aとします）を作成して電話番号（電話番号_A）を取得する必要があります。
その電話番号の Answer URL で呼び出したサーバーから AI Studio アプリケーション（App_Bとします）を呼び出します。
App_B 側にも電話番号（電話番号_B）が必要ですが、こちらは主にテストをするためだけに利用しますので、日本の電話番号でなくても問題ありません。
今回は App_A を Vonage Cloud Runtime で作成します。
この記事では、図の赤い矢印部分の実装方法について説明します。
App_B の準備
App_B は 外部から呼び出される AI Studio の Incoming Agent になります。本来は、AI Studio のアプリケーションにリンクした電話番号_Bに着信したときにフローが実行されます。
AI Studio を作成したときに自動的に設定されている Answer URL（回答URL）はこのあと利用するため、控えておいてください。
通常、Answer URL は以下のような感じになっています。
https://studio-api-us.ai.vonage.com/integrations/vapi/webhooks/connect?agent_id=XXXXXXXXXXXX
今回は、AI Studio 内のフローについてはこだわりませんので、簡単なメッセージが流れるようなものでよいかと思います。
App_A の準備
今回は、VCR（Vonage Cloud Runtime）を利用します。VCR については、以下の記事などを参考にしてください。
今回は、上記ブログ内でも紹介しているStarter Projectテンプレートを使って作成したアプリケーションをベースにしています。
AI Studio を呼び出すコードは以下のとおりです。
import express, { query } from 'express';
const app = express();
const port = process.env.VCR_PORT;
app.use(express.json());
app.use(express.static('public'));
app.get('/_/health', async (req, res) => {
res.sendStatus(200);
});
app.get('/transfer', async (req, res) => {
console.log(`🐞 Received transfer request`);
console.dir(req.query);
if (req.query.from) { // PSTN経由の着信
const query_params = new URLSearchParams(req.query);
const requestOptions = {
method: 'GET',
headers: req.headers,
redirect: 'follow'
};
try {
fetch('https://studio-api-us.ai.vonage.com/integrations/vapi/webhooks/connect?agent_id=XXXXXXXXXXXX&'+query_params.toString(), requestOptions)
.then(data => data.json())
.then(json => res.json(json));
} catch (error) {
console.error(error);
}
} else {
res.json([
{
action: "talk",
text: 'こんにちは',
language: 'ja-JP',
style: 1,
loop: 3,
}
]);
}
});
app.listen(port, () => {
console.log(`App listening on port ${port}`)
});
App_A に電話番号（電話番号_A）を割り当てて、その番号に電話をかけることで AnswerURL が呼び出されます。
App_A の AnswerURL は以下のように設定します（ URL はデプロイしたときに発行されるものを利用してください）。
GET https://neru-XXXXXXXX-XXXXX-XXXXX-dev.apse1.runtime.vonage.cloud/transfer
transferエンドポイントが呼び出されたときに、 PSTN 経由の着信かどうかを判定して、PSTN 経由の場合は AI Studio を呼び出します。
ここで注意が必要なのが、AI Studio の呼び出し方法として、以下のように AI Studio アプリケーションの Answer URL を単純にリダイレクトで呼び出しても、認証エラーになってしまってうまくいかない点です。
res.status(301).redirect('https://studio-api-us.ai.vonage.com/integrations/vapi/webhooks/connect?agent_id=XXXXXXXXXXXX')
理由としては、Vonage上で設定した AnswerURL は、単純にリンクを呼んでいるのではなく、認証のための bearer トークンや、from や to などのパラメーターが設定されているためです。
そのため上記コードでは、Vonage から指定されたヘッダー情報やクエリパラメータをそのまま使って、もともと設定されていた AI Studio の AnswerURL をコール（ fetch ）して JSON（中身は NCCO）を取得しています。
そして、得られた JSONをそのまま返却することで AI Studio への接続を実現しています。
まとめ
今回は、AI Studio の着信フローを別のアプリケーションから呼び出す方法について解説をしました。
あまりニーズはないかもしれませんが、時折必要になるテクニックかと思いますので、ぜひ参考にしてください。
Discussion