setup-inbound

Bolna の着信通話

着信通話では、電話番号をエージェントに紐付け、その番号への着信に自動で応答します。必要に応じて、IVR メニュー、発信者の識別、スパム対策、多言語切り替えを追加できます。

エンドポイントは 2 つだけです

エンドポイント	用途
POST /inbound/setup	電話番号をエージェントに紐付けます（IVR 設定は任意）。
POST /inbound/unlink	紐付けを解除します。

どちらも、Authorization: Bearer $BOLNA_API_KEY と Content-Type: application/json を指定します。

phone_number_id の取得元

電話番号の取得元	ID の取得方法
Bolna ホスティング（ダッシュボードで購入）	GET /phone-numbers/all — manage-phone-numbers を参照してください。
接続済みプロバイダー（お使いの Twilio、Plivo、Vobiz、Exotel）	プロバイダーの接続後に電話番号を一覧表示すると返されます。
独自の SIP トランク（BYOT）	POST /sip-trunks/trunks/{id}/numbers から返されます — setup-sip-trunk を参照してください。

取得元にかかわらず、紐付けの手順は同じです。

基本的な紐付け

curl -X POST https://api.bolna.ai/inbound/setup \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "phone_number_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

レスポンス：

{
  "url": "https://api.bolna.ai/inbound_call?agent_id=...&user_id=...",
  "phone_number": "+19876543210",
  "id": "3c90c3cc0d444b5088888dd25736052a"
}

基本的な設定はこれで完了です。これで、+19876543210 への着信にエージェントが応答します。

1 つの電話番号につき、エージェントは 1 つです。 電話番号を別のエージェントに再紐付けすると、以前の紐付けは通知なしに解除されます。再紐付けせずに解除するには、/inbound/unlink を使用します。

IVR（メニュールーティング）

「営業は 1、サポートは 2」のような案内や、通話前のデータ収集に使用します。Plivo のみ対応しています。

curl -X POST https://api.bolna.ai/inbound/setup \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @assets/ivr_department_routing.json

アセットファイル：

{
  "agent_id": "default-agent-uuid",
  "phone_number_id": "phone-number-uuid",
  "ivr_config": {
    "enabled": true,
    "voice": "Polly.Aditi",
    "welcome_message": "Welcome to Acme Corp.",
    "timeout": 5,
    "max_retries": 2,
    "default_agent_id": "default-agent-uuid",
    "steps": [
      {
        "step_id": "department",
        "type": "menu",
        "prompt": "Press 1 for Sales. Press 2 for Support. Press 3 for Billing.",
        "field_name": "department",
        "options": [
          { "digit": "1", "label": "Sales",   "agent_id": "sales-agent-uuid" },
          { "digit": "2", "label": "Support", "agent_id": "support-agent-uuid" },
          { "digit": "3", "label": "Billing", "agent_id": "billing-agent-uuid" }
        ]
      }
    ]
  }
}

ステップの種類

種類	用途
menu	選択肢を提示し、押された番号に応じてルーティングします。
collect	複数桁の入力（口座番号、PIN など）を取得します。

IVR のトップレベルフィールド

フィールド	デフォルト	備考
enabled	false	IVR 全体の有効・無効を切り替えます。
voice	Polly.Joanna	IVR プロンプト用の Polly 音声です。ヒンディー語と英語には Polly.Aditi を使用します。
welcome_message	—	接続時に、最初のステップの前に 1 回再生されます。
timeout	5	ステップごとに、発信者の入力を待つ秒数です。
max_retries	2	各ステップで無効な入力があった場合の再試行回数です。
invalid_input_message	"Invalid input. Please try again."	無効なキーが押されたときに再生されます。
no_input_message	"No input received. Goodbye."	タイムアウト時に再生されます。
steps[]	必須	IVR のフローです。
default_agent_id	—	オプションレベルで agent_id が設定されていない場合のフォールバックエージェントです。

ステップの遷移

フィールド	動作
next_step	直線的な遷移：現在のステップの後に、このステップへ進みます。
conditional_next	押された番号に応じて分岐します：{"1": "menu_en", "2": "menu_hi"}。
いずれもなし	IVR を終了します。選択された agent_id または default_agent_id にルーティングします。

分岐を使った多言語 IVR

{
  "step_id": "language",
  "type": "menu",
  "prompt": "For English press 1. Hindi ke liye 2 dabayein.",
  "field_name": "language",
  "options": [
    { "digit": "1", "label": "English" },
    { "digit": "2", "label": "Hindi" }
  ],
  "conditional_next": { "1": "menu_en", "2": "menu_hi" }
}

多言語対応の部署振り分けフロー全体については、assets/ivr_multilingual.json を参照してください。

エージェントに渡される情報

IVR の完了後、収集されたフィールドは recipient_data として利用できます。

{
  "department": "Sales",
  "account_number": "123456",
  "language": "English",
  "ivr_completed_at": "2026-05-19T10:30:00Z"
}

エージェントのプロンプトで使用します："Customer selected {department}. Account number: {account_number}."

IVR を無効にする

curl -X POST https://api.bolna.ai/inbound/setup \
  ... \
  -d '{ "agent_id": "...", "phone_number_id": "...", "ivr_config": { "enabled": false } }'

メニューと入力収集ステップの例、条件分岐を含む IVR の詳しいリファレンスについては、references/ivr-config.md を参照してください。

発信者の識別（ingest_source_config）

発信者に応じて、エージェントのプロンプト変数に値を事前入力します。これは /inbound/setup ではなく、エージェントに設定します。設定方法は 3 種類あります。

