API 参考

将 Hanc.AI 集成到你的应用中的完整 API 文档。以编程方式管理代理、获取通话数据、发起通话，以及操作平台的每一个部分。

下面的每一节都会给出HTTP 方法和路径、参数（路径、查询和请求体）、一个可直接运行的示例请求，以及一个有代表性的示例响应，让你无需猜测负载结构即可完成集成。

快速概览


基础 URL	`https://api.hanc.ai`
版本前缀	所有路由均以 `/v1` 为前缀
认证	通过 `x-api-key` 头传递 API 密钥
格式	JSON（请求和响应）

在仪表板的 Integration → API Keys 中生成 API 密钥。每个用户最多可拥有 3 个密钥——有关设置、权限和安全指南，请参阅集成中的 API Keys 部分。

curl -X GET "https://api.hanc.ai/v1/agent/list" \
  -H "x-api-key: YOUR_API_KEY"

认证

在每个请求中通过 x-api-key 头发送你的密钥：

x-api-key: YOUR_API_KEY

密钥会解析为拥有它的用户，并且每个请求都会自动限定在该用户范围内——你永远不需要传递用户 ID。缺失或无效的密钥会被拒绝，返回 401 Unauthorized / 403 Forbidden。

提示

将密钥保存在服务器端。切勿将 API 密钥嵌入浏览器、移动应用或任何终端用户可以查看的客户端。如果密钥泄露，请在 Integration → API Keys 中吊销它并签发新密钥。

约定

有几条规则适用于整个 API。读一遍能为你节省调试时间：

版本前缀 — 每个路径都以 /v1 开头（例如 https://api.hanc.ai/v1/agent/list）。
ID 是 Mongo ObjectId — 任何 :id（以及 :agentActionId、:agentToolId 等）都必须是 24 个字符的十六进制字符串。格式错误的 ID 返回 400 Bad Request。
未知的请求体字段会被剥离 — API 会校验请求体，并静默丢弃它无法识别的属性，因此字段名中的拼写错误会被忽略而不是被存储。
日期 — 分析/导出端点接受 YYYY-MM-DD 格式的 date_from / date_to。date_to 为包含当天结束时刻。
数组查询参数 — 当某个筛选器接受多个值时（例如 agent_ids、direction），你可以重复该键（?direction=inbound&direction=outbound）或用逗号分隔（?direction=inbound,outbound）。
响应中的时间戳为纪元毫秒，除非显示为 ISO‑8601 字符串。

端点索引

一份关于所有可用内容的速览图。每个端点的详细文档见下文。

Calls（通话）

操作	方法	端点
列出通话	GET	`/v1/call/list`
通话详情（转录、情感、摘要）	GET	`/v1/call/:id`
综合分析（区间内的合计值）	GET	`/v1/call/general-metrics`
每日分析	GET	`/v1/call/daily-metrics`
情感统计	GET	`/v1/call/sentiment-stats`
成本明细	GET	`/v1/call/costs-breakdown`
导出通话（CSV）	GET	`/v1/call/list/export`
导出成本（CSV）	GET	`/v1/call/costs-breakdown/export`
发起电话通话	POST	`/v1/call/make-phone-call`
发起网页通话	POST	`/v1/call/make-web-call`

Agents（代理）

操作	方法	端点
列出代理	GET	`/v1/agent/list`
代理详情	GET	`/v1/agent/:id`
创建代理	POST	`/v1/agent`
更新代理	PATCH	`/v1/agent/:id`
删除代理	DELETE	`/v1/agent/:id`
代理通话统计	GET	`/v1/agent/:id/call-stats`
列出代理模板	GET	`/v1/agent/agent_template/list`
列出动作	GET	`/v1/agent/:id/actions`
添加动作	POST	`/v1/agent/:id/actions`
更新动作	PATCH	`/v1/agent/:id/actions/:agentActionId`
删除动作	DELETE	`/v1/agent/:id/actions/:agentActionId`
列出工具	GET	`/v1/agent/:id/tools`
添加工具	POST	`/v1/agent/:id/tools`
更新工具	PATCH	`/v1/agent/:id/tools/:agentToolId`
删除工具	DELETE	`/v1/agent/:id/tools/:agentToolId`

Knowledge Base（知识库）

操作	方法	端点
列出知识库	GET	`/v1/knowledge-base/list`
创建（含第一个文件）	POST	`/v1/knowledge-base`
添加单个文件	POST	`/v1/knowledge-base/:id/file`
添加多个文件	POST	`/v1/knowledge-base/:id/files`
删除文件	DELETE	`/v1/knowledge-base/:id/file`
分配代理	PUT	`/v1/knowledge-base/:id/agents`

Phone Numbers（电话号码）

操作	方法	端点
列出号码	GET	`/v1/phone-number/list`
可用号码（按国家/地区）	GET	`/v1/phone-number/available`
购买号码	POST	`/v1/phone-number/buy`
从 Twilio 导入	POST	`/v1/phone-number/import-twilio`
连接到 SIP	PATCH	`/v1/phone-number/connect-to-sip`

