🔰

kintone × AI Studio 着信ハンズオン

高橋克己（□い芸人）

2024/12/13に公開

 はじめにみなさん、こんにちは。KDDI ウェブコミュニケーションズで CPaaS のエバンジェリストをしている高橋です。

この記事では、Vonage の着信ログを kintone に記録していく手順について解説をします。

 本記事の対象となる読者Vonage を初めて触る方
Vonage AI Studio を使った着信フローを作成してみたい方
kintone をある程度使いこなしている方
kintone の VCall プラグインを利用していて、かつ着信フローも作成したい方

 Vonage とは
Vonage は、米国ニュージャージー州に本社を置く、CPaaS（Communication Platform as a Service）企業です。

もともとは VoIP（Voice over IP）企業としてスタートしましたが、いくつかの企業買収を行うことで、コミュニケーションサービス全般をサポートすることができる企業に発展しました。現在はスウェーデンの大手通信機器会社エリクソンの傘下に入っています。
2024年2月14日より、株式会社KDDIウェブコミュニケーションズ（以後、KWC）が Vonage の再販事業を開始することとなりました。

KWC経由でアカウントを開設する場合、Vonageで直接開設したアカウントとは一部仕様が異なります。（※提供する機能面において違いはありません）

 Vonage AI Studio とはVonage AI Studio （以下、AI Studio）は、ノーコード・ローコードでコールフローを作成できるツールで、ブラウザ上で動作します。
上の図のように、ノードと呼ばれる部品をドラッグ・アンド・ドロップして接続するだけで、簡単にコールフローが作成できます。
!Vonage AI Studio自体はすでに正式リリース（GA: General Availability）となっていますが、一部の機能についてはベータリリース、もしくはアルファリリースのものが含まれます。日本語のサポートは2024年12月現在、アルファリリースとなります。

 用語定義

用語
説明


エージェント
AI Studioでフローを作成する最も大きな単位です。エージェント単位で言語や話者、リージョンやタイムゾーンの設定を行います。スタンダードプランでは、最大10個のエージェントが作成できます。

イベント
フローが起動するトリガーです。イベントには、Inbound call / Outbound call / End call / API Eventの4つがあります。

ノード
フローを構成する各部品のことです。ノードは、Conversation / Advanced / Actions / Integrations / Flow Control の5つのカテゴリーに分類されます。

プロパティ
いくつかのノードにはプロパティと呼ばれる要素が含まれます。たとえば、自然言語解析におけるエンティティやインテントや、フロー内で共有する変数などがプロパティになります。


 シナリオ本記事では、以下のシナリオでコールフローを作成していきます。
電話がかかってきたら、kintone の着信ログアプリに新しいレコードを追加します。
電話番号で kintone の顧客リストアプリを検索します。
該当する顧客が見つかった場合は、顧客の名前を読み上げます。
具体的な用件を聞きます。
用件をさきほど作成した kintone のレコードに書き込みます。
担当者に着信があった旨をメールで伝えます。

 準備このシナリオをAI Studioで作成するためには、あらかじめ以下の準備が必要になります。
Vonage アカウント（ハンズオン用のアカウントはこちらから取得が可能です。本番環境でご利用いただく場合は、こちらの手順でアカウントを開設してください。）
kintone アカウント（こちらから開発者ライセンスが取得可能です。）
ブラウザ（Chrome推奨）
通話が可能な携帯電話 or スマートフォン
Vonage クーポンコード（トライアルアカウントで電話番号を購入する際に必要です）

 kintone アプリの準備ハンズオンで使うアプリテンプレートを準備してありますので、事前にダウンロードをしてください。
!今回は kintone をある程度使いこなせる方を想定しておりますので、説明は最低限にしてあります。

 ハンズオン用のスペースを作成（任意）今回のハンズオン用にスペースを作成してください。スペース名は何でもよいです。


 アプリを作成今回のハンズオンで利用するアプリを、さきほどダウンロードしたテンプレートから作成します。

 顧客リストに登録顧客リストアプリを開いて、ご自分の情報を登録します。
必要な項目を入力してください。TELと会社名、担当者名（よみ）はこのあと利用しますので、必ず入力してください。

 Vonage の設定ではここから、Vonage 側の設定を行っていきます。

 AI Studioの起動Vonage APIコンソールにログインします。
左側からAI Studioを選択し、さらに右側に表示されるAI Studioにアクセスするボタンを押します。


!AI Studioは独立したサービスになっているため、再度ログインが必要になる場合があります。

 新しいエージェントの作成

