Tiledesk REST API 详解

一、API 基础

1.1 端点基础

Tiledesk REST API 以 /v3 为版本前缀，所有请求和响应使用 JSON 格式。

环境	基础 URL
自部署	`http://<your-server>:8081/api`
Tiledesk Cloud	`https://api.tiledesk.com/v3`

💡 自部署环境的 API 通过统一反代暴露在 /api/ 路径下，完整 URL 为 http://<server>:8081/api/v3/<resource>。Cloud 环境直接在域名根下暴露。

1.2 Project ID

绝大多数 API 需要在路径中携带 {project_id} 来标识所属项目（租户）。获取方式：

Dashboard 任意页面 URL 中 /project/ 后的那串字符串
Project Settings 页面顶部

格式示例：5df2240cecd41b00173a06bb

1.3 认证方式

方式一：Basic Auth（简单直接）

curl -u 'admin@tiledesk.com:superadmin' \
  http://localhost:8081/api/v3/projects/5df2240cecd41b00173a06bb/users

适合脚本和简单集成。邮箱密码明文放在 URL 里。

方式二：JWT Token（推荐，生产安全）

第一步：用邮箱密码换取 JWT

curl -X POST http://localhost:8081/api/v3/auth/signin \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "admin@tiledesk.com",
    "password": "superadmin"
  }'

响应：

{
  "success": true,
  "token": "JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "_id": "5ab11c6b83dc240014d46095",
    "email": "admin@tiledesk.com"
  }
}

第二步：用 JWT 调用 API

curl http://localhost:8081/api/v3/projects/5df2240cecd41b00173a06bb/users \
  -H 'Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

JWT Token 有效期默认 7 天，续期重新调用 signin 即可。

方式三：匿名认证（访客端）

访客 widget 自动完成的认证，也可以通过 API 手动触发：

curl -X POST http://localhost:8081/api/v3/auth/signinAnonymously \
  -H 'Content-Type: application/json' \
  -d '{
    "id_project": "5df2240cecd41b00173a06bb",
    "firstname": "访客",
    "lastname": "游客"
  }'

1.4 角色与权限

角色	权限
Guest	匿名访客，只能发消息
User	已认证访客（通过自定义 JWT 登录）
Agent	坐席，可以回复会话
Admin	管理员，管理项目、坐席、Bot
Owner	项目创建者，最高权限

API 文档中每个端点标注的 Minimum role 是调用该接口所需的最低角色。

1.5 速率限制

默认上限：约 200 请求/分钟
超过限制返回 HTTP 429 Too Many Requests
Cloud 版根据订阅等级可能更高；自部署版无强制速率限制但 server 可能过载

1.6 请求格式

所有 POST/PUT 请求必须带 Content-Type: application/json：

curl -X POST ... \
  -H 'Content-Type: application/json' \
  -d '{"key": "value"}'

1.7 响应格式

成功返回 2xx 状态码 + JSON；失败返回 4xx + 错误说明。时间戳使用 UTC ISO-8601 格式。

二、认证 API

2.1 邮箱密码登录

POST /v3/auth/signin

请求体：

{
  "email": "agent@company.com",
  "password": "secure_password"
}

2.2 匿名登录

POST /v3/auth/signinAnonymously

请求体：

{
  "id_project": "<项目ID>",
  "firstname": "访客名",
  "lastname": "访客姓",
  "email": "optional@email.com",
  "attributes": {}
}

2.3 自定义 Token 登录

外部系统生成 JWT 后，访客可凭此 token 登录：

POST /v3/auth/signinWithCustomToken

请求头：Authorization: JWT <自定义JWT>

三、项目管理 API

3.1 列出用户所属全部项目

GET /v3/projects/

最低角色：user

curl -H 'Authorization: JWT <token>' \
  http://localhost:8081/api/v3/projects/

响应包含 project_id、name、status、channels（已开通渠道）等字段。

3.2 获取项目详情

GET /v3/projects/{project_id}

最低角色：agent

返回项目配置、operatingHours、widget 外观设置等完整信息。

3.3 获取可用坐席

GET /v3/projects/{project_id}/users/availables

返回当前在线、在工作时段内的坐席列表，用于智能路由。

查询参数：

raw=true：只考虑在线状态，忽略工作时段

3.4 检查项目当前是否开放

GET /v3/projects/{project_id}/isopen

根据项目设置的工作时段，返回 {"isopen": true/false}。

PUT /v3/projects/{project_id}/availables

请求体：

{
  "widget": {
    "logoChat": "https://your-site.com/logo.png",
    "themeColor": "#76528B",
    "themeForegroundColor": "#CBCE91",
    "align": "right",
    "displayOnDesktop": true,
    "displayOnMobile": true,
    "singleConversation": false
  }
}