Voices · Subscription · Customers · Workspaces（语音·订阅·客户·工作区）

操作	方法	端点
列出语音	GET	`/v1/voice/list`
订阅详情	GET	`/v1/subscription`
配置自动充值	PATCH	`/v1/subscription/auto-top-up`
设置充值金额	PATCH	`/v1/subscription/top-up-amount`
列出客户	GET	`/v1/customer/list`
客户详情	GET	`/v1/customer/:id`
创建客户	POST	`/v1/customer`
更新客户	PATCH	`/v1/customer/:id`
删除客户	DELETE	`/v1/customer/:id`
列出工作区	GET	`/v1/workspaces/list`
创建工作区	POST	`/v1/workspaces`
工作区详情	GET	`/v1/workspaces/:id`
更新工作区	PATCH	`/v1/workspaces/:id`
删除工作区	DELETE	`/v1/workspaces/:id`
邀请成员	POST	`/v1/workspaces/:workspace_id/invite-member`
移除成员	DELETE	`/v1/workspaces/:workspace_id/remove-member`

Calls（通话）

管理和分析语音通话：列出并检查通话（转录、情感、摘要）、拉取聚合指标、导出 CSV 报告，以及发起外呼电话通话和网页通话。

列出通话

GET /v1/call/list

列出你账户下的通话，支持筛选、排序和分页。

查询参数

名称	类型	是否必需	说明
`agent_ids`	string[]	否	按一个或多个代理 ID 筛选（重复或逗号分隔）。
`agent_id`	string	否	按单个代理筛选（旧版；建议使用 `agent_ids`）。
`direction`	enum[]	否	`inbound` 和/或 `outbound`。
`call_status`	enum[]	否	`started`、`success`、`failed`、`pending`。
`call_type`	enum[]	否	`phone`、`web`。
`customer_id`	string	否	按客户筛选。
`workspace_id`	string	否	按工作区筛选。
`date_from` / `date_to`	string	否	区间筛选（`YYYY-MM-DD`）。
`sort_order`	enum	否	`asc` 或 `desc`。
`limit`	number	否	返回的最大结果数。
`skip`	number	否	跳过的结果数（分页偏移量）。

示例请求

curl -G "https://api.hanc.ai/v1/call/list" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "agent_ids=507f1f77bcf86cd799439042" \
  --data-urlencode "direction=inbound" \
  --data-urlencode "sort_order=desc" \
  --data-urlencode "limit=10"

示例响应 — 200 OK

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "call_type": "phone",
    "agent_id": "507f1f77bcf86cd799439042",
    "agent_name": "Customer Support Agent",
    "call_status": "success",
    "call_from": "+12345678900",
    "call_to": "+12345678911",
    "direction": "inbound",
    "start_timestamp": 1703302407333,
    "end_timestamp": 1703302428855,
    "recording_url": "https://recordings.example.com/12345",
    "disconnection_reason": "user_hangup",
    "sentiment": { "sentiment": "positive", "explanation": "Friendly, helpful tone." },
    "call_summary": "Customer issue resolved.",
    "task_achieved": true
  }
]

获取通话详情

GET /v1/call/:id

获取单通通话的完整详情——转录、情感、摘要、信用额度和性能指标。

路径参数

名称	类型	是否必需	说明
`id`	string	是	通话的 ID。

示例请求

curl "https://api.hanc.ai/v1/call/507f1f77bcf86cd799439011" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 200 OK

{
  "_id": "507f1f77bcf86cd799439011",
  "call_type": "phone",
  "agent_id": "507f1f77bcf86cd799439042",
  "agent_name": "Customer Support Agent",
  "call_status": "success",
  "call_from": "+12345678900",
  "call_to": "+12345678911",
  "direction": "inbound",
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "recording_url": "https://recordings.example.com/12345",
  "transcription": [
    { "speaker": "agent", "content": "Hello, how can I help?", "timestamp": 1703302407333 },
    { "speaker": "user", "content": "I need help with my order.", "timestamp": 1703302410000 }
  ],
  "sentiment": { "sentiment": "positive", "explanation": "Friendly, helpful tone." },
  "call_summary": "Customer issue resolved.",
  "task_achieved": true,
  "call_credits_details": {
    "phone_call_credits": 1,
    "web_call_credits": 0,
    "text_message_credits": 0,
    "call_forwarding_credits": 0
  }
}

如果通话不存在或不属于你的账户，则返回 404。

综合指标

GET /v1/call/general-metrics

某个日期范围内的合计值（通话数、总时长和平均时长）。

查询参数

