🔰

AI Studioで作成した発信(Outbound Call)エージェントをcURLで実行する

KWC sutou

2025/03/06に公開

Vonage

tech

 はじめにcURLコマンドを使って、サーバやPCからAI Studioで作成したOutbound Callのエージェントを実行するURLとその基本的な使い方についてまとめました。


基本的な使い方に加え、cURLコマンド実行時にAI Studioへ渡した値をSMSで送信させてみました。


サーバ側のCronや監視ツールなどからcURLを実行することで通知先、通知内容をパターンごとに分けた架電、SMS送信ができるようになります。


これにより、特定の閾値を超えた場合や異常を検出した際などの関係各所への連絡、通知の効率化、自動化が図れます。


電話番号取得についてはこちらを参考にしてください。

 前提条件Vonageの電話番号が取得済みであること
発着信可能な電話番号があること(携帯電話など)
インターネットに接続されたcURLコマンド実行環境があること

 AI Studioの起動Vonageダッシュボードへログインし左メニューからAI Studioを選択

右上のCreate Agentを選択
Telephonyを選択しNext
Fill in Detailsへ詳細情報を入力する




Region は United States を選択でOK
Choose Template で Start from Scratchを選択しNext
Select Event で Outbound call を選択しCreate

以下のような画面が表示されAI Studioの利用準備が完了


 作成したAgentへ準備したVonage電話番号を割り当てる画面左側上部にある受話器のマークを選択し Phone Settingsを選択

Assign Phone Number →購入済の着信に利用する電話番号→Assign Numberの順に選択

Phone Settings のAgent phone number に選択した電話番号が表示されていれば設定完了


 AI Studioで自動音声のみのフローを作成して動作確認左側のNODESメニュー内のConversationからSpeakノードを右側へドラッグ＆ドロップ

ドラッグ＆ドロップしたSpeakノードのClick here to edit部分をクリックするとプロパティウィンドウが開きます。


Agent Saysのテキストボックスへ自動音声で流す音声の文章を入力しEnterを押下すると以下のような画面になります。





入力したテキストの右側に三角マークの再生ボタンがあるので意図した内容になっているか再生してチェックしてください。


意図したものになっていればSave&Exitを選択し保存
Speakノードのみだと音声再生後にそのまま通話状態が続いてしまうためNODESのActionsからEnd Callをドラッグ＆ドロップしSTARTノードとSpeakノードとEnd Callノードを接続しPublishを選択


 cURLで呼び出すための情報収集左上のIDの部分がAgent IDとなるためコピーして保存しておく


右上のユーザアイコンからGenerate API Key を押下すると右下へ作成されたAPI Keyが表示されるのでコピーして保存しておく



すでに一度作成したことがある場合は以下のような注意が表示される。以前保存したAPI Keyがあればそれを利用してください。忘れてしまったなどで上書きしてしまってもいい場合はRegenerate Keyを選択してください。


 cURLコマンドを実行してみるまずはcURLがインストールされているか確認

Macの場合、ターミナルを開き以下を実行
curl -V

実行結果
curl 8.7.1 (x86_64-apple-darwin24.0) libcurl/8.7.1 (SecureTransport) LibreSSL/3.3.6 zlib/1.2.12 nghttp2/1.63.0
Release-Date: 2024-03-27
Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS GSS-API HSTS HTTP2 HTTPS-proxy IPv6 Kerberos Largefile libz MultiSSL NTLM SPNEGO SSL threadsafe UnixSockets
インストールされていれば以下コマンドを実行する
X-Vgai-Key: の後ろへ上記でコピーしたAPI KEYを貼り付け
agent_idの””の中に上記でコピーしたAgent IDを貼り付け
"to": の””の中に発信先の電話番号を指定する。

番号フォーマットは81を先頭につけて、その後先頭の0を取った番号で記入。


(例:090-YYYY-XXXX の場合 8190YYYYXXXX)
curl --location --request POST 'https://studio-api-us.ai.vonage.com/telephony/make-call' \
--header 'X-Vgai-Key: コピーしたAPI Keyを貼り付け' \
--header 'Content-Type: application/json' \
--data-raw '{
"agent_id": "コピーしたAgent IDを貼り付け",
"to": "8190YYYYXXXX"
}'
実行例(ターミナルで以下を実行)
curl --location --request POST 'https://studio-api-us.ai.vonage.com/telephony/make-call' \
--header 'X-Vgai-Key: aaaaaaaaaabbbbbbbbbbcccccccccc' \
--header 'Content-Type: application/json' \
--data-raw '{
"agent_id": "12345678901234567890abcd",
"to": "8190YYYYXXXX"
}'

上記を実行すると以下のような出力が表示されます
{"sessionId":"XXXXXXXX-YYYY-1234-ZZZZ-123456789012","sessionStartTime":"2025-02-27T02:50:53.674484"}

問題なく実行できた場合は、Toに設定した電話番号へ発信され、AI Studioに設定した自動音声が再生されて通話が終了されます。

 cURL実行時にパラメータをセットしてAI StudioのAgentへデータを渡すcURL実行時にsession_parametersを指定することでAI Studio側の変数へ値を渡すことができます。
cURLで実行する前にAI Studio側のCustom Parametersへ追加します。



今回はTEST_PARAMETERというパラメータを設定
動作確認のために、先ほど作ったSpeakノードの後ろへSend SMSを追加し、Body欄にTEST_PARAMETERを記述してPublishを実行

AI Studioの準備ができたらcURLコマンドへsession_parametersを指定して実行
curl --location --request POST 'https://studio-api-us.ai.vonage.com/telephony/make-call' \
--header 'X-Vgai-Key: aaaaaaaaaabbbbbbbbbbcccccccccc' \
--header 'Content-Type: application/json' \
--data-raw '{
"agent_id": "12345678901234567890abcd",
"to": "8190YYYYXXXX",
"session_parameters": [
    {
        "name": "TEST_PARAMETER",
        "value": "hogehoge"
    }
  ]
}'
今回はTEST_PARAMETERというパラメータへhogehogeという値を入れて実行します。


着信後、SMSの本文にhogehogeが入ってくれば完了となります。

 複数の値を渡す場合の表記session_parametersを複数指定する場合は{}をカンマ区切りで追加することで複数の指定が可能です。
curl --location --request POST 'https://studio-api-us.ai.vonage.com/telephony/make-call' \
--header 'X-Vgai-Key: aaaaaaaaaabbbbbbbbbbcccccccccc' \
--header 'Content-Type: application/json' \
--data-raw '{
"agent_id": "12345678901234567890abcd",
"to": "8190YYYYXXXX",
"session_parameters": [
    {
        "name": "TEST_PARAMETER",
        "value": "hogehoge"
    },
    {
        "name": "TEST_PARAMETER2",
        "value": "fugafuga"
    }
  ]
}'

 おわりに今回は最小限の指定でVonage AI Studioで作成したAgentをcURLから実行する方法について説明しました。


cURL実行側から値を渡したり発信するAgentを作り込むことで複雑なフローも実行可能です。

 参考資料Vonage AI Studio Documents - Triggering Outbound Call API