Create Agentボタンを押します。
Agent Typeの中からTelephonyを選択し、Nextボタンを押します。
エージェントの基本情報を登録していきます。

Regionは、「United States」を選択します。現在選択できるのは、「United States」か「Europe」の2つのみとなります。

Agent Nameには、任意の名前を指定します。今回は「kintone incoming agent」としました。

Languageは、「Japanese」を選択します。2024年12月現在、日本語はアルファリリースとなります。

Voicesでは、話者を選択します。日本語は13種類から選択できます。Premiumと書かれた話者は別料金（€0.0027/100文字）が必要です。それ以外は AI Studio の料金プランに含まれます。

Time Zoneは、「Asia/Tokyo」を選択します。
上記設定が完了したら、Nextボタンを押します。
!一度作成すると、RegionとLanguageは作成後の変更ができません。ご注意ください。

Start from Scratchを選択し、Nextボタンを押します。
イベントの種類を選択します。

イベントとは、どのような状況でフローを実行するかの指定で、以下の4種類があります。


イベント種別
説明


Inbound Call
ユーザーからの着信時に実行されます。

Outbound Call
ユーザーへの発信で、ユーザーが応答した時に実行されます。

End Call
通話が終了したときに実行されます。

API Event
外部からのAPI経由で実行されます。

今回は着信時のフローを作成するので、Inbound Callを選択します。

Createボタンを押します。
上記のようなフロー作成画面が表示されればエージェントの作成は完了です。

 フローの作成ではいよいよシナリオに従ってフローを作成していきましょう。

 ユーザーパラメーターの追加フローを作成する前に、一連のフローの中で扱う変数を格納するパラメーターを作成しておきます。
左側のPropertiesアイコンをクリックします。
さらにParametersを選択します。
右側にウィンドウが開くので、Add user parameterをクリックします。
以下の5つの変数を追加してください。スペルミスを防止するため、変数名はカット・アンド・ペーストで作成するとよいでしょう。


Name


CUSTOMER_NUMBER

RECORD_ID

CUSTOMER_NAME_KANA

CUSTOMER_COMPANY_NAME

REQUIREMENT


Go Backボタンを押して、さらにCloseボタンでウィンドウを閉じます。

 電話番号を変換Vonage はグローバルなサービスなので、電話番号はすべて先頭に国番号が付加された MSISDN 形式になっています。

そのため、日本の電話番号形式（0ABJ形式）に変換しておく必要があります。
電話番号の変換を行うために、Custom Codeノードを利用します。
!Custom Codeを使うことで、フローの途中で JavaScript を実行することができます。
左側のNODESアイコンを選択します。
さらにNODESメニューからCustom Codeノードをドラッグ・アンド・ドロップします。
ドロップしたノードのClick here to edit部分をクリックすると、プロパティウィンドウが開きます。
プロパティウィンドウの上部で、ノードの名前を指定します。今回は、「電話番号形式の変換」とします。
以下のコードをコード欄に貼り付けます。
var phoneVal = $CALLER_PHONE_NUMBER;
phoneVal = "0" + phoneVal.slice(2);
return phoneVal;
!変数（$CALLER_PHONE_NUMBER）の貼り付けがうまくいかないことがあります。

その場合は一度変数を削除し、$を押して変数をリストから選択してください。
このコードは、発信者番号（$CALLER_PHONE_NUMBER）の先頭2文字（国番号の81）を0に変換します。

Output Parameterのプルダウンリストから、さきほど作成したユーザーパラメータ「$USER.CUSTOMER_NUMBER」を選択します。

Save & Exitボタンを押して、設定を保存します。

STARTノードの右側にある◯印から今作成したノードの左側まで線を伸ばして接続します。

 着信ログアプリに新しいレコードを追加つぎに、着信があったら kintone に新しいレコードを追加します。

書き込みは、kintone の RestAPI を利用します。

API をコールするためには、事前に以下の kintone 情報を取得しておく必要があります。
着信ログアプリのアプリID（URL の xxxxx.cybozu.com/k/NN の NN の部分）
適切な権限を設定した API トークン
書き込みをするフィールドコード
さきほど追加した 着信ログアプリを開き、設定ボタン（歯車アイコン）を押します。

APIトークンをクリックします。

生成するボタンを押します。
アクセス権で、「レコード閲覧」、「レコード追加」、「レコード編集」にチェックを入れます。
生成された API トークンをメモ帳などに保存します。

保存ボタンを押します。