ソース	適した用途
内部 API	既存の CRM／顧客データベースがあるチーム。リアルタイムで、完全に動的です。
CSV アップロード	小規模なチーム、通話量が少ない場合、ノーコードでの利用。静的なため、更新するには再アップロードが必要です。
Google Sheet	コーディング不要でのリアルタイム同期。シートは一般公開されている必要があります。

内部 API ソース

Bolna は、次の情報を付けてエンドポイントに GET リクエストを送信します。

GET https://your-api.example.com/customers
    ?contact_number=+19876543210
    &agent_id=<agent_uuid>
    &execution_id=<execution_uuid>

認証：Bearer トークン（エージェントごとに設定）。

レスポンスの JSON は recipient_data にマージされます。プロンプトでは次のように使用します。

You are speaking with {first_name} {last_name}. They are on the {plan} plan,
last contacted on {last_contacted_at}.

CSV／Google Sheet ソース

どちらの場合も、contact_number 列（国番号付き）が必要です。それ以外の列はすべてプロンプト変数になります。

contact_number,first_name,last_name,plan,last_contacted_at
+19876543210,Priya,Sharma,Enterprise,2026-05-12
+918765432109,Rahul,Verma,Pro,2026-05-14

各ソースの詳しい設定方法については、references/caller-identification.md を参照してください。

スパムと不正使用の制御

これらは受信マッピング自体ではなく、エージェントのtask_configに設定します。

フィールド	説明
inbound_limit	受信者の電話番号ごとの最大通話数です。-1 = 無制限です。1つの番号による費用の増加を防ぐのに役立ちます。
whitelist_phone_numbers[]	あらゆる制限や不明な発信者のルールを常に回避するE.164形式の番号です。
disallow_unknown_numbers	ブール値です。trueの場合、エージェントのingest_source_configルックアップに含まれていない発信者を拒否します。ingest_source_configの設定が必要です。

{
  "task_config": {
    "inbound_limit": 3,
    "whitelist_phone_numbers": ["+919876543210", "+19876543210"],
    "disallow_unknown_numbers": true
  }
}

disallow_unknown_numbers: trueでingest_source_configが設定されていない場合、すべての受信通話が拒否されます。必ず最初に発信者識別を設定してください。

多言語の自動切り替え

Bolnaは約3回の会話ターン後に発信者の言語を自動検出し、システムメッセージ（通話終了、ユーザーオンライン確認、ツール待機）をその言語に切り替えられます。エージェントで言語ごとのバリエーションを設定してください。

{
  "check_user_online_message": {
    "en": "Hey, are you still there?",
    "hi": "क्या आप अभी भी वहाँ हैं?",
    "ta": "வணக்கம், நீங்கள் இன்னும் இணைப்பில் இருக்கிறீர்களா?"
  },
  "call_hangup_message": {
    "en": "Thank you for calling. Goodbye!",
    "hi": "कॉल करने के लिए धन्यवाद। अलविदा!"
  }
}

フォールバックの順序：検出された言語 → en → 最初に利用可能な言語。安全策として、必ずenを設定してください。 references/auto-switch-messages.mdを参照してください。

リンク解除

curl -X POST https://api.bolna.ai/inbound/unlink \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "123e4567-e89b-12d3-a456-426614174000" }'

電話番号の所有権は引き続き維持されます（プロバイダー／SIPトランク／Bolnaの在庫内）。エージェントとのリンクのみが解除されます。

詳細情報

ファイル	内容
references/ivr-config.md	すべてのステップタイプ、ナビゲーション、音声、高度なパターン。
references/caller-identification.md	API、CSV、Google Sheet — セットアップ手順とプロンプト変数の接続方法。
references/auto-switch-messages.md	多言語メッセージ一式、フォールバックの順序、対応コード。
assets/ivr_department_routing.json	部門振り分け用のシンプルなIVR。
assets/ivr_multilingual.json	言語選択 → 部門メニュー。言語ごとに別々のエージェントを使用します。
assets/ivr_account_verification.json	エージェントにつなぐ前に、2段階のcollectフロー（アカウント＋PIN）を実行します。
scripts/setup_inbound.py	シンプルなセットアップとIVRセットアップ用のフラグを使って、POST /inbound/setupをラップします。

トラブルシューティング

症状	原因	対処方法
呼び出し音は鳴るが応答しない	phone_number_idがまだマッピングされていない	POST /inbound/setupを再実行し、GET /phone-numbers/allで確認します
IVRが400を返す	Plivo以外の番号でIVRを使用している	IVRはPlivo専用です。Plivo経由でルーティングするか、IVRを使用しないでください
プロンプト内のrecipient_dataが空	ingest_source_configが設定されていない、またはcontact_numberが一致しなかった	ソースに発信者の番号が含まれていることを確認します。ルックアップのHTTPステータスについてBolnaのログを確認します
すべての発信者が拒否される	ingest_source_configを設定せずにdisallow_unknown_numbers: trueにしている	先にソースを追加するか、disallow_unknown_numbers: falseに設定します
自動切り替え後の通話終了メッセージが誤った言語で再生される	検出には3ターン必要だが、通話がそれより短かった	enのフォールバックを設定します。最初の1〜2ターンは引き続き主要言語になる場合があります
エージェントは応答するが、受信SIPの音質が悪い	ulawコーデックの不一致	BolnaはSIP経由の受信でulawを設定します。トランクでulawが許可されていることを確認します

関連項目

• manage-phone-numbers — Bolna番号の購入または一覧表示（phone_number_idの取得元）。
• setup-sip-trunk — BYOT番号をBolnaに接続します。
• create-agent — task_config（スパム制御）とingest_source_configは、エージェントの本文にあります。
• setup-tools/references/dtmf.md — 通話中のキーパッド入力（IVRメニューのルーティングとは異なります）。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md — 規制対象のインドの番号を使用する場合のDLT／140／160シリーズの規則。