manage-violations

Bolna 違反

違反とは、コンテンツポリシー、規制ルール、または不正検知ヒューリスティックに抵触する可能性のある通話に対して、Bolna が発するフラグです。各違反にはステータス（open / under-review / resolved / rejected）があり、証拠を添付できます。API を使用して、フラグを監視し、対応してください。

エンドポイント

メソッド	パス	用途
GET	/violations/list	違反を一覧表示します（ページネーション、ステータスで絞り込み可能）
POST	/violations/submit	違反に対する証拠ファイルとコメントを送信します

認証：Authorization: Bearer $BOLNA_API_KEY。

違反オブジェクト

{
  "id": "vio_01HQXYZ123",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "execution_id": "exec_abc123",
  "status": "open",
  "violation_type": "calling_hours",
  "description": "Call placed at 22:45 IST to +91XXXXXXXXXX — outside TRAI calling hours.",
  "evidence_required": true,
  "created_at": "2026-05-18T22:45:00Z",
  "due_by": "2026-05-25T22:45:00Z"
}

フィールド	備考
status	open、under_review、resolved、rejected。
violation_type	Bolna のカテゴリ。例：calling_hours、dnc_breach、content_policy、dlt_mismatch、consent_missing、fraud_signal。
evidence_required	自動的に解決されるフラグもあれば、証拠の提出が必要なものもあります。
due_by	違反が自動的にエスカレーションされる前に証拠を提出する期限です。

一般的な違反の種類

種類	発生条件	一般的な証拠
calling_hours	許可された時間帯外に発信した	免除を示す顧客の同意記録、または修正済みの calling_guardrails の証明
dnc_breach	電話勧誘拒否登録簿に登録された番号に発信した	発信時点でその番号が登録されていなかったことを示す DNC 照合ログ
content_policy	エージェントのプロンプトが禁止コンテンツとしてフラグ付けされた	更新後のプロンプトのスクリーンショットと説明
dlt_mismatch	DLT の承認なしにインドの 140/160 を使用した	DLT 承認証明書 / Header URN
consent_missing	通話に対する同意の記録がない	オプトイン記録（フォーム送信、署名済み契約書）
fraud_signal	通話パターンが通常と異なる（大量発信、なりすましヒューリスティック）	業務上の説明と CRM レコードのサンプル

違反の一覧表示

# All open violations, page 1
curl "https://api.bolna.ai/violations/list?status=open&page_number=1&page_size=20" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

# Everything for a specific agent
curl "https://api.bolna.ai/violations/list?agent_id=$AGENT_ID" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

レスポンスのエンベロープは標準的なページネーション形式（total、has_more、data）に従います。has_more == false になるまでループしてください。

証拠の提出

ファイルと任意のコメントを含むマルチパート POST です。

curl -X POST https://api.bolna.ai/violations/submit \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -F 'violation_id=vio_01HQXYZ123' \
  -F 'file=@/path/to/evidence.pdf' \
  -F 'comment=Customer signed our consent form on 2026-05-10 — attached.'

フォームフィールド	必須	備考
violation_id	はい	/violations/list の id。
file	通常は必須	証拠を含む PDF、画像、または文書。
comment	任意	Bolna のコンプライアンス審査で表示される簡潔な説明。

レスポンスで受理が確認され、ステータスは under_review に移行します。

運用ワークフロー

1. GET /violations/list?status=open を毎日または毎週ポーリングし、新しいフラグを確認します。
2. violation_type に基づいてトリアージします。カテゴリごとに担当チームが異なります（法務、運用、エンジニアリングなど）。
3. 関連する実行と生ログを取得して、状況を確認します：GET /executions/{execution_id}。
4. 自社システムから証拠を収集します（CRM のエクスポート、同意フォーム、プロンプトのスクリーンショット）。
5. due_by までに POST /violations/submit で提出します。
6. Bolna の審査を待ち、ステータスが resolved または rejected に移行するのを確認します。
7. パターンを追跡します。同じ violation_type が再発する場合は、根本原因となっているエージェントやプロセスを修正します。

各種類の違反が発生した場合の修正方法

種類	考えられる修正
calling_hours	calling_guardrails.call_start_hour / call_end_hour を正しく設定します（自分のタイムゾーンではなく、受信者のタイムゾーンを使用）。
dnc_breach	バッチ CSV に追加する前に、DNC 登録簿と照合します。
content_policy	禁止コンテンツを削除するよう、エージェントのプロンプトを書き直します。再検証のために保存し直してください。
dlt_mismatch	DLT / Header / Template の登録を完了します（https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md）。
consent_missing	発信前に明示的なオプトインを取得し、その記録を保存します。
fraud_signal	事前にサポートへ問い合わせてください。Bolna は正当なユースケースの詳細を確認する必要があります。

プライバシーと証拠の取り扱い

• 証拠には個人識別情報（PII）が含まれる場合があります（顧客の署名、IDなど）。アップロードは機密情報として扱ってください。
• 証拠ファイルを git にコミットしたり、内容をチャットログに貼り付けたりしないでください。 ご自身の安全な保管場所に保管し、API 経由でのみアップロードしてください。
• お客様側で監査ログを記録してください：コンプライアンス対応のため、violation_id、証拠ファイル名のハッシュ、提出者、タイムスタンプをローカルに記録してください。
• 捏造しないでください。 実際に存在する日付入りの証拠のみを提出してください。虚偽の申告は違反の重大化につながります。

詳細

ファイル	内容
scripts/list_violations.py	ステータス、エージェント、ページネーションを指定して GET /violations/list をラップします。
scripts/submit_violation_evidence.py	マルチパートのファイルアップロードを使用して POST /violations/submit をラップします。

関連項目

• get-executions — 提出前に、問題のある呼び出しのトランスクリプトと生ログを取得して状況を確認します。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md — dlt_mismatch フラグを防ぐための DLT 前提条件です。
• create-agent — calling_hours フラグを防ぐための calling_guardrails です。
• setup-inbound — 着信スパムのフラグを防ぐための whitelist_phone_numbers です。