四、会话与消息 API

💡 技术拓展：Tiledesk 的「会话」在 API 中称为 request（请求），每条消息都属于某个 request。request_id 格式为 support-group-UUID（如 support-group-550e8400-e29b-41d4-a716-446655440000）。

4.1 发送消息（访客端）

POST /v3/{project_id}/requests/{request_id}/messages

最低角色：guest

请求体：

{
  "text": "你好，我想咨询一下...",
  "departmentid": "<可选，技能组ID>"
}

💡 如果 request_id 对应的会话不存在，该调用会自动创建一个新会话——这是访客发起新对话的标准入口。

4.2 列出会话消息

GET /v3/{project_id}/requests/{request_id}/messages

最低角色：agent

返回消息列表，按时间正序排列。

4.3 获取单个会话详情

GET /v3/{project_id}/requests/{request_id}

最低角色：agent

4.4 关闭会话

PUT /v3/{project_id}/requests/{request_id}/close

4.5 重新打开会话

PUT /v3/{project_id}/requests/{request_id}/reopen

4.6 列出项目下的会话

GET /v3/{project_id}/requests/

查询参数：

page：分页页码
status：100 活跃 / 200 已关闭
departmentid：按技能组过滤
agentid：按坐席过滤

4.7 Message 模型关键字段

字段	类型	说明
sender	String	发送者 ID（用户 / 机器人 / system）
senderFullname	String	发送者显示名
text	String	消息文本
type	String	`text` / `image`
status	Number	`-100` FAILED / `0` SENDING / `100` SENT / `150` DELIVERED / `200` RECEIVED / `300` SEEN
metadata	Object	消息附加元数据（图片 URL、Bot Flow ID 等）
createdAt	String	UTC ISO-8601 时间戳

五、Leads（客户/线索）API

5.1 Leads 模型

字段	类型	说明
lead_id	String	外部系统唯一标识（如 CRM 中的客户 ID）
fullname	String	客户姓名
email	String	邮箱
attributes	Object	自定义属性
company	String	公司
phone	String	电话
tags	Array	标签数组

5.2 CRUD 操作

方法	端点	说明
GET	`/v3/{project_id}/leads`	列出全部 leads（支持分页、搜索）
GET	`/v3/{project_id}/leads/{id}`	获取单个 lead
POST	`/v3/{project_id}/leads`	创建 lead
PUT	`/v3/{project_id}/leads/{id}`	更新 lead
DELETE	`/v3/{project_id}/leads/{id}`	删除 lead

最低角色：agent

查询示例

curl -H 'Authorization: JWT <token>' \
  'http://localhost:8081/api/v3/5df2240cecd41b00173a06bb/leads?page=2&direction=-1&sortField=createdAt'

创建示例

curl -X POST \
  -H 'Authorization: JWT <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fullname": "张三",
    "email": "zhangsan@corp.com",
    "company": "科技公司",
    "lead_id": "CRM-001234"
  }' \
  http://localhost:8081/api/v3/5df2240cecd41b00173a06bb/leads

六、坐席与团队 API

6.1 列出项目下所有用户/坐席

GET /v3/{project_id}/users/

最低角色：agent

6.2 获取单个坐席

GET /v3/{project_id}/users/{user_id}

6.3 技能组（Departments）

技能组是会话自动路由的基础单元（如「销售部」「技术支持」）。

方法	端点
GET	`/v3/{project_id}/departments/` 列出
POST	`/v3/{project_id}/departments/` 创建
PUT	`/v3/{project_id}/departments/{id}` 更新
DELETE	`/v3/{project_id}/departments/{id}` 删除

6.4 快捷回复（Canned Responses）

预设的标准化回复模板，坐席可一键发送。

方法	端点
GET	`/v3/{project_id}/cannedresponses`
POST	`/v3/{project_id}/cannedresponses`
PUT	`/v3/{project_id}/cannedresponses/{id}`
DELETE	`/v3/{project_id}/cannedresponses/{id}`

七、Bot / Chatbot API

7.1 列出项目下全部 Bot

GET /v3/{project_id}/bots

最低角色：agent

7.2 获取单个 Bot 详情

GET /v3/{project_id}/bots/{bot_id}

Bot 详情包含 Bot Flow 定义（JSON 格式的对话流程图）。

7.3 创建 Bot

POST /v3/{project_id}/bots

请求体包含 Bot 的名称、描述、初始 Bot Flow JSON。

7.4 更新 Bot Flow

Bot Flow 是一个 JSON 格式的有向图，节点代表对话状态：

