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	Agent 提示词被标记为包含禁止内容	更新后的提示词截图及说明
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。

提交证据

使用 multipart 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 再次出现，请修复底层 Agent 或流程。

看到各类违规项时的修复方法

类型	可能的修复方法
calling_hours	正确设置 calling_guardrails.call_start_hour / call_end_hour（使用接收方的时区，而非你的时区）。
dnc_breach	将号码加入批量 CSV 之前，先对照 DNC 登记名单进行筛查。
content_policy	改写 Agent 提示词，移除禁止内容。重新保存以再次验证。
dlt_mismatch	完成 DLT / Header / Template 注册（https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md）。
consent_missing	拨打电话前获取明确的选择加入同意，并保存记录。
fraud_signal	主动联系支持团队 — Bolna 会需要了解合法用例的背景。

隐私与证据处理

• 证据可能包含个人身份信息（客户签名、证件）。请将上传内容视为敏感信息。
• 不要将证据文件提交到 git，也不要将内容粘贴到聊天记录中。请将文件保存在自己的安全存储中，并且仅通过 API 上传。
• 在你这边记录审计日志：为合规起见，在本地记录 violation_id、证据文件名哈希、提交者和时间戳。
• 不得伪造。 仅提交真实且注明日期的证据——虚假声明会导致违规升级处理。

深入了解

文件	内容
scripts/list_violations.py	封装 GET /violations/list，支持按状态、Agent 筛选和分页。
scripts/submit_violation_evidence.py	封装 POST /violations/submit，并上传 multipart 文件。

另请参阅

• get-executions — 提交前，获取违规调用的对话记录和原始日志以了解上下文。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md — DLT 前置要求，可防止出现 dlt_mismatch 标记。
• create-agent — 配置 calling_guardrails，以防止出现 calling_hours 标记。
• setup-inbound — 配置 whitelist_phone_numbers，以防止出现入站垃圾信息标记。