create-disposition

Bolna Dispositions（通話後の抽出）

Disposition は、通話ごとに生の文字起こしを構造化データに変換します。各 disposition は 1 つの質問を行い、結果は実行ペイロードの extracted_data と webhook の配信内容に格納されます。

階層

Agent
└── Extractions (feature)
    └── Category  (e.g. "Lead Quality")
        └── Disposition  (e.g. "Call Outcome")

Category は結果を視覚的にグループ化します。Disposition が基本単位で、1 つの質問と 1 セットの回答で構成されます。

disposition を追加するタイミング

ユースケース	フィールド名	回答タイプ
通話結果	Call Outcome	事前定義：interested / not_interested / follow_up / wrong_number
リードの適格性確認（BANT）	Budget、Authority、Need、Timeline	混合 — 自由入力 + Yes/No
予約の確定	Appointment Date、Appointment Time	timestamp / text による検証付きの自由入力
感情	Customer Sentiment	事前定義：positive / neutral / negative
エージェントへの引き継ぎが必要	Handover Needed	事前定義：Yes / No
コンプライアンス	Disclosure Read、Consent Captured	事前定義：Yes / No
連絡先情報の取得	Email、Alt Phone	email / regex による検証付きの自由入力
自由形式の要約	Main Concern、Reason for Cancellation	自由入力

エンドポイント

エンドポイント	用途
GET /dispositions/	アカウント内のすべての disposition を一覧表示します（任意でエージェントに絞り込み可能）
GET /dispositions/{id}	単一の disposition を取得します
POST /dispositions/	エージェントに任意で紐付けて、1 つの disposition を作成します
POST /dispositions/bulk	エージェント用の N 個の disposition をアトミックに作成します
PUT /dispositions/{id}	disposition を更新します（コピーオンライトに対応）
DELETE /dispositions/{id}	disposition を削除します
POST /v2/agent/{agent_id}/dispositions/test	文字起こしに対してエージェントのすべての disposition をテストします

認証：Authorization: Bearer $BOLNA_API_KEY。すべての POST/PUT で JSON ボディを使用します。

Disposition オブジェクト