名称	类型	是否必需	说明
`date_from`	string	是	开始日期（`YYYY-MM-DD`）。
`date_to`	string	是	结束日期（`YYYY-MM-DD`，包含）。
`agent_id` / `agent_ids`	string(s)	否	限定为一个或多个代理。
`customer_id`	string	否	按客户筛选。
`workspace_id`	string	否	按工作区筛选。
`direction` / `call_status` / `call_type`	enum[]	否	与列出通话相同的筛选器。

省略 date_from 或 date_to 会返回 400 Bad Request。

示例请求

curl -G "https://api.hanc.ai/v1/call/general-metrics" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31"

示例响应 — 200 OK

{ "total_calls": 128, "total_duration": 45230, "average_duration": 353 }

每日指标

GET /v1/call/daily-metrics

某个日期范围内每天的总通话时长——非常适合绘制趋势图。

查询参数 — 与综合指标相同（date_from/date_to 必需，外加可选的代理/客户/工作区/方向/状态/类型筛选器）。

示例请求

curl -G "https://api.hanc.ai/v1/call/daily-metrics" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-07"

示例响应 — 200 OK

[
  { "date": "2026-05-01", "total_duration": 5400 },
  { "date": "2026-05-02", "total_duration": 7320 },
  { "date": "2026-05-03", "total_duration": 0 }
]

情感统计

GET /v1/call/sentiment-stats

某个日期范围内、单个代理按情感分类的通话计数。

查询参数

名称	类型	是否必需	说明
`agent_id`	string	是	要报告的代理。
`date_from`	string	是	开始日期。
`date_to`	string	是	结束日期（包含）。

示例请求

curl -G "https://api.hanc.ai/v1/call/sentiment-stats" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "agent_id=507f1f77bcf86cd799439042" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31"

示例响应 — 200 OK

{ "positive": 84, "negative": 12, "neutral": 32 }

成本明细

GET /v1/call/costs-breakdown

按用户、代理或工作区分组的成本/用量明细（通话、分钟数、信用额度、令牌数、各模型详情）。

查询参数

名称	类型	是否必需	说明
`date_from`	string	是	开始日期。
`date_to`	string	是	结束日期（包含）。
`group_by`	enum	否	`user`（默认）、`agent` 或 `workspace`。
`customer_id`	string	否	按客户筛选（代理商权限）。
`workspace_id`	string	否	按工作区筛选。

示例请求

curl -G "https://api.hanc.ai/v1/call/costs-breakdown" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31" \
  --data-urlencode "group_by=agent"

示例响应 — 200 OK

{
  "breakdown": [
    {
      "agent_id": "507f1f77bcf86cd799439042",
      "agent_name": "Customer Support Agent",
      "total_calls": 64,
      "total_duration_minutes": 380,
      "credits": { "phone_call": 60, "web_call": 4, "text_message": 0, "call_forwarding": 1, "total": 65 },
      "tokens": { "input": 920000, "output": 120000, "total": 1040000 }
    }
  ],
  "totals": { "total_calls": 64, "total_duration_minutes": 380, "total_credits": 65, "total_tokens": 1040000 },
  "period": { "from": 1746057600000, "to": 1748735999999 }
}

导出通话（CSV）

GET /v1/call/list/export

将某个日期范围内的每通通话下载为 CSV 文件（含逐通、逐模型的令牌详情）。

查询参数

名称	类型	是否必需	说明
`date_from`	string	是	开始日期。
`date_to`	string	是	结束日期（包含）。

响应 — 一个 CSV 文件（Content-Type: text/csv），以名为 call-details_<date_from>_<date_to>.csv 的附件形式提供。

示例请求

curl -G "https://api.hanc.ai/v1/call/list/export" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31" \
  -o call-details.csv

导出成本（CSV）

GET /v1/call/costs-breakdown/export

将成本明细下载为 CSV 文件。

查询参数 — 与成本明细相同（date_from/date_to 必需；可选 group_by、customer_id、workspace_id）。

响应 — 一个以 costs-breakdown_<date_from>_<date_to>.csv 形式提供的 CSV 文件。

示例请求

curl -G "https://api.hanc.ai/v1/call/costs-breakdown/export" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31" \
  --data-urlencode "group_by=agent" \
  -o costs-breakdown.csv

发起电话通话

POST /v1/call/make-phone-call

从你的某个代理发起一通外呼电话。

请求体

字段	类型	是否必需	说明
`agent_id`	string	是	将发起通话的代理。
`from_number`	string	是	E.164 格式的主叫号码（例如 `+1234567890`）。
`to_number`	string	是	接收方电话号码。
`custom_data`	object	否	附加到通话的任意数据。
`dynamic_context`	object	否	传入对话的上下文（例如客户姓名）。

示例请求

curl -X POST "https://api.hanc.ai/v1/call/make-phone-call" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "507f1f77bcf86cd799439042",
    "from_number": "+1234567890",
    "to_number": "+19876543210",
    "dynamic_context": { "customer_name": "Jane", "order_id": "12345" }
  }'

示例响应 — 201 Created