{
  "flow": [
    {
      "id": "start",
      "type": "start",
      "message": "你好，我是 AI 助手，请问需要什么帮助？",
      "next": "collect_name"
    },
    {
      "id": "collect_name",
      "type": "collect",
      "variable": "customer_name",
      "next": "end"
    },
    {
      "id": "end",
      "type": "end",
      "message": "感谢您的咨询，我们稍后联系您。"
    }
  ]
}

完整的 Bot Flow JSON schema 请参考官方 Design Studio 文档。

八、知识库 API

8.1 列出知识库

GET /v3/{project_id}/knowledge-bases

8.2 创建知识库

POST /v3/{project_id}/knowledge-bases

请求体：

{
  "name": "产品文档库",
  "description": "包含全部产品手册和 FAQ",
  "type": "internal"
}

8.3 知识库文档操作

方法	端点	说明
GET	`/v3/{project_id}/knowledge-bases/{kb_id}/documents`	列出知识库内文档
POST	`/v3/{project_id}/knowledge-bases/{kb_id}/documents`	上传文档（支持 PDF / Markdown / URL）
DELETE	`/v3/{project_id}/knowledge-bases/{kb_id}/documents/{doc_id}`	删除文档

8.4 触发重新训练

上传/删除文档后，需要触发 RAG 重新向量化：

POST /v3/{project_id}/knowledge-bases/{kb_id}/retrain

此操作会通知 backend-llm-train 服务重新处理知识库，耗时取决于文档数量。

九、其他有用 API

9.1 Analytics（统计分析）

GET /v3/{project_id}/analytics/conversations
GET /v3/{project_id}/analytics/messages
GET /v3/{project_id}/analytics/agents

返回会话数、消息量、坐席在线时长等统计数据。

9.2 Tags（标签）

为会话打标签，便于分类和检索：

GET    /v3/{project_id}/tags/
POST   /v3/{project_id}/tags/
PUT    /v3/{project_id}/tags/{id}
DELETE /v3/{project_id}/tags/{id}

9.3 Files（文件上传）

POST /v3/{project_id}/files/upload

用 multipart/form-data 提交文件，返回文件 URL，可在消息中引用。

9.4 Webhook Events

事件名	触发时机
`message-sent`	新消息发送
`message-delivered`	消息送达
`conversation-unarchived`	会话恢复
`conversation-created`	新会话创建
`lead-created`	新访客创建

Webhook URL 在 Dashboard 设置中配置，Tiledesk 会以 POST JSON 格式推送事件。

十、完整对接流程示例

场景：外部 CRM 系统同步客户数据 + 触发 AI Bot

#!/bin/bash
# ==== 配置 ====
BASE_URL="http://localhost:8081/api/v3"
EMAIL="admin@tiledesk.com"
PASSWORD="superadmin"
PROJECT_ID="5df2240cecd41b00173a06bb"

# ==== Step 1: 认证获取 JWT ====
TOKEN=$(curl -s -X POST "$BASE_URL/auth/signin" \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}" | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")

echo "✅ JWT 已获取"

# ==== Step 2: 检查外部 CRM 中的新客户 ====
# （这里演示直接创建一个新 lead）
LEAD_RESP=$(curl -s -X POST "$BASE_URL/$PROJECT_ID/leads" \
  -H "Authorization: JWT $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "lead_id": "CRM-CUST-001234",
    "fullname": "王五",
    "email": "wangwu@company.com",
    "company": "ABC 科技",
    "phone": "13800138000"
  }')

LEAD_ID=$(echo "$LEAD_RESP" | python3 -c "import sys,json;print(json.load(sys.stdin)['_id'])")
echo "✅ Lead 已创建，ID: $LEAD_ID"

# ==== Step 3: 向该客户发送欢迎消息 ====
# 先创建一个匿名访客会话，然后发送消息
REQUEST_ID="support-group-$(uuidgen)"

curl -s -X POST "$BASE_URL/$PROJECT_ID/requests/$REQUEST_ID/messages" \
  -H "Authorization: JWT $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "王五您好，欢迎联系 ABC 科技！请问有什么可以帮您？"
  }'

echo "✅ 欢迎消息已发送，会话 ID: $REQUEST_ID"

# ==== Step 4: 查询 AI Bot 状态 ====
BOTS=$(curl -s "$BASE_URL/$PROJECT_ID/bots" \
  -H "Authorization: JWT $TOKEN")

echo "📊 当前 Bot 列表:"
echo "$BOTS" | python3 -m json.tool 2>/dev/null || echo "$BOTS"

场景：访客 API + 自动路由到技能组