{
  "name": "Call Outcome",
  "question": "What was the outcome of the call?",
  "system_prompt": "You are analyzing a sales call transcript.",
  "category": "Lead Quality",
  "model": "gpt-4.1-mini",

  "is_subjective": true,
  "is_objective": true,

  "subjective_type": "text",
  "subjective_type_config": null,

  "objective_options": [
    { "value": "interested",     "condition": "Customer expressed genuine interest and agreed to a next step" },
    { "value": "not_interested", "condition": "Customer declined all proposals" },
    { "value": "follow_up",      "condition": "Customer asked to be contacted later" }
  ],

  "agent_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}

フィールド	型	備考
name	string	extracted_data に表示される名前です。
question	string	LLM が文字起こしを基に評価するプロンプトです。具体的に指定してください。
system_prompt	string | null	評価用 LLM に任意で指定するシステムコンテキストです。
category	string	出力をグループ化します。デフォルトは "General" です。
model	string	デフォルトは gpt-4.1-mini です。重要度の高い抽出には、より高性能なモデルを使用してください。
is_subjective	bool	subjective による自由入力の回答を有効にします。
is_objective	bool	objective による事前定義の選択肢を有効にします。
subjective_type	string	自由入力の制約です。以下を参照してください。
subjective_type_config	object	subjective_type == "regex" の場合に必須です。
objective_options	array	is_objective が true の場合に必須です。
agent_ids	array	この disposition が紐付けられているエージェントです。

is_subjective または is_objective の少なくとも一方を true にする必要があります。

自由入力の検証タイプ

subjective_type	検証内容	値の例	備考
text	任意の内容	"Customer was happy with the demo"	デフォルトです。検証は行いません。
timestamp	ISO 8601	"2026-04-08T14:30:00"	解析して検証します。
numeric	整数または小数	"42"、"3.14"
boolean	true または false と完全一致	"true"
email	有効な RFC メールアドレス	"[email protected]"
regex	subjective_type_config.pattern に一致	"1234567890"	subjective_type_config に pattern と任意の description を追加します。

検証に失敗した場合、元の LLM の応答は subjective に保持され、validation.is_valid は false になります。データは失われません。使用するかどうかは利用側が判断します。

正規表現の例（10 桁の電話番号）：

{
  "subjective_type": "regex",
  "subjective_type_config": {
    "pattern": "^\\d{10}$",
    "description": "10-digit phone number"
  }
}

Objective の選択肢

{
  "value": "interested",
  "condition": "Customer expressed genuine interest and agreed to a next step",
  "sub_options": []
}

sub_options は再帰的に設定でき、階層的な分類（例：interested → enterprise / pro / starter）に対応します。

実行時の出力形式

{
  "execution_id": "abc123",
  "status": "completed",
  "transcript": "...",
  "extracted_data": {
    "Lead Quality": {
      "Call Outcome": {
        "subjective": "Customer expressed strong interest and asked about enterprise pricing.",
        "objective": "interested",
        "confidence": 0.92,
        "confidence_label": "High",
        "reasoning_subjective": "Customer asked about enterprise pricing and requested a demo.",
        "reasoning_objective": "Customer explicitly expressed interest and agreed to a next step.",
        "validation": null
      }
    },
    "Contact Info": {
      "Customer Email": {
        "subjective": "[email protected]",
        "objective": null,
        "confidence": 0.95,
        "confidence_label": "High",
        "reasoning_subjective": "Customer clearly provided their email address during the call.",
        "reasoning_objective": null,
        "validation": { "is_valid": true, "expected_type": "email" }
      }
    }
  }
}

フィールド	説明
subjective	自由記述の回答です。何も見つからない場合は ""、is_subjective が false の場合は null です。
objective	定義済みの値から選択されます。または null です。
confidence	0.0 ～ 1.0 です。
confidence_label	"High"（≥0.8）、"Medium"（≥0.5）、"Low"（<0.5）です。
reasoning_subjective / reasoning_objective	回答タイプごとの LLM による説明です。監査とデバッグに役立ちます。
validation	subjective_type が text ではなく型指定されている場合にのみ含まれます。

同じペイロードが Webhook 経由でも届きます。https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md を参照してください。

ディスポジションを 1 つ作成する

curl --request POST https://api.bolna.ai/dispositions/ \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "name": "Call Outcome",
  "question": "What was the outcome of the call?",
  "category": "Lead Quality",
  "is_subjective": true,
  "is_objective": true,
  "subjective_type": "text",
  "objective_options": [
    { "value": "interested",     "condition": "Customer expressed genuine interest and agreed to a next step" },
    { "value": "not_interested", "condition": "Customer declined all proposals" },
    { "value": "follow_up",      "condition": "Customer asked to be contacted later" }
  ],
  "agent_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}
JSON

id を含む完全なディスポジションオブジェクトを返します。後で更新する場合は保存してください。

一括作成（新しいエージェントに推奨）

完全な分析スイートをアトミックに追加します。すべて成功するか、すべて失敗します。

curl --request POST https://api.bolna.ai/dispositions/bulk \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --header "Content-Type: application/json" \
  --data @assets/sample_bulk_dispositions.json

アセットファイルには、通話結果、顧客感情、予算への言及、意思決定者、引き継ぎの必要性、顧客のメールアドレスを含む、営業電話分析パック一式が含まれています。

本番環境で運用する前にテストする

エージェントのすべてのディスポジションをトランスクリプトに適用して、出力を確認します。

curl --request POST "https://api.bolna.ai/v2/agent/$AGENT_ID/dispositions/test" \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "transcript": "Agent: Hi, how can I help? Customer: I am interested in your enterprise plan. Agent: Great — what email should I send the proposal to? Customer: priya at example dot com.",
    "call_date": "2026-05-19T10:00:00Z"
  }'

レスポンスの形式は、実際の実行における extracted_data と同じです。本番環境の通話で期待する結果になるまで、ディスポジションを調整してください。

更新とコピーオンライトのルール

スコープ指定の更新（リクエスト本文または URL に agent_id を渡す場合）：

ディスポジションの状態	動作	ステータス
このエージェント専用	その場で編集	200 OK（ID は変更されません）
他のエージェントと共有	新しいプライベートコピーを作成し、エージェントをそのコピーに再リンク	201 Created（新しい ID）

ディスポジション ID を独自のデータベースに保存している場合、201 が返されたら保存済みの ID を更新してください。古い ID は引き続き存在しますが、スコープ指定したエージェントには紐付かなくなります。

スコープ指定なしの更新（agent_id なし）：

• 管理者：任意のディスポジションをその場で編集できます。
• 管理者以外：所有するディスポジションのみ編集できます。

認可に関する注意点

• 一般ユーザーが DELETE できるのは、自分が作成したディスポジション（created_by が自身のユーザー ID と一致するもの）のみです。
• 管理者は任意のディスポジションを削除できます。
• ディスポジションの出力をすでに含む過去の実行は、編集や削除の影響を受けません。変更されるのは今後の通話のみです。

