Naruko Todoke の使い方に戻る

リアルタイムAI連携画面の使い方

お客様がご契約の OpenAI をそのまま使って、電話に AI が応答する 機能です。 Naruko Todoke に連携として追加し、電話番号をキャンペーンへ割り当てるだけで使えます。 音声は Naruko と OpenAI が直接通信するため、応答までの待ち時間を抑えられます。

どの値を入力するのか

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

Naruko の項目OpenAI 側での場所接頭辞
OpenAI プロジェクト IDplatform.openai.com のプロジェクト設定 接続先の宛先になります。必須項目です。proj_
API キーAPI keys の Secret Key 同じ一覧に並ぶ Tracking ID は API キーではありません。sk-
Webhook シークレットプロジェクト設定 → Webhooks の signing secret Webhook URL を登録すると発行されます。呼び名が画面の項目名と違うので注意してください。whsec_

設定のしかた

OpenAI 側の準備

  1. 1

    OpenAI 側でプロジェクトと API キーを用意する

    platform.openai.com でプロジェクトを作り、API keys から Secret Key を発行します。この機能はお客様の OpenAI アカウントをそのまま使うため、AI の利用料は OpenAI から直接ご請求されます。

Naruko 側の設定

  1. 2

    Naruko で連携を作る

    「配信 → リアルタイムAI連携」の「連携を追加」で、名前と OpenAI プロジェクト ID、API キーを入れて保存します。接続先は Naruko 側で自動設定されるため入力は不要です。先に配信チャネルの購入が必要です。これは同時に使える通話数の枠で、AI が応対できなかったときに外線へ転送する設定にする場合は、着信と転送で 2 チャネル使います。

  2. リアルタイムAI連携の画面。登録済みの連携が一覧に並んでいる
    リアルタイムAI連携 /user/todoke/openai-realtime。「連携を追加」から作成し、電話番号は「共通 → 電話番号」で紐づけます。
  3. 3

    応答の方式を選ぶ

    既定は「組み込み」で、この画面で設定した指示・モデル・音声でそのまま応答します。外部システムで応答を組み立てたい場合や、通話中に予約状況などを調べて答えさせたい場合は「外部システム」を選びます。外部システムを選ぶと、必要なのは OpenAI プロジェクト ID だけになります。

  4. 4

    Webhook URL を OpenAI に登録する

    保存すると連携の設定画面に Webhook URL が表示されます。これを platform.openai.com のプロジェクト設定 → Webhooks に登録してください。イベントには realtime.call.incoming を必ず含めます。これが無いと、電話番号へ発信しても OpenAI から Naruko へ通知が届かず応答できません。

  5. 5

    signing secret を連携に登録する

    Webhook を登録すると、whsec_ で始まる signing secret が発行されます。連携の設定画面「Webhook シークレット」へ入力して保存してください。これを設定するまで、届いた通知が本物か検証できません。

  6. 6

    電話番号を割り当てる

    「共通 → 電話番号」で、対象の電話番号の着信アクションに「リアルタイム応答」を選び、使う連携を指定します。指定した電話番号への着信が、そのまま OpenAI の AI 応答につながります。取得済みの未割当の電話番号が無い場合は「電話番号を申請」から申請してください。

  7. 7

    電話番号ごとに応対を変える

    店舗や部署ごとに違う応対をさせたいときは、連携の設定画面の「電話番号ごとの応答の指示」から設定できます。1 つの連携のまま電話番号ごとに応対を変えられるので、店舗の数だけ連携や OpenAI プロジェクトを用意する必要はありません。空欄のままなら、連携に設定した指示がそのまま使われます。

  8. 8

    AI が応答できなかったときの動作を決める

    連携の設定画面の「応答できなかったときの動作」で、AI が応答できなかった着信の行き先を、話中で切断・外線転送・ルーム・IVR から選びます。既定は話中で切断です。AI の応答を待つ秒数は「呼び出し秒数」で 10〜120 秒に変えられます。待っている間、発信者には呼び出し音が聞こえます。オートコールなど発信のときは、この設定に関わらず話中で切断します。

  9. 連携の設定画面。応答できなかったときの動作と呼び出し秒数の欄
    連携の設定画面の上部