{
  "_id": "507f1f77bcf86cd799439011",
  "call_type": "phone",
  "agent_id": "507f1f77bcf86cd799439042",
  "call_status": "started",
  "call_from": "+1234567890",
  "call_to": "+19876543210",
  "direction": "outbound",
  "start_timestamp": 1703302407333
}

发起网页通话

POST /v1/call/make-web-call

为你的某个代理创建一个浏览器/WebRTC 通话会话。

请求体

字段	类型	是否必需	说明
`agent_id`	string	是	将处理该网页通话的代理。
`custom_data`	object	否	附加到通话的任意数据。
`dynamic_context`	object	否	传入对话的上下文。

示例请求

curl -X POST "https://api.hanc.ai/v1/call/make-web-call" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "507f1f77bcf86cd799439042", "dynamic_context": { "topic": "billing" } }'

示例响应 — 201 Created

{
  "_id": "507f1f77bcf86cd799439077",
  "call_type": "web",
  "agent_id": "507f1f77bcf86cd799439042",
  "call_status": "started",
  "start_timestamp": 1703302407333
}

Agents（代理）

创建和管理语音代理、它们的动作（通话期间执行的操作——发送电子邮件/短信/WhatsApp、调用你的 API）以及它们的工具（能力，例如 RAG 搜索、预约、呼叫转接、日历/CRM 集成）。

列出代理

GET /v1/agent/list

返回你账户拥有的所有代理。

查询参数

名称	类型	是否必需	说明
`customer_id`	string	否	限定到某个客户。
`workspace_id`	string	否	限定到某个工作区。

示例请求

curl "https://api.hanc.ai/v1/agent/list" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "agent_name": "Customer Support Agent",
    "llm_id": "60d21b4667d0d8992e610c86",
    "voice": { "voice_id": "60d21b4667d0d8992e610c87" },
    "interruption_sensitivity": 1.0,
    "call_settings": { "language": "en-US", "sentiment_analysis": false, "call_summary": false },
    "status": "active",
    "workspace_id": "60d21b4667d0d8992e610c87",
    "knowledge_base": ["60d21b4667d0d8992e610c89"]
  }
]

获取单个代理

GET /v1/agent/:id

返回单个代理。

路径参数

名称	类型	是否必需	说明
`id`	string	是	代理 ID。

示例请求

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY"

返回代理对象（形状与列出代理中的单项相同），若未找到则返回 404。

创建代理

POST /v1/agent

创建一个新代理。仅 agent_name 和 llm_id 是必需的——其余均为可选，会回退到合理的默认值。

查询参数 — 可选的 customer_id、workspace_id，用于关联新代理。

请求体

字段	类型	是否必需	说明
`agent_name`	string	是	显示名称。
`llm_id`	string	是	支撑该代理的 LLM 的 ID。
`voice`	object	否	`{ "voice_id": "<id>" }`。
`interruption_sensitivity`	number	否	代理被打断时让步的容易程度（例如 `0.5`）。
`call_settings`	object	否	语言、提醒、静默超时、情感分析、通话摘要、`max_call_duration_minutes`（1–15）。
`data_retrieval`	object[]	否	代理在通话中收集的字段。
`webhook_url`	string	否	接收代理事件通知的 URL。
`is_data_collection_active`	boolean	否	启用数据收集表单。

示例请求

curl -X POST "https://api.hanc.ai/v1/agent" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Customer Support Agent",
    "llm_id": "507f1f77bcf86cd799439033",
    "voice": { "voice_id": "507f1f77bcf86cd799439035" },
    "interruption_sensitivity": 0.5,
    "call_settings": { "language": "en-US", "max_call_duration_minutes": 10 }
  }'

示例响应 — 201 Created（创建的代理对象）。

更新代理

PATCH /v1/agent/:id

部分更新一个代理。所有请求体字段均为可选——只发送你想更改的内容。

路径参数 — id（代理 ID）。

请求体 — 创建字段的任意子集，外加 folder、status（例如 active）、is_customer_memory_active、widget_settings、callback_settings。在 call_settings 内部，你还可以设置 recording_enabled、stt_languages（最多 4 个 BCP‑47 代码）和 max_call_duration_minutes。

示例请求

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_name": "Support Agent v2", "call_settings": { "language": "en-GB", "recording_enabled": false } }'

示例响应 — 200 OK（更新后的代理对象）。

删除代理

DELETE /v1/agent/:id

删除一个代理。

示例请求

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 204 No Content（空响应体）。

代理通话统计

GET /v1/agent/:id/call-stats

某个日期范围内、单个代理每天的通话计数。

路径参数 — id（代理 ID）。

查询参数

名称	类型	是否必需	说明
`date_from`	string	是	开始日期（`YYYY-MM-DD`）。
`date_to`	string	是	结束日期（`YYYY-MM-DD`）。

示例请求

curl -G "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/call-stats" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31"

示例响应 — 200 OK