アプリを更新ボタンを押します。
ダイアログが表示されますので、アプリを更新ボタンを押します。
利用するフィールドも確認しておきましょう。

今回書き込みをする際に必要となるフィールドは、以下のとおりです。


フィールド名
フィールドコード
説明


着信番号
TEL
顧客の電話番号

用件
detail
電話の用件

ではこれらの情報を使って、着信ログアプリにレコードを追加しましょう。

Webhookノードをドラッグ・アンド・ドロップします。
さきほどのノードの上の項目と接続します。

Click here to editをクリックします。
ノードの名前は「着信ログを追加」にします。

Methodは「POST」を選択します。

Request URL欄には、API のエンドポイント（https://xxxxx.cybozu.com/k/v1/record.json）

xxxxxの部分はご自分の環境に合わせてください。

Headersタブが選択されていることを確認します。

HTTP Headerに「X-Cybozu-API-Token」、Valueにさきほど生成した API トークンを指定します。

Bodyタブに移動します。
ボディパラメーターに以下の JSON を貼り付けます。
{
  "app": NN,
  "record": {
    "TEL": {
        "value": "$USER.CUSTOMER_NUMBER"
    },
    "detail": {
        "value": ""
    } 
  }
}
app の右側のNNには、ご自分の着信ログのアプリIDを指定してください。
プロパティウィンドウを下の方にスクロールして、Response Mappingを表示します。

Object pathに「id」、Parameterに「$USER.RECORD_ID」を指定します。
!Request Mappingは、戻ってきた値をパラメーターにマッピングするためのものです。

今回の API が正常に実行されると、以下のような JSON が戻ってくるので、その id フィールドを RECORD_ID パラメーターに格納しています。
{
  "id": "1",
  "revision": "1"
}

Save & Exitボタンを押します。

 kintone の顧客リストを検索つぎに、電話番号をキーにして kintone の顧客アプリから顧客情報を取得します。

さきほどと同じように、kintone の RestAPI を使いますので、以下の情報を事前に確認、設定しておく必要があります。
顧客リストアプリのアプリ ID（URL の xxxxx.cybozu.com/k/NN の NN の部分）
顧客リストアプリの API トークン（さきほどの手順と同じように生成してください。今回はレコード閲覧権限のみあれば OK です）
取得フィールドのフィールドコード（以下のフィールドを利用します）


フィールド名
フィールドコード
説明


担当者名（よみ）
Yomi
担当者名のよみ

会社名
CompanyName
顧客の会社名

ではこれらの情報を使って、顧客リストアプリから顧客情報を取得してみましょう。

Webhookノードをドラッグ・アンド・ドロップします。
さきほどのノードの上の項目と接続します。

Click here to editをクリックします。
ノードの名前は「顧客名の取得」にします。

Methodは「GET」を選択します。

Request URL欄には、API のエンドポイント（https://xxxxx.cybozu.com/k/v1/records.json）

xxxxxの部分はご自分の環境に合わせてください。最後はrecords.jsonになりますので注意してください。

Headersタブが選択されていることを確認します。

HTTP Headerに「X-Cybozu-API-Token」、Valueにさきほど取得しておいた API トークンを指定します。

Bodyタブを開きます。
ボディパラメーターに以下の JSON を指定します。
{
  "app": NN,
  "query": "TEL= \"$USER.CUSTOMER_NUMBER\""
}
NNには、顧客リストアプリのアプリIDと入れます。
!kintone の RestAPI ではクエリーパラメーターも利用できますが、Webhook ノードから呼び出すときはうまくいかないことがあるため、ボディパラメーターを利用することをおすすめします。

Response Mappingまでスクロールします。

Object pathに「records[0].Yomi.value」、Parameterに「$USER.CUSTOMER_NAME_KANA」を指定します。

Object pathに「records[0].CompanyName.value」、Parameterに「$USER.CUSTOMER_COMPANY_NAME」を指定します。

Save & Exitボタンを押します。
!もし該当するレコードがない場合、API コールのレスポンスは 404 になりますので、後続のノードで判定することができます。

 顧客の名前を読み上げでは次は、今取得した担当者名（CUSTOMER_NAME_KANA）を入れた応答メッセージを再生します。

もし、該当するレコードが取得できていない場合は、担当者名はない応答メッセージを再生します。

Speakノードを2つ、ドラッグ・アンド・ドロップします。
さきほどのノードの上の項目と下の項目をそれぞれのSpeakノードに接続します。
上の項目と接続したノードのClick here to editをクリックします。
ノードの名前は「顧客名ありガイダンス」にします。