# 访客端（Widget 或自定义前端）
# 1. 匿名登录获取 JWT
VISITOR_TOKEN=$(curl -s -X POST "$BASE_URL/auth/signinAnonymously" \
  -H 'Content-Type: application/json' \
  -d "{
    \"id_project\": \"$PROJECT_ID\",
    \"firstname\": \"访客测试\",
    \"attributes\": {\"referer\": \"https://blog.example.com/article-123\"}
  }" | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")

# 2. 创建新会话并发送第一条消息（指定技能组）
curl -s -X POST "$BASE_URL/$PROJECT_ID/requests/support-group-$(uuidgen)/messages" \
  -H "Authorization: JWT $VISITOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "我需要售后服务",
    "departmentid": "605a1b2c3d4e5f0011223344"
  }'

十一、API 完整端点清单

以下为 Tiledesk v3 REST API 完整端点分类汇总。官方文档位于 developer.tiledesk.com/apis/rest-api。

资源	端点前缀	说明
认证	`/v3/auth/*`	signin / signinAnonymously / signinWithCustomToken
项目	`/v3/projects/*`	项目 CRUD、available agents、operating hours
会话	`/v3/{project_id}/requests/*`	会话创建、关闭、重开、消息列表
消息	`/v3/{project_id}/requests/{id}/messages`	发送和列出消息
Leads	`/v3/{project_id}/leads/*`	客户/线索 CRUD
坐席	`/v3/{project_id}/users/*`	用户/坐席管理
技能组	`/v3/{project_id}/departments/*`	路由分组
Bot	`/v3/{project_id}/bots/*`	Bot CRUD + Flow JSON
知识库	`/v3/{project_id}/knowledge-bases/*`	RAG 知识库 + 文档管理
快捷回复	`/v3/{project_id}/cannedresponses/*`	坐席预设回复
标签	`/v3/{project_id}/tags/*`	会话分类标签
Analytics	`/v3/{project_id}/analytics/*`	统计数据
文件	`/v3/{project_id}/files/*`	文件上传下载
事件	`/v3/{project_id}/events/*`	会话事件历史
Segments	`/v3/{project_id}/segments/*`	客户分群

十二、API 与实时 API 的关系

Tiledesk 同时提供两套 API：

API 类型	用途	协议	端点
REST API（本文）	数据管理、CRUD、统计分析	HTTP JSON	`/api/v3/*`
Realtime API	实时消息推送、会话状态变更	MQTT over WebSocket	`/mqws/ws`

典型的集成模式是：

REST API 完成初始化（登录、创建客户、发送离线消息）
Realtime API 保持长连接，接收实时推送（新消息、会话关闭）

Realtime API 文档见 developer.tiledesk.com/apis/realtime-api。

Tiledesk REST API 详解

Tiledesk REST API 详解

一、API 基础

1.1 端点基础

1.2 Project ID

1.3 认证方式

方式一：Basic Auth（简单直接）

方式二：JWT Token（推荐，生产安全）

方式三：匿名认证（访客端）

1.4 角色与权限

1.5 速率限制

1.6 请求格式

1.7 响应格式

二、认证 API

2.1 邮箱密码登录

2.2 匿名登录

2.3 自定义 Token 登录

三、项目管理 API

3.1 列出用户所属全部项目

3.2 获取项目详情

3.3 获取可用坐席

3.4 检查项目当前是否开放

3.5 更新项目 Widget 外观

四、会话与消息 API

4.1 发送消息（访客端）

4.2 列出会话消息

4.3 获取单个会话详情

4.4 关闭会话

4.5 重新打开会话

4.6 列出项目下的会话

4.7 Message 模型关键字段

五、Leads（客户/线索）API

5.1 Leads 模型

5.2 CRUD 操作

查询示例

创建示例

六、坐席与团队 API

6.1 列出项目下所有用户/坐席

6.2 获取单个坐席

6.3 技能组（Departments）

6.4 快捷回复（Canned Responses）

七、Bot / Chatbot API

7.1 列出项目下全部 Bot

7.2 获取单个 Bot 详情

7.3 创建 Bot

7.4 更新 Bot Flow

八、知识库 API

8.1 列出知识库

8.2 创建知识库

8.3 知识库文档操作

8.4 触发重新训练

九、其他有用 API

9.1 Analytics（统计分析）

9.2 Tags（标签）

9.3 Files（文件上传）

9.4 Webhook Events

十、完整对接流程示例

场景：外部 CRM 系统同步客户数据 + 触发 AI Bot

场景：访客 API + 自动路由到技能组

十一、API 完整端点清单

十二、API 与实时 API 的关系