公共 API 参考
工单、消息与动作的端点、scopes 和示例。
使用带 scopes 的 API 密钥，从你的系统管理全渠道工单与动作。
基础 URL
所有请求通过公共网关。
https://api.threada.ai认证
- 在 `X-Api-Key` 头中发送 API 密钥。
- 在 Admin → API keys 中创建并轮换密钥；每个集成一把密钥。
- 密钥按租户隔离，并通过 scopes 实现最小权限。
Scopes
- `support.read` — 列出并获取工单、消息和动作。
- `support.write` — 创建/更新工单并追加消息。
- `support.actions` — 执行动作并查询状态。
分页
- 列表端点接受 `limit` 和 `page_token`。
- 将 `next_page_token` 传入下一次请求。
错误
- 错误返回 `{ error: { type, message, code } }`。
- HTTP 状态码与 `code` 值一致。
请求与响应示例
列出工单
获取所有渠道的未关闭工单。
请求
curl -X GET "https://api.threada.ai/api/v1/public/tickets?limit=25" \
-H "X-Api-Key: YOUR_API_KEY" 响应
{
"items": [
{
"ticket_id": "TICKET_ID",
"tenant_id": "TENANT_ID",
"subject": "SUBJECT",
"status": "open",
"priority": "normal",
"channel": "email",
"tags": ["vip", "returns"],
"last_message_at": "2026-02-04T18:32:11Z"
}
],
"next_page_token": "NEXT_PAGE_TOKEN"
}创建工单
以初始消息创建新工单。
请求
curl -X POST "https://api.threada.ai/api/v1/public/tickets" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": "SUBJECT",
"priority": "normal",
"channel": "email",
"contact": {
"name": "CUSTOMER_NAME",
"email": "customer@example.com"
},
"tags": ["returns"],
"initial_message": {
"role": "user",
"content": "MESSAGE_BODY",
"external_message_id": "EXT_MSG_ID"
}
}' 响应
{
"ticket": {
"summary": {
"ticket_id": "TICKET_ID",
"tenant_id": "TENANT_ID",
"subject": "SUBJECT",
"status": "open",
"priority": "normal",
"channel": "email",
"tags": ["returns"],
"created_at": "2026-02-04T18:32:11Z"
},
"contact": {
"name": "CUSTOMER_NAME",
"email": "customer@example.com"
},
"messages": [
{
"message_id": "MESSAGE_ID",
"role": "user",
"content": "MESSAGE_BODY",
"channel": "email",
"created_at": "2026-02-04T18:32:11Z"
}
]
}
}执行动作
为工单触发自定义 HTTP 自动化。
请求
curl -X POST "https://api.threada.ai/api/v1/public/tickets/TICKET_ID/actions" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payload": {
"type": "custom_http",
"method": "POST",
"url": "/hooks/zapier",
"headers": {
"X-Source": "threada"
},
"body_json": "{\"event\":\"ticket_updated\"}"
}
}' 响应
{
"action": {
"action_id": "ACTION_ID",
"tenant_id": "TENANT_ID",
"ticket_id": "TICKET_ID",
"action_type": "custom_http",
"status": "succeeded",
"requested_by": "api_key:API_KEY_ID",
"payload": {
"type": "custom_http",
"method": "POST",
"url": "/hooks/zapier",
"headers": {
"X-Source": "threada"
},
"body_json": "{\"event\":\"ticket_updated\"}"
}
}
}