[
  { "date": "2026-05-28", "total_calls": 10 },
  { "date": "2026-05-29", "total_calls": 4 }
]

列出代理模板

GET /v1/agent/agent_template/list

返回你可以克隆的预构建代理模板目录。无参数。

示例请求

curl "https://api.hanc.ai/v1/agent/agent_template/list" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "icon_url": "https://example.com/icon.png",
    "description": "A ready-made receptionist agent.",
    "agent": { "agent_name": "Receptionist", "call_settings": { "language": "en-US" } },
    "llm": { "model": "gpt-4o-mini", "begin_message": "Hello, how can I assist you today?" }
  }
]

代理动作

动作是代理在通话期间执行的事情。支持的 action_type 值：send_email、send_sms、send_whatsapp、api_call。settings 对象的形状取决于类型。

列出动作

GET /v1/agent/:id/actions

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions" \
  -H "x-api-key: YOUR_API_KEY"

返回一个动作对象数组。

添加动作

POST /v1/agent/:id/actions

请求体

字段	类型	是否必需	说明
`action_type`	enum	是	`send_email`、`send_sms`、`send_whatsapp` 或 `api_call`。
`settings`	object	是	与类型相关的配置。
`is_active`	boolean	否	默认为 `true`。

示例请求

curl -X POST "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "send_email",
    "settings": {
      "name": "Welcome Email",
      "subject": "Welcome!",
      "message": "Thank you for joining us.",
      "direct_recipients": ["user@example.com"]
    }
  }'

示例响应 — 201 Created

{
  "_id": "60f5b1a8d1b9f7c1d0c0a6c6",
  "agent_id": "60d21b4667d0d8992e610c85",
  "action_type": "send_email",
  "settings": { "name": "Welcome Email", "subject": "Welcome!", "message": "Thank you for joining us.", "direct_recipients": ["user@example.com"] },
  "is_active": true
}

更新动作

PATCH /v1/agent/:id/actions/:agentActionId

更新已附加动作的 settings 和/或 is_active。两个请求体字段均为可选。

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions/60f5b1a8d1b9f7c1d0c0a6c6" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

返回 200 OK 及更新后的动作对象。

删除动作

DELETE /v1/agent/:id/actions/:agentActionId

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions/60f5b1a8d1b9f7c1d0c0a6c6" \
  -H "x-api-key: YOUR_API_KEY"

返回 204 No Content。

代理工具

工具赋予代理额外的能力。支持的 tool_type 值：api_rag、appointment_booking、call_forwarding、end_call、google_calendar、outlook_calendar、etermin、resmio、hubspot_crm、agent_transfer、mcp。settings 对象的形状取决于类型。

etermin 和 resmio 是实时的预约/预订工具：代理会直接在已连接的 eTermin 或 resmio 账户中检查可用性并预订、改期或取消。两者都需要先在账户上连接相应的集成。

列出工具

GET /v1/agent/:id/tools

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools" \
  -H "x-api-key: YOUR_API_KEY"

返回一个工具对象数组。

添加工具

POST /v1/agent/:id/tools

请求体

字段	类型	是否必需	说明
`tool_type`	enum	是	上述支持的工具类型之一。
`settings`	object	是	与类型相关的配置。
`is_active`	boolean	否	默认为 `true`。

示例请求

curl -X POST "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_type": "call_forwarding",
    "settings": { "name": "Transfer to human", "phone_number": "+1234567890" }
  }'

示例响应 — 201 Created

{
  "_id": "60f5b1a8d1b9f7c1d0c0a6c6",
  "agent_id": "60d21b4667d0d8992e610c85",
  "tool_type": "call_forwarding",
  "settings": { "name": "Transfer to human", "phone_number": "+1234567890" },
  "is_active": true
}

更新工具

PATCH /v1/agent/:id/tools/:agentToolId

更新已附加工具的 settings 和/或 is_active（均为可选）。

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools/60f5b1a8d1b9f7c1d0c0a6c6" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

返回 200 OK 及更新后的工具对象。

删除工具

DELETE /v1/agent/:id/tools/:agentToolId

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools/60f5b1a8d1b9f7c1d0c0a6c6" \
  -H "x-api-key: YOUR_API_KEY"

返回 204 No Content。

Knowledge Base（知识库）

上传你的代理可在通话期间搜索的文档，并控制哪些代理使用各个知识库。文件上传使用 multipart/form-data。

列出知识库

GET /v1/knowledge-base/list

查询参数 — 可选的 customer_id、workspace_id。

curl "https://api.hanc.ai/v1/knowledge-base/list" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "knowledge_base_name": "Company Policies",
    "knowledge_base_description": "Refund, shipping and warranty policies.",
    "files": [
      { "_id": "60d21b4667d0d8992e610c90", "file_name": "policies.pdf", "file_size": 2048000, "uploaded_at": "2026-05-24T07:34:23.980Z" }
    ],
    "agent_names": ["Sales Agent", "Support Bot"]
  }
]

