OpenAI Realtime 応答の使い方

1. 通知の受け取り先を登録する

platform.openai.com のプロジェクト設定にある Webhooks へ、外部システムの URL を登録します。 Naruko の Webhook URL は使用しません。 イベントには realtime.call.incoming を含めてください。 署名の検証方法は OpenAI の Webhooks ガイドをご確認ください。

2. 受信した Webhook を解析する

着信すると、次の形式の通知が届きます。

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

sip_headers から、 Naruko が付与した次の情報を取得できます。

3. 応答を開始する

通知に含まれる call_id を指定し、 お客様の API キーで応答を開始します。AI の話し方・声・応対内容はここで指定します。

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

{
  "type": "realtime",
  "model": "gpt-realtime",
  "instructions": "あなたは○○店の受付です。…",
  "audio": { "output": { "voice": "marin" } }
}

応答しない場合は /reject を呼び出します。 呼び出し中のあいだに応答してください。 応答がないまま呼び出しが終了すると、発信者には話中音が流れます。

通話を開始したあとは、 /refer で担当者などの別の番号へ転送、 /hangup で通話を終了できます。 AI が用件を伺ったうえで担当者へおつなぎする、といった運用にご利用いただけます。
※ 転送の可否は経路のネットワーク環境にも依存します。ご利用前に実際の通話でご確認ください。

4. 通話中に制御する

応答したあと、同じ通話へ WebSocket で接続すると、通話中の会話を受け取りながら AI へ指示を送れます。予約の空き状況をお伺いしてから確認してお答えする、といった応対を実現できます。

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 が話した内容

相手の発話の文字起こしは、接続後に session.update で有効化した場合に届きます。

AI に話させるときは response.create を送ります。 調べた内容を伝えたい場合も、この指示に含めてお送りください。

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