動作の確認

  1. 9

    通話が長くなりすぎないようにする

    連携の設定画面の「最大通話時間」で、通話が始まってから切断するまでの秒数を 30〜3600 秒で設定できます。既定は 600 秒で、空欄にすると上限はありません。切断の前に予告音は再生しません。AI の利用料はお客様の OpenAI アカウントへ直接発生するため、通話が長く残ると費用が増えます。「呼び出し秒数」は AI が応答するまで発信者をお待たせする時間で、こちらとは別のものです。

  2. 10

    発信する前に設定をテストする

    連携の設定画面の「OpenAI Realtime との接続性を確認」で「確認」を押すと、API キーが実際に使えるか・SIP 接続設定・応答の指示の有無・チャネル数をその場で確認できます。電話は発生しません。❌ や ⚠️ が表示された場合は、その理由に従って直してください。

応対を調整する

モデル

空欄なら gpt-realtime を使います。gpt-realtime-2.1 などの新しいモデルや、低コストな -mini も選べます。候補に無いモデル名も入力できます。

音声

新規作成時は OpenAI が推奨する marin が入っています。cedar も Realtime 専用の音声で、どちらも高品質です。ほかの音声に変えることもできます。保存済みの連携なら「試聴」ボタンでその声を確認できます。試聴にもお客様の OpenAI アカウントでごく少額の利用料が発生します。

通話開始の指示

電話に応答した直後、AI から話し始めるための指示です。空欄なら既定の文面を使います。入力欄にうすく表示されているものがそれです。ここは「話し始めて」というきっかけで、名乗り方や言葉づかいは「応答の指示」が決めます。最初のひとことを変えたいときに使ってください。

応答の指示

AI の受け答えを指示する文章です。この連携に割り当てた電話番号すべてに使われます。

  • 新規作成時はサンプルが入っています。相手の話を遮らない・聞き取れなければ聞き返す・電話番号を復唱して確認するなど、自然な会話のための指示です。
  • サンプルのままだと、社名を名乗らず一般的な受付の応対になります。会社名・店舗名・営業時間・所在地・よくあるご質問を書き足すと、その場で答えられることが増えます。
  • オートコールなど、こちらから発信したときの応対を変えたいときは「発信時の指示」を設定します。着信は「ご用件を伺う」・発信は「用件を伝える」のように応対が変わる場合だけで構いません。
  • 発信のときは、電話番号ごとの発信時の指示 → 連携の発信時の指示 → 電話番号ごとの応答の指示 → 連携の応答の指示、の順に探して最初に見つかったものを使います。

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

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

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-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…" }
    ]
  }
}

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

同じ値を X-Naruko- で始まる名前でも送っています。これから実装する場合は X-Call- をご利用ください。

応答する前に、X-Call-Token が連携の設定画面に表示されている着信トークンと一致することを確かめてください。 一致しない着信は、Naruko を経由していません。

X-Call-Callee着信先電話番号
X-Call-Caller発信元電話番号
X-Call-Direction着信: inbound / 発信: outbound
X-Call-LinkedidNaruko 側の通話 ID。通話履歴との突き合わせにご利用いただけます
X-Call-Node通話を処理したサーバー。通話 ID との組で一意になります
X-Call-Token連携ごとの着信トークン。この値と一致する着信だけを受け付けてください

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 が用件を伺ったうえで担当者へおつなぎする、といった運用にご利用いただけます。
※ 転送の可否は経路のネットワーク環境にも依存します。ご利用前に実際の通話でご確認ください。

OpenAI のドキュメント「Realtime calls」で accept / reject の仕様を読む

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時は空席があります。その旨をお伝えください。"
  }
}

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

通話の記録を残す

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

通話 ID

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

受け取る場所項目名例
OpenAI へ渡す SIP ヘッダX-Call-Linkedid1700000000.42
着信 Webhookuniqueid同じ値
通話履歴 APIuniqueid同じ値

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

終了の確認

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

  • 着信 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 でそろえてあります。

