OpenAI Realtime 応答の使い方

どの値を入力するのか

OpenAI 側の画面と Naruko 側の項目名が一致していないため、取り違えが起きやすい箇所です。 接頭辞で見分けてください。

設定のしかた

応対を調整する

外部システムで応答を組み立てる場合

連携の「応答の方式」で 外部システム を選ぶと、 外部システムが OpenAI からの通知を受けて応答を組み立てます。 予約システムや顧客データベースを参照した応対、通話中に調べて答える応対を実現できます。 Naruko は電話を OpenAI へつなぐところまでを担当します。

{
  "type": "realtime.call.incoming",
  "data": {
    "call_id": "rtc_xxxxxxxx",
    "sip_headers": [
      { "name": "X-Call-Callee", "value": "0312340001" },
      { "name": "X-Call-Caller", "value": "0312345678" },
      { "name": "X-Call-Direction", "value": "inbound" },
      { "name": "X-Call-Linkedid", "value": "1755150000.42" },
      { "name": "X-Call-Node", "value": "node1" },
      { "name": "X-Call-Token", "value": "a1b2c3…" }
    ]
  }
}

POST https://api.openai.com/v1/realtime/calls/{call_id}/accept
Authorization: Bearer <お客様の API キー>

{
  "type": "realtime",
  "model": "gpt-realtime",
  "instructions": "○○店の受付として応対してください。…",
  "audio": { "output": { "voice": "marin" } }
}

wss://api.openai.com/v1/realtime?call_id={call_id}
Authorization: Bearer <お客様の API キー>

conversation.item.input_audio_transcription.completed   // 相手が話した内容
response.output_audio_transcript.done                  // AI が話した内容

{
  "type": "response.create",
  "response": {
    "instructions": "3月5日18時は空席があります。その旨をお伝えください。"
  }
}

※ 外部システムを選択した場合、Naruko 側の API キー・モデル・音声・応答の指示は使用しません。

通話の記録を残す

AI の応対を業務システムへ記録したり、顧客管理と結び付けたりするときに必要な情報をまとめます。 応答の方式が組み込み・外部システムのどちらでも共通です。

通話 ID

Naruko は通話ごとに ID を持っています。どこで受け取っても同じ値なので、これを鍵にして突き合わせられます。

通話明細は通話の終了後に記録されます。応答の可否を判断する時点では取得できません。 複数の組織をまたいで管理される場合は、 X-Call-Node と組み合わせてください。

終了の確認

OpenAI から通話終了の通知は届きません。 OpenAI が送るのは着信時の realtime.call.incoming だけです。 終了・通話時間・結果は Naruko 側の次の２つでご確認ください。

• 着信 Webhook の着信切断時（incoming_call_hangup）… 終了した時点で通知します。届かなければ最大 3 回まで再送します。
• 通話履歴 API （GET /api/public/v1/calls）… あとから引き直せます。通知を受け取れなかったときの確認にお使いください。

# 上の表の ID をそのまま指定します
curl https://hub.naruko.app/api/public/v1/calls/1700000000.42 \
  -H "Authorization: Bearer nrk_live_..."

AI が応答しなかった通話も確認できます。call_status が NO ANSWER / BUSY などになり、通話時間は 0 秒です。 項目名は Webhook と API でそろえてあります。

録音と文字おこし

通話の音声の録音は準備中です。 会話の文字おこしは OpenAI が行い、通話中に接続する WebSocket へテキストが届きます。 それをどこで受け取って保存するかが、応答を組み立てる場所によって変わります。

文字おこしは、有効にしてからお使いください。 WebSocket へ接続したあと session.update を送り、 audio.input.transcription にモデルと言語を指定します。 Naruko が応答を組み立てる場合は、Naruko が whisper-1 と日本語を指定しています。 言語を指定すると精度と遅延が改善すると OpenAI が案内しています。

認証

• OpenAI からの通知の検証は、OpenAI が発行する署名シークレットで行います。検証のしかたは OpenAI の Webhooks ガイドをご確認ください。
• 通話履歴 API は Naruko Todoke の API キー（Authorization: Bearer nrk_live_…）で認証します。発行方法は Todoke API ガイドをご覧ください。
• 着信 Webhook には署名が付きません。受信側の保護のしかたは 着信 Webhook の仕様に例を載せています。

OpenAI 側の操作について

OpenAI の画面は随時更新されるため、操作方法は公式ドキュメントをご確認ください。

• API キーを発行する OpenAI の「API keys」の画面です。Secret Key を発行できます。
• Webhook を登録する OpenAI のドキュメント「Webhooks」です。エンドポイントの作り方と signing secret の扱いが説明されています。
• SIP で接続する OpenAI のドキュメント「Realtime API with SIP」です。Naruko が使っている接続方式で、ネットワーク要件も記載されています。
• モデル・音声の一覧 OpenAI のリファレンス「Realtime sessions」です。指定できるモデル名と音声名が載っています。

ご利用にあたって

• この機能は通話中に配信チャネルを 1 つ使います。チャネルは同時に使える通話数の枠です。チャネルは着信した電話番号が属するキャンペーンごとに数えます。足りないと着信は話中になります。無料枠はありませんので、ご利用の前にチャネルを購入し、キャンペーンへ割り当ててください。
• AI の利用料はお客様の OpenAI アカウントへ直接発生します。Naruko からの従量課金はありません。
• 応答の指示は電話番号ごとに変えられます。別の OpenAI プロジェクトを使い分けたいときは、連携を分けてください。
• 設定に不備があるときや OpenAI 側で応答できないときの動作は、「応答できなかったときの動作」で選べます。話中で切断・外線転送・ルーム・IVR から選べて、既定は話中で切断です。この設定が作動するのは着信のときだけです。オートコールなど発信のときは、設定に関わらず話中で切断します。
• 同時通話数の上限に達したときは、「応答できなかったときの動作」に関わらず話中になります。チャネルを購入していない通話を外線へ転送すると、通話料が発生するためです。
• 「外部システム」を選んだ場合、Naruko は OpenAI に電話をつなぐところまでを行います。応答の内容は外部システムが決めるため、Naruko 側の指示・モデル・音声の設定は使いません。
• 「外部システム」を選択した場合、Naruko は OpenAI への発信に独自のヘッダを付与します。着信先電話番号・発信元電話番号・着信か発信かを取得できるため、店舗や部署ごとに応対を切り替えられます。