Agent saysに「$USER.CUSTOMER_NAME_KANA さま、お電話ありがとうございます。本日はどのようなご用件でしょうか？」と入力します。

Enterを押します。
!パラメーターを入力するときは、最初に$を入力するとリストから選択することができます。

Save & Exitボタンを押します。
もう1つのSpeakノードも設定していきましょう。

Click here to editをクリックします。
ノードの名前は「顧客名なしガイダンス」にします。

Agent saysに「お電話ありがとうございます。本日はどのようなご用件でしょうか？」と入力します。

Enterを押します。

Save & Exitボタンを押します。

 用件を聞くではつぎに、用件を聞くノードを作成していきましょう。

Collect Inputノードを使うことで、音声で受け付けた文章を文字に変換することができます。

Collect Inputノードをドラッグ・アンド・ドロップします。
さきほどの「顧客名ありガイダンス」ノードと「顧客名なしガイダンス」ノードを、今ドロップしたノードとそれぞれ接続します。

Click here to editをクリックします。
ノードの名前は「用件を聞く」にします。

Parameterのプルダウンリストから「USER.REQUIREMENT」を選択します。

Promptsに「具体的に用件をお話ください。」と入力して、Enterを押します。

Retry Promptsに「すみませんが、うまく聞き取れませんでした。用件を具体的にお話ください。」と入力して、Enterを押します。

Save & Exitボタンを押します。
ここで発話された内容は音声認識されて、USER.REQUIREMENTパラメーターに格納されます。

 kintone レコードを更新取得した用件を kintone の着信ログに書き込みます。

kintone のレコード更新 RestAPI を利用します。

Webhookノードをドラッグ・アンド・ドロップします。
ドラッグしたノードとさきほどのノードの一番上の◯印と接続します。

Click here to editをクリックします。
ノードの名前は「着信ログを更新」にします。

Methodは「PUT」を選択します。

Request URL欄には、API のエンドポイント（https://xxxxx.cybozu.com/k/v1/record.json）

xxxxxの部分はご自分の環境に合わせてください。

Headersタブが選択されていることを確認します。

HTTP Headerに「X-Cybozu-API-Token」、Valueに着信ログアプリの API トークンを指定します。

Bodyタブに移動します。
ボディパラメーターに、以下の JSON を指定します。
{
  "app": NN,
  "id": $USER.RECORD_ID,
  "record": {
    "detail": {
        "value": "$USER.REQUIREMENT"
    },
    "companyName": {
      "value": "$USER.CUSTOMER_COMPANY_NAME"
    }
  }
}
app の右側のNNには、ご自分の着信ログのアプリIDを指定してください。

Save & Exitボタンを押します。

 担当者にメール用件を受け付けたことを顧客に通知し、担当者にはメールで着信があったことを知らせます。

Speakノードをドラッグ・アンド・ドロップします。
さきほどのノードの上の項目と接続します。

Click here to editをクリックします。
ノードの名前は「折り返しガイダンス」にします。

Agent saysに、「ありがとうございます。追って担当者より折り返しのお電話をいたします。」と入力し、Enterを押します。

Save & Exitボタンを押します。
つぎに担当者にメールをしますが、その前に担当者のメールアドレスを登録しておく必要があります。
左側のPROPERTIESからContactsメニューを選択します。

Create Contactボタンを押します。
画面上部にコンタクト名（メールを送信したい担当者名）を入力します。

Phone Numberに、担当者の電話番号を入力します（E.164形式）。

Email欄に、担当者のメールアドレスを入力します。

Save & Exitボタンを押します。

Closeボタンを押します。
!E.164形式とは、電話番号の先頭に+をつけた国番号を付与した形式です。

日本の電話番号の場合は、先頭の0を削除して、国番号（+81）を付与します。

例：090XXXXYYYY → +8190XXXXYYYY
では、メールを送信するノードを作成していきます。
左側のNODESメニューからSend Emailノードをドラッグ・アンド・ドロップします。
さきほどのノードと接続をします。

Click here to editをクリックします。
ノードの名前は「担当者にメール」にします。

To欄で「@」を入力すると、さきほど登録したContactがリスト表示されるので、そちらを選択します。

Subject欄には、「着信がありました」と入力します。

