ユーザが発声した内容を OpenAI Realtime API が回答を返します。
sequenceDiagram
participant user
participant vonage
participant OpenAI Realtime API
participant External Service
user->>vonage: Input
vonage->>OpenAI Realtime API: WebSocket
OpenAI Realtime API->>External Service: Function Calling
External Service-->>OpenAI Realtime API: Data
OpenAI Realtime API-->>vonage: WebSocket
vonage-->>user: Response
- Vonage Voice API ガイド
- 公開鍵と秘密鍵を生成し、秘密鍵をprivate.keyという名前に変更してディレクトリの直下に配置。
- 作成したアプリケーションに購入した電話番号をリンク
https://platform.openai.com/docs/quickstart
npm install
npm run start
ngrok http 3000起動した際に払い出される ngrok の URL をコピーする。
cp .env.example .env.envを設定する。
| キー | 値 |
|---|---|
| SERVER_URL | ngrokで払い出されたURL（https://は除く） |
| OPENAI_API_KEY | OpeAIのシークレットキー（sk-から始まる文字列） |
| OPENAI_API_VERSION | 2025-04-01-preview（OpenAI Realtime API の最新バージョン） |
| OPENAI_MODEL | gpt-realtime（Realtime 対応のモデル） |
| VONAGE_PRIVATE_KEY_PATH | Vonage Voice API v2 用の秘密鍵ファイルパス（例: ./private.key） |
| VONAGE_OUTBOUND_FROM | Vonageで取得した発信元電話番号（E.164形式） |
| VONAGE_TRANSPORT_NUMBER | 転送先のデフォルト電話番号（E.164形式）。transfer_call で指定がない場合に利用されます。 |
上記の設定では、OpenAI Realtime API 側に OPENAI_API_VERSION=2025-04-01-preview を送り、gpt-realtime モデルと組み合わせることで最新仕様に対応しています。これにより音声入力→応答のリアルタイムループが安定して機能します。
追加の調整をしたいときは、ルートにある system-message.txt に書かれた文言が最優先で読み込まれます。ファイルが存在しないか空の場合はデフォルトの挨拶文（README の冒頭にあるチャッピーの定義）を使用します。
.envを読み込むために npm run start を Ctrl-c で終了させ、再度 npm run start で起動。
ngrok を起動するたびに払い出される URL が異なるため、ngrok を再起動した場合は上記手順を繰り返す。
Vonage のダッシュボードから、作成したアプリケーションの設定画面を開き、回答 URL に ngrok の URL/incoming-call を設定、メソッドはPOST。
同じく、イベント URL に ngrok の URL/event を設定、メソッドはPOST。
Vonage Voice API v2 を使って任意の番号へ発信するには、以下のように POST /connect を呼び出します。呼び出し時に VONAGE_APPLICATION_ID と VONAGE_PRIVATE_KEY_PATH から生成した JWT を内部で利用し、相手が応答すると /answer の NCCO（ガイダンス → WebSocket 接続）を通じて OpenAI Realtime に接続します。
curl -X POST https://<サーバー>/connect \
-H "Content-Type: application/json" \
-H "X-API-Key: ${VONAGE_APPLICATION_ID}" \
-d '{
"to": "+818012345678",
"from": "+815012345678"
}'from を省略すると VONAGE_OUTBOUND_FROM の値が自動で利用されます。秘密鍵ファイル（例: private.key）は .gitignore されているので、ローカル/本番それぞれの環境に配置してください。
/connect では X-API-Key ヘッダーを必須とし、値が VONAGE_APPLICATION_ID と一致しないリクエストは拒否します。バックエンドと連携するクライアントでは、このヘッダーを常に付与してください。
ngrokが起動しアプリケーションも起動していることを確認したら、アプリケーションにリンクした電話番号に電話をして、AIによる回答が戻って来ることを確認する。
Fly.io 環境を使って、アプリケーションをデプロイすることができます。
brew install flyctlまずは本番用の環境変数を作成します。
cp .env .env.production次に、アプリケーションのデプロイ環境を作成します。
fly launchこれでDocker環境を自動的に生成してくれます。
サーバーのURL（XXXXXXXX.fly.dev）が払い出しされるので、.env.productionのSERVER_URLを更新します。
以下のコマンドで、.env.productionの内容をFly.ioの環境変数に設定できます。
fly secrets import < .env.production個別に環境変数を設定する場合は、以下のように設定することもできます。
fly secrets set NAME=VALUE環境変数を変更したら、デプロイをし直してください。
以下のコマンドでデプロイができます。
npm run deploychange-url.jsでVonageのアプリケーション環境を書き換えることができるので、以下のコマンドを使うと実行環境を切り替えながらテストができます。
ローカル実行
npm run debugサーバー実行
npm run deploy