詳細情報

ファイル	内容
references/answer-types.md	自由記述と事前定義済みの値、検証パターン、それぞれの使いどころ。
references/copy-on-write.md	200 と 201 の更新フローをコード付きで解説します。
assets/sample_bulk_dispositions.json	すぐに使える営業電話分析パック。2 つのカテゴリに分かれた 6 つのディスポジションを収録。
assets/sample_transcripts.json	テスト用の 3 つのトランスクリプト（営業、サポート、予約）。
scripts/create_disposition.py	POST /dispositions/ をフラグ付きで実行します。
scripts/bulk_create_dispositions.py	JSON ファイルを使って POST /dispositions/bulk を実行します。
scripts/test_dispositions.py	サンプルのトランスクリプトに対して POST /v2/agent/{id}/dispositions/test を実行します。

レガシー：gpt_assistants.custom_questions

古いエージェント（および v1 ダッシュボードから移行された一部のエージェント）では、通話後の抽出ロジックが個別の disposition オブジェクトではなく、エージェント自体にインラインで記述されています。GET /v2/agent/{id} が次の内容を返す場合は、この形式です。

{
  "dispositions": null,
  "gpt_assistants": [
    {
      "assistant_id": "asst_f4sCpG4zASXIls0FMl7PkMMt",
      "custom_questions": "1. interested:\n[- What to Extract: User interest in becoming an expert\n- Expected Response: Yes or No]\n\n2. reason_not_interested:\n[- What to Extract: Reason stated by the user...\n- Expected Response: Short reason]\n\n3. full_name:\n..."
    }
  ]
}

項目	レガシー gpt_assistants	モダンな dispositions
保存場所	エージェント内の、自由記述の単一文字列	agent_ids を介してリンクされた個別の disposition オブジェクト
形式	番号付きリスト。抽出内容と期待される応答のヒントを自由記述	構造化形式：name、question、objective_options[]、subjective_type
検証	なし — LLM は解釈した内容をそのまま返します	型付き（timestamp、email、regex など）で、validation.is_valid フラグがあります
信頼度	なし	あり — confidence と confidence_label
エージェント間での再利用	なし — エージェントごとにコピーします	あり — 1 つの disposition を N 個のエージェントにリンクできます
結果の保存先	実行データの同じ extracted_data フィールド	実行データの同じ extracted_data フィールド

両方のシステムが共存します。 dispositions が設定されている場合は、それが実行されます。dispositions が null で、gpt_assistants[0].custom_questions に内容がある場合は、代わりにそちらが実行されます。実行データに含まれる出力構造は、どちらの場合も同じです。

移行： レガシーエージェントに「disposition を追加」するようユーザーから依頼された場合、通常は次の手順で行います。

1. 既存の custom_questions 文字列を解析します。意図する disposition ごとに、番号付きの項目が 1 つあります。
2. 各項目を構造化された disposition に変換します（POST /dispositions/）。
3. 新しい disposition がリンクされたら、どのシステムが出力を生成しているのかを明確にするため、必要に応じて gpt_assistants をクリアします。

モダンな機能を使うために移行は必須ではありません。ただし、信頼度スコア、型付き検証、共有 disposition を利用するには移行が必要です。

よくある注意点

• 曖昧な質問では信頼度が低くなります。「通話はどうでしたか？」は結果が不安定になります。「顧客はフォローアップミーティングに同意しましたか？同意した場合、日付はいつですか？」なら明確です。
• objective_options.condition は LLM の選択基準です。 人間のレビュアーに指示するつもりで記述してください。
• 1 つの disposition に多くの概念を詰め込まないでください。「見込み客の質と次のステップ」は、結果とアクションの 2 つの disposition に分けます。
• 適切な回答タイプを選んでください。 カテゴリ形式は is_objective、自由回答形式は is_subjective です。両方の場合は、両方のフラグを true にします（両方を使うと便利な disposition は多くあります）。
• 信頼度が 0.8 以上なら、一般的に信頼できます。 0.5 未満の場合は、手動で確認してください。CRM のルーティングには、生の文字起こしに基づくヒューリスティクスではなく、confidence_label を使用してください。
• リンクには agent_ids を使います。 agent_ids のない disposition は存在しますが、どのエージェントでも実行されません。新しい disposition をすべてリンクするには、一括作成が最も簡単です。

関連項目

• get-executions — 通話後に extracted_data を取得します。
• setup-webhook — 抽出結果をリアルタイムで受信します。
• create-agent — エージェントのトップレベル設定（Extractions は Analytics タブの機能です）。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md — extracted_data を含む構造。