创建知识库

POST /v1/knowledge-base

创建一个知识库并同时上传其第一个文件。这是一个 multipart/form-data 请求——不存在仅含请求体的"创建"方式。

查询参数 — 可选的 customer_id、workspace_id。

表单字段

字段	类型	是否必需	说明
`file`	file	是	第一个文档（例如一个 PDF）。
`name`	string	是	知识库名称（1–100 个字符）。
`description`	string	是	描述（1–300 个字符）。
`folder`	string	否	文件夹/分类标签（0–50 个字符）。

示例请求

curl -X POST "https://api.hanc.ai/v1/knowledge-base" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./policies.pdf" \
  -F "name=Company Policies" \
  -F "description=Refund, shipping and warranty policies." \
  -F "folder=Sales"

示例响应 — 200 OK（创建的知识库，形状与列表项相同）。

添加单个文件

POST /v1/knowledge-base/:id/file

向现有知识库添加一个文件。Multipart 字段名：file。

curl -X POST "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/file" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./addendum.pdf"

返回 200 OK 及更新后的知识库。

添加多个文件

POST /v1/knowledge-base/:id/files

一次性添加多个文件。Multipart 字段名：files（每个文件重复一次）。可选的 customer_id、workspace_id 查询参数。

curl -X POST "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/files" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "files=@./doc1.pdf" \
  -F "files=@./doc2.pdf"

返回 200 OK 及更新后的知识库。

删除文件

DELETE /v1/knowledge-base/:id/file

按 ID 移除一个或多个文件。尽管路径是单数形式，请求体接受一个数组。

请求体

字段	类型	是否必需	说明
`file_ids`	string[]	是	要删除的文件 ID 的非空数组。

curl -X DELETE "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/file" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_ids": ["60c72b2f9b1e8b001c8e4d3a", "60c72b2f9b1e8b001c8e4d3b"] }'

返回 200 OK。

分配代理

PUT /v1/knowledge-base/:id/agents

设置（替换）使用该知识库的完整代理列表。

请求体

字段	类型	是否必需	说明
`agent_ids`	string[]	是	应使用该知识库的代理 ID。

curl -X PUT "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/agents" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_ids": ["60d21b4667d0d8992e610c85"] }'

返回 200 OK。

Phone Numbers（电话号码）

列出你的号码、查找可购买的号码、购买号码、从已连接的 Twilio 账户导入号码，或将号码连接到 SIP 中继。

在仪表板中购买号码

仪表板中的号码购买功能超出了这些端点所暴露的范围。在奥地利、德国、瑞士、美国和加拿大可获得即时、无需材料的号码；其他所有国家/地区都使用引导式自助流程，你需提交自己的监管文件（并可将其保存为草稿以便稍后继续）。购买界面提供本地、移动、全国和免费类型——外加高级号码（+€2/月）和 WhatsApp 通话号码。BYO SIP 是厂商中立的（sipgate、Placetel、TENIOS、easybell、Zadarma、Telnyx、自定义中继——不仅限于 Twilio 导入）。完整流程请参阅电话号码。

列出电话号码

GET /v1/phone-number/list

查询参数 — 均为可选：inbound_agent_id、outbound_agent_id、customer_id、workspace_id（以及 user_id，默认为你自己）。

curl "https://api.hanc.ai/v1/phone-number/list" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "phone_number": "+1234567890",
    "formatted_number": "+1 (234) 567-8900",
    "country": "US",
    "provider": "twilio",
    "status": "active",
    "inbound_agent_id": "64bfb7b3f3d9ab3f1e2c109c",
    "inbound_agent_name": "Receptionist"
  }
]

可用号码

GET /v1/phone-number/available

列出某个国家/地区可购买的号码。

查询参数

名称	类型	是否必需	说明
`country_code`	string	否	ISO 国家/地区代码（默认 `US`），例如 `DE`、`AT`、`CH`。
`area_code`	string	否	数字区号筛选。

curl -G "https://api.hanc.ai/v1/phone-number/available" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "country_code=US" \
  --data-urlencode "area_code=415"

示例响应 — 200 OK

[
  { "phone_number": "+14155550100", "formatted_number": "+1 (415) 555-0100", "country": "US", "area_code": "415", "setup_fee": 2, "subscription": 2, "currency": "EUR" }
]

购买号码

POST /v1/phone-number/buy

购买一个特定号码。可选的 customer_id、workspace_id 查询参数。

请求体

字段	类型	是否必需	说明
`phone_number`	string	是	要购买的号码（E.164）。
`country_code`	string	是	号码所属国家/地区（例如 `US`）。

curl -X POST "https://api.hanc.ai/v1/phone-number/buy" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100", "country_code": "US" }'

示例响应 — 200 OK

{
  "message": "Phone number purchased successfully!",
  "phone_number": { "_id": "507f1f77bcf86cd799439011", "phone_number": "+14155550100", "country": "US", "provider": "twilio", "status": "active" }
}