応答できなかった通話の通知

AI が応答できなかった通話と、「応答できなかったときの動作」でもつながらなかった通話は、 配信の Webhook の realtime.failed で通知します。 1 件ごとに 1 回届き、届かなければ再送します。

{
  "request_timing": "realtime.failed",
  "environment": "live",
  "data": {
    "uniqueid": "1700000000.42",
    "integration_id": 3,
    "integration_name": "AI応対",
    "campaign_id": 45,
    "direction": "inbound",
    "stage": "ai",
    "reason_code": "no_answer",
    "reason": "AI が時間内に応答しませんでした。外部システムが着信を受け付けているかご確認ください。",
    "callee_phonenumber": "0312345678",
    "fallback_action": "transfer",
    "occurred_at": "2026-10-16T09:18:28+09:00"
  }
}
stage意味
aiAI が応答できなかった。fallback_action の動作へ進みました。
fallback「応答できなかったときの動作」でもつながらなかった。

reason_code は次のいずれかです。 reason には、リアルタイムAI連携の画面の「最近のエラー」と同じ文が入ります。

reason_code意味
not_configured連携の設定が完了していないため、AI へ接続しなかった。
channel_limit配信チャネルが足りないため、接続しなかった。
no_campaign電話番号にキャンペーンが割り当てられていないため、接続しなかった。
endpoint_unhealthy外部システムの監視用エンドポイントが異常のため、AI へ接続しなかった。着信のときだけです。
no_gateway転送に使う回線を決められず、転送先へ発信しなかった。stage が fallback のときだけです。
rejected着信を拒否された。外部システムが OpenAI で着信を拒否したときもこの値です。
busy話中だった。
no_answer時間内に応答しなかった。
unavailable接続できなかった。
unallocated_number接続先が存在しないか、経路が無かった。
invalid_number発信できない接続先だった。
congestion回線が混み合っていた。
network_error回線に問題が発生した。
failed上記以外の理由で接続できなかった。

外部システムの監視

応答の方式が「外部システム」の連携で使えます。連携の設定画面の「監視用エンドポイント」に入力すると、異常のあいだの着信を AI へつながず、 「応答できなかったときの動作」へすぐに進めます。発信者が呼び出し秒数のあいだ待たされることはありません。

連携の設定画面。応答の方式で外部システムを選び、その下の監視用エンドポイントに入力している
連携の設定画面。外部システムを選ぶと、監視用エンドポイントの欄が表示されます。
指定できる URLhttps で始まる公開 URL。ポートは 443
確かめ方30 秒ごとに GET を送ります。5 秒以内に 2xx を返せば成功です。リダイレクトは失敗として扱います
異常になるとき2 回続けて失敗したとき
正常へ戻るとき2 回続けて成功したとき
異常のあいだの着信realtime.failed を reason_code: endpoint_unhealthy で送ります。発信は対象外です
状態の確認 連携の一覧と、公開 API の health_status
連携の一覧。監視用エンドポイントの状態・最終確認・直近の失敗が表示されている
異常のあいだの連携の一覧。最後に確かめた日時と、失敗した理由が表示されます。

録音と文字おこし

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

応答の方式会話の文字おこしの保存先
組み込みNaruko が WebSocket で受け取って保存し、録音ライブラリで読めます
外部システム外部システムが WebSocket で受け取ります。Naruko には残りません

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

認証

  • OpenAI からの通知の検証は、OpenAI が発行する署名シークレットで行います。検証のしかたは OpenAI の Webhooks ガイドをご確認ください。
  • 通話履歴 API は Naruko Todoke の API キー(Authorization: Bearer nrk_live_…)で認証します。発行方法は 公開 API ガイドをご覧ください。
  • 着信 Webhook は、設定画面で発行した署名の鍵で検証します。検証のしかたは 着信 Webhook の仕様をご覧ください。

OpenAI 側の操作について

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

ご利用にあたって

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

チャネルの購入やキャンペーンへの割り当て、電話番号の申請など、Naruko Todoke 全体の使い方はこちらをご覧ください。

Naruko Todoke の使い方