Body欄には、以下の内容を登録しておきます。文中のパラメーターについては、「$」を押すことで選択が可能です。
以下の着信がありました。
-----
着信日時：$CALL_START_DATE $CALL_START_TIME
$USER.CUSTOMER_COMPANY_NAME
用件: $USER.REQUIREMENT
-----
必要に応じてご対応をお願いいたします。

Save & Exitボタンを押します。

 通話を終了する最後に通話を切断します。

End Callノードをドラッグ・アンド・ドロップします。
さきほどのノードと接続します。
ノードの名前は「通話終了」にします。

 テスト以上でコールフローはすべて完成ですので、テストをしていきましょう。

 電話番号の購入ここからの手順を行うために、電話番号を購入していきます。電話番号を購入するためには、以下のいずれかの条件が必要です。
アカウントをアップグレードしている
クーポンコードを適用している
!クーポンコードの適用方法については、こちらの記事をご覧ください。
Vonage APIコンソールにログインします（AI Studioではありません）。
左側の番号メニューを展開し、番号を購入を選択します。

国のリストから「United States(+1)」を選択します。

機能のリストを開き、「SMS」と「Voice」をチェックします。

Searchボタンを押すと、購入できるリストが一覧表示されます。
購入したい番号をリストから選択し、購入ボタンを押します。
!日本の番号は本人性確認（KYC）が完了した法人、もしくは個人事業主のみ購入が可能です。
確認ウィンドウが開くので、購入ボタンを押します。
画面上部に購入完了のメッセージが表示されれば、無事に番号が購入できています。
!米国番号に対してSMSを送信するためには、このウィンドウに記載があるようにブランドとキャンペーンの登録が別途必要です。日本国内へのSMS送信については登録は不要です。

 電話番号をAI Studioに紐付けるではつぎに、今購入した電話番号を現在作成中のエージェントに紐付けます。
AI Studioのコンソールに入ります。
左上のハンバーガーメニューから、Phone Settingsを選択します。
さきほど購入した番号をリストから選択します。

Assign Numberボタンを押します。
電話番号が紐付けられたことを通知するダイアログが表示されます。

Closeボタンを押してウィンドウを閉じます。

 実際の電話機を使ったテストでは最後に電話機を使ってテストをしてみましょう。

ただし、現在はUS番号しか購入していないので、皆さんからの携帯からかけるのではなく、AI Studioから皆さんの電話に発信して、一連のフローをテストしていきます。
画面上部のTesterボタンを押します。

Start phone callボタンを押します。
国の選択リストから「Japan（+81）」を選択します。
電話番号欄には、ご自分の電話番号の先頭の0を外したものを設定します。

Callボタンを押します。
自分の電話機にUS番号から着信がかかりますので、一連のフローをテストしてください。

kintone にレコードが追加されていることや、メールが届くことも合わせて確認しておきましょう。

 デバッグもしうまく動作しない場合は、画面上部のReportsからログを確認することができます。
最新のデータが一番上にリストされます。電話番号のリンクを押すと、詳細なログが確認できます。
!もしリストに最新のログが表示されない場合は、右側のDate & Timeで昨日と今日を範囲指定しなおすと、ログが表示されます。

 まとめ今回は、Vonage の AI Studio を使って、kintone に着信ログを記録するアプリケーションを作成してみました。

AI Studio には、これ以外にもたくさんの機能があるので、ぜひいろいろ試してみてください。
最後にAI Studioの料金についても説明をしておきます。料金ページはこちらです。
スタンダードプランは無料で利用が可能ですが、月に10,000セッション（フローの実行）までという制限があります。また、スタンダードプランでも一部の機能はオプション料金が必要になります。

用語	説明
エージェント	AI Studioでフローを作成する最も大きな単位です。エージェント単位で言語や話者、リージョンやタイムゾーンの設定を行います。スタンダードプランでは、最大10個のエージェントが作成できます。
イベント	フローが起動するトリガーです。イベントには、Inbound call / Outbound call / End call / API Eventの4つがあります。
ノード	フローを構成する各部品のことです。ノードは、Conversation / Advanced / Actions / Integrations / Flow Control の5つのカテゴリーに分類されます。
プロパティ	いくつかのノードにはプロパティと呼ばれる要素が含まれます。たとえば、自然言語解析におけるエンティティやインテントや、フロー内で共有する変数などがプロパティになります。

イベント種別	説明
Inbound Call	ユーザーからの着信時に実行されます。
Outbound Call	ユーザーへの発信で、ユーザーが応答した時に実行されます。
End Call	通話が終了したときに実行されます。
API Event	外部からのAPI経由で実行されます。