从 Twilio 导入

POST /v1/phone-number/import-twilio

从已连接的 Twilio 账户导入号码。可选的 customer_id、workspace_id 查询参数。

请求体

字段	类型	是否必需	说明
`sid`	string	是	Twilio 账户 SID（`AC…`）。

curl -X POST "https://api.hanc.ai/v1/phone-number/import-twilio" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }'

示例响应 — 200 OK（导入的电话号码记录）。

连接到 SIP

PATCH /v1/phone-number/connect-to-sip

将一个现有号码连接到 SIP 中继。

请求体

字段	类型	是否必需	说明
`phone_number`	string	是	要连接的号码（E.164）。

curl -X PATCH "https://api.hanc.ai/v1/phone-number/connect-to-sip" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+1234567890" }'

返回 200 OK（空响应体）。

Voices（语音）

列出语音

GET /v1/voice/list

列出可用的语音。可按语言或提供商筛选，并包含某个客户的私有克隆语音。

查询参数

名称	类型	是否必需	说明
`language`	string	否	按语言筛选，例如 `?language=de`。
`provider`	string	否	`11-Labs`、`openai`、`qwen` 或 `azure`。
`customer_id`	string	否	同时包含该客户的私有语音克隆。

curl -G "https://api.hanc.ai/v1/voice/list" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "language=de"

示例响应 — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "voice_id": "voice_12345",
    "name": "Emma",
    "gender": "female",
    "accent": "British",
    "languages": ["english", "spanish"],
    "provider": "11-Labs",
    "sample_url": "https://example.com/sample.mp3"
  }
]

Subscription（订阅）

订阅详情

GET /v1/subscription

返回你当前的订阅，包括信用额度余额和充值设置。

curl "https://api.hanc.ai/v1/subscription" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 200 OK

{
  "_id": "507f191e810c19729de860ea",
  "payment_plan_id": "507f191e810c19729de860ec",
  "currency": "EUR",
  "package_credits": 1000,
  "package_credits_used": 100,
  "auto_top_up_enabled": false,
  "top_up_amount": 50,
  "extra_credits_payed": 1000,
  "extra_credits_used": 100,
  "billing_cycle": "monthly",
  "next_credit_reset": "2026-06-15T03:00:00.000Z",
  "is_cancelled": false
}

如果不存在订阅记录，则返回 404。

配置自动充值

PATCH /v1/subscription/auto-top-up

启用或禁用自动信用额度充值。

请求体

字段	类型	是否必需	说明
`enabled`	boolean	是	打开或关闭自动充值。
`amount`	number	否	充值的金额（20–1000）。启用时设置。

curl -X PATCH "https://api.hanc.ai/v1/subscription/auto-top-up" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "amount": 50 }'

返回 200 OK 及更新后的订阅。

设置充值金额

PATCH /v1/subscription/top-up-amount

更新已配置的充值金额。

请求体

字段	类型	是否必需	说明
`top_up_amount`	number	是	新金额（1–100）。

curl -X PATCH "https://api.hanc.ai/v1/subscription/top-up-amount" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "top_up_amount": 10 }'

返回 200 OK 及更新后的订阅。

Customers（客户）

管理你代理商下的客户。这些端点要求你的账户隶属于某个代理商。

列出客户

GET /v1/customer/list

curl "https://api.hanc.ai/v1/customer/list" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "email": "customer@example.com",
    "name": "John Doe",
    "account_status": "active",
    "agents_count": 3
  }
]

客户详情

GET /v1/customer/:id

curl "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY"

返回客户对象，若未找到则返回 404。

创建客户

POST /v1/customer

请求体

字段	类型	是否必需	说明
`email`	string	是	客户登录邮箱。
`initial_password`	string	是	初始密码（8–128 个字符）。
`name`	string	是	账户/公司名称。
`user_full_name`	string	是	客户用户的全名。
`visibility`	object	否	各板块的可见性标志。
`opt_out_promotions`	boolean	否	让该客户退出促销消息。

curl -X POST "https://api.hanc.ai/v1/customer" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "initial_password": "Password123!",
    "name": "Acme Co.",
    "user_full_name": "John Doe"
  }'

返回 201 Created 及新客户。若邮箱已存在或你的账户不隶属于某个代理商，则返回 400。

更新客户

PATCH /v1/customer/:id

请求体 — 均为可选：name、email、phone、address。

curl -X PATCH "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corporation", "phone": "+1234567890" }'

返回 200 OK 及更新后的客户。

删除客户

DELETE /v1/customer/:id

curl -X DELETE "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY"

示例响应

{ "message": "Customer deleted successfully" }

Workspaces（工作区）

将代理、号码和知识库归入工作区，并管理它们的成员。

列出工作区

GET /v1/workspaces/list

可选的 customer_id 查询参数。

curl "https://api.hanc.ai/v1/workspaces/list" \
  -H "x-api-key: YOUR_API_KEY"

示例响应 — 200 OK

[
  {
    "_id": "64b1f2d2f3d92c5b8c5e1e22",
    "name": "Workspace A",
    "description": "For the A team.",
    "owner_user_id": "64b1f2d2f3d92c5b8c5e1e10",
    "members": [
      { "user_id": "64b1f2d2f3d92c5b8c5e1e11", "full_name": "John Doe", "email": "john.doe@example.com" }
    ]
  }
]

创建工作区

POST /v1/workspaces

请求体

字段	类型	是否必需	说明
`name`	string	是	工作区名称（2–100 个字符）。
`description`	string	否	描述（0–500 个字符）。

curl -X POST "https://api.hanc.ai/v1/workspaces" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Development Team", "description": "For the dev team." }'

返回 201 Created 及工作区。

工作区详情

GET /v1/workspaces/:id

curl "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
  -H "x-api-key: YOUR_API_KEY"

返回工作区对象。

更新工作区

PATCH /v1/workspaces/:id

请求体 — name（2–100）和/或 description（0–500）。

curl -X PATCH "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renamed Workspace" }'

返回 200 OK 及更新后的工作区。

删除工作区

DELETE /v1/workspaces/:id

curl -X DELETE "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
  -H "x-api-key: YOUR_API_KEY"

示例响应

{ "message": "Workspace deleted successfully" }

邀请成员

POST /v1/workspaces/:workspace_id/invite-member

请求体

字段	类型	是否必需	说明
`email`	string	是	要邀请的用户的邮箱。

curl -X POST "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22/invite-member" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "teammate@example.com" }'

返回 201 Created 及工作区（新成员会出现在 members 中）。

移除成员

DELETE /v1/workspaces/:workspace_id/remove-member

请求体

字段	类型	是否必需	说明
`email`	string	是	要移除的成员的邮箱。

curl -X DELETE "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22/remove-member" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "teammate@example.com" }'

返回 200 OK 及更新后的工作区。

API 无法使用的功能

有些操作只能通过仪表板完成：

功能	原因
API 密钥管理	安全——密钥无法创建其他密钥
电话号码设置	需要交互式设置
Google Calendar 集成	需要交互式授权
计费与支付	通过仪表板管理

需要帮助？

如有 API 相关问题，请通过 support@hanc.ai 联系我们的支持团队。

快速概览​

认证​

约定​

端点索引​

Calls（通话）​

Agents（代理）​

Knowledge Base（知识库）​

Phone Numbers（电话号码）​

Voices · Subscription · Customers · Workspaces（语音·订阅·客户·工作区）​

Calls（通话）

列出通话​

获取通话详情​

综合指标​

每日指标​

情感统计​

成本明细​

导出通话（CSV）​

导出成本（CSV）​

发起电话通话​

发起网页通话​

Agents（代理）

列出代理​

获取单个代理​

创建代理​

更新代理​

删除代理​

代理通话统计​

列出代理模板​

代理动作​

列出动作​

添加动作​

更新动作​

删除动作​

代理工具​

列出工具​

添加工具​

更新工具​

删除工具​

Knowledge Base（知识库）

列出知识库​

创建知识库​

添加单个文件​

添加多个文件​

删除文件​

分配代理​

Phone Numbers（电话号码）

列出电话号码​

可用号码​

购买号码​

从 Twilio 导入​

连接到 SIP​

Voices（语音）

列出语音​

Subscription（订阅）

订阅详情​

配置自动充值​

设置充值金额​

Customers（客户）

列出客户​

客户详情​

创建客户​

更新客户​

删除客户​

Workspaces（工作区）

列出工作区​

创建工作区​

工作区详情​

更新工作区​

删除工作区​

邀请成员​

移除成员​

API 无法使用的功能​

需要帮助？​

快速概览

认证

约定

端点索引

Calls（通话）

Agents（代理）

Knowledge Base（知识库）

Phone Numbers（电话号码）

Voices · Subscription · Customers · Workspaces（语音·订阅·客户·工作区）

列出通话

获取通话详情

综合指标

每日指标

情感统计

成本明细

导出通话（CSV）

导出成本（CSV）

发起电话通话

发起网页通话

列出代理

获取单个代理

创建代理

更新代理

删除代理

代理通话统计

列出代理模板

代理动作

列出动作

添加动作

更新动作

删除动作

代理工具

列出工具

添加工具

更新工具

删除工具

列出知识库

创建知识库

添加单个文件

添加多个文件

删除文件

分配代理

列出电话号码

可用号码

购买号码

从 Twilio 导入

连接到 SIP

列出语音

订阅详情

配置自动充值

设置充值金额

列出客户

客户详情

创建客户

更新客户

删除客户

列出工作区

创建工作区

工作区详情

更新工作区

删除工作区

邀请成员

移除成员

API 无法使用的功能

需要帮助？