Typebot 3.19 REST API 详解

目标：本文档覆盖 Typebot v3.19 自托管实例的完整 REST API，含认证方式、全部端点（Workspace / Typebot / Results / Public Chat）、请求/响应示例与常见错误码。所有请求均以 Builder 的公开 URL 为基础（如 https://typebot.example.com），版本信息截至 2026-10-27。

一、环境信息

Typebot 版本：v3.19.0
API 协议：HTTP + JSON，无 gRPC
API 基础路径：Builder 的公开 URL + /api/v1/（如 https://typebot.example.com/api/v1/）
Viewer 公开端点：Viewer 的公开 URL + /api/v1/（但公开对话端点走 Viewer 进程）
认证方式：Bearer Token（Authorization: Bearer <token>）；部分公开端点无需认证
数据格式：Content-Type: application/json
管理面形态：Typebot 无任何 CLI 工具，所有程序化操作必须通过 REST API 完成——这也是本批次选择 D5 替代默认 D1 CLI 篇的原因

二、前置条件

Builder 和 Viewer 已部署并可访问（见《Typebot 3.19 Docker Compose 部署指南》）
至少有一个已注册的管理员账户（ADMIN_EMAIL 对应邮箱）
准备好 curl / HTTPie / Postman 等工具（本文全部用 curl 演示）

三、API 总览

3.1 端点分组

分组	路径前缀	认证	用途
Workspace 管理	`/api/v1/workspaces`	Bearer Token	创建/查询/更新 Workspace
Typebot 管理	`/api/v1/typebots`	Bearer Token	创建/查询/更新/发布/导入/删除 bot
对话结果	`/api/v1/typebots/{id}/results`	Bearer Token	获取 bot 的访客对话数据
公开对话（Viewer）	`/api/v1/typebots/{publicId}/startChat` / `continueChat`	无需	外部系统程序化发起/继续对话
API Token 生成	Builder 网页内（Settings → My Account）	交互式	Token 只能通过 UI 生成，无 API 端点

3.2 版本与限流

API 版本：v1（路径中显式）
限流：默认无显式限流配置（需自行用反向代理或 API Gateway 控制）
超时：Builder 默认 CHAT_API_TIMEOUT 限制聊天 API 执行时间（毫秒）

3.3 基础 URL 构成

Builder API URL:   https://<NEXTAUTH_URL host>/api/v1/...
Viewer 公开端点:   https://<NEXT_PUBLIC_VIEWER_URL host>/api/v1/...

⚠️ 重要：所有 管理类 端点（Workspace、Typebot CRUD、Results）走 Builder；公开对话类 端点（startChat、continueChat）走 Viewer。两者使用相同的 API Token，但进程不同。

四、认证与首次调用

4.1 生成 API Token（通过 Builder UI）

Typebot 的 API Token 无法通过 API 生成，必须在 Builder 网页内手动操作：

浏览器访问 https://<NEXTAUTH_URL host> 并登录
点击左下角头像 → Settings & Members → My account
滚动到 API tokens 区域 → 点击 Create
填写 Token 名称（如 automation-bot）→ 点击 Create token
立即复制 Token（只显示一次）

4.2 测试认证

export TYPEBOT_API_TOKEN='pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
export TYPEBOT_API_BASE='http://localhost:8128/api/v1'

# 验证 token 有效（列出所有 Workspace）
curl -sS -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Accept: application/json" \
  "$TYPEBOT_API_BASE/workspaces" | python3 -m json.tool

成功响应（200 OK）：

{
  "workspaces": [
    {
      "id": "abc123def456",
      "name": "My Workspace",
      "icon": null,
      "plan": "UNLIMITED",
      "stripeId": null,
      "settings": {},
      "isSuspended": false,
      "isPastDue": false,
      "isVerified": true,
      "chatsHardLimit": null,
      "lastActivityAt": "2026-10-27T10:00:00.000Z",
      "createdAt": "2026-10-27T09:00:00.000Z",
      "updatedAt": "2026-10-27T09:00:00.000Z"
    }
  ]
}

失败响应（401 Unauthorized）：

{
  "code": "UNAUTHORIZED",
  "message": "Unauthorized"
}

💡 Token 权限范围：API Token 继承创建者账户的所有权限——管理员账户创建的 Token 可访问所有 Workspace 并拥有完全操作权限；普通成员创建的 Token 仅能操作其所属 Workspace 内的 Typebot。

五、Workspace 管理 API

5.1 列出 Workspace

curl -sS -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  "$TYPEBOT_API_BASE/workspaces" | python3 -m json.tool

响应：包含当前 Token 所属账户可访问的所有 Workspace 数组（见 4.2 节示例）。

5.2 创建 Workspace

curl -sS -X POST \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering Bot Platform", "icon": "🤖"}' \
  "$TYPEBOT_API_BASE/workspaces" | python3 -m json.tool

响应（200 OK）：

{
  "workspace": {
    "id": "ws_new_ws_id",
    "name": "Engineering Bot Platform",
    "icon": "🤖",
    "plan": "FREE",
    "createdAt": "2026-10-27T10:30:00.000Z"
  }
}

5.3 获取单个 Workspace

curl -sS -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  "$TYPEBOT_API_BASE/workspaces/<workspaceId>" | python3 -m json.tool

5.4 更新 Workspace

curl -sS -X PATCH \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Workspace", "icon": "🔄"}' \
  "$TYPEBOT_API_BASE/workspaces/<workspaceId>" | python3 -m json.tool

六、Typebot 管理 API

这是最核心的一组端点，覆盖 Bot 的完整生命周期。

6.1 列出 Typebot

# 列出指定 Workspace 下的所有 Typebot
WORKSPACE_ID='ws_abc123'

curl -sS -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  "$TYPEBOT_API_BASE/typebots?workspaceId=$WORKSPACE_ID" | python3 -m json.tool

响应：

{
  "typebots": [
    {
      "id": "tb_abc123",
      "name": "Customer Support Bot",
      "icon": "💬",
      "publicId": "abcd1234ef56",   // 公开对话 ID，嵌入脚本用
      "customDomain": null,
      "isArchived": false,
      "createdAt": "2026-10-27T10:00:00.000Z",
      "updatedAt": "2026-10-27T10:30:00.000Z"
    }
  ]
}

6.2 创建 Typebot

curl -sS -X POST \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$WORKSPACE_ID"'",
    "typebot": {
      "name": "Lead Qualification Bot",
      "icon": "🎯"
    }
  }' \
  "$TYPEBOT_API_BASE/typebots" | python3 -m json.tool

响应（200 OK）：返回完整的 typebot 对象，含新建的 id 和默认空 groups 数组。

⚠️ Typebot 的完整数据结构非常复杂（含 groups / blocks / events / theme），通过 API 创建一般只传 name + icon + workspaceId，完整编辑仍在 Builder UI 内完成。API 更适合自动化管理（发布/取消发布/导入/导出）。

6.3 获取 Typebot 详情

TYPEBOT_ID='tb_abc123'

curl -sS -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  "$TYPEBOT_API_BASE/typebots/$TYPEBOT_ID" | python3 -m json.tool | head -50

响应包含完整的 typebot 定义 JSON（groups / blocks / theme / settings），体积可能很大（数百行）。

6.4 更新 Typebot

# 更新 Bot 名称（只传需要修改的字段）
curl -sS -X PATCH \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lead Qualification Bot - v2"}' \
  "$TYPEBOT_API_BASE/typebots/$TYPEBOT_ID" | python3 -m json.tool | head -20

6.5 发布 Typebot（重要）

Builder 内编辑 Bot 后必须显式发布才能在 Viewer 对外生效：

curl -sS -X POST \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$TYPEBOT_API_BASE/typebots/$TYPEBOT_ID/publish" | python3 -m json.tool

响应（200 OK）：

{
  "message": "success"
}

6.6 取消发布（关闭 Bot 接收新对话）

curl -sS -X POST \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$TYPEBOT_API_BASE/typebots/$TYPEBOT_ID/unpublish" | python3 -m json.tool

6.7 导入 Typebot

可将 JSON 格式的 Typebot 定义导入到指定 Workspace：

curl -sS -X POST \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$WORKSPACE_ID"'",
    "typebot": { ... 完整 typebot JSON ... }
  }' \
  "$TYPEBOT_API_BASE/typebots/import" | python3 -m json.tool

6.8 删除 Typebot

curl -sS -X DELETE \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  "$TYPEBOT_API_BASE/typebots/$TYPEBOT_ID" | python3 -m json.tool

6.9 复制 Typebot

curl -sS -X POST \
  -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": "'"$WORKSPACE_ID"'"}' \
  "$TYPEBOT_API_BASE/typebots/$TYPEBOT_ID/duplicate" | python3 -m json.tool

七、对话结果 API

获取 Bot 收集到的访客对话数据（leads、answers、变量值等）。

7.1 获取 Results

curl -sS -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  "$TYPEBOT_API_BASE/typebots/$TYPEBOT_ID/results" | python3 -m json.tool | head -80

响应（节选）：

{
  "results": [
    {
      "id": "res_abc123",
      "typebotId": "tb_abc123",
      "createdAt": "2026-10-27T11:00:00.000Z",
      "updatedAt": "2026-10-27T11:01:30.000Z",
      "variables": [
        {"name": "email", "value": "user@example.com"},
        {"name": "company", "value": "Acme Inc."}
      ],
      "answers": [
        {
          "blockId": "blk_001",
          "variableId": "var_email",
          "value": "user@example.com"
        }
      ]
    }
  ]
}

7.2 导出 CSV

# Typebot UI 内可手动导出 CSV，API 未提供直接导出端点
# 可用上面的 Results API + jq 自行转换
curl -sS -H "Authorization: Bearer $TYPEBOT_API_TOKEN" \
  "$TYPEBOT_API_BASE/typebots/$TYPEBOT_ID/results" \
  | jq -r '.results[] | [.id, .createdAt, (.variables | map("\(.name)=\(.value)") | join(";"))] | @csv'

八、公开对话 API（Viewer，无认证）

这是 Viewer 进程提供的端点，不需要 API Token（但需要 Bot 已发布）。用于外部系统（Web 嵌入、WhatsApp、自定义集成等）程序化发起和继续对话。

⚠️ 公开端点走 Viewer（NEXT_PUBLIC_VIEWER_URL 的 host），非 Builder。URL 格式：https://<viewer-host>/api/v1/...

8.1 开始新对话

export VIEWER_API_BASE='http://localhost:8129/api/v1'
PUBLIC_ID='abcd1234ef56'   // 从 Builder 详情页或嵌入脚本获取

curl -sS -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "publicId": "'"$PUBLIC_ID"'",
    "isStreamEnabled": false,
    "variables": [
      {"name": "source", "value": "api-test"},
      {"name": "utm_campaign", "value": "2026q4"}
    ]
  }' \
  "$VIEWER_API_BASE/typebots/$PUBLIC_ID/startChat" | python3 -m json.tool

响应（200 OK）：

{
  "messages": [
    {
      "id": "msg_001",
      "type": "text",
      "content": "Hello! I'm your assistant. What can I help you with today?",
      "status": "success"
    }
  ],
  "state": {
    "currentBlockId": "blk_welcome_001",
    "progress": 5,
    "variables": [
      {"name": "source", "value": "api-test"},
      {"name": "utm_campaign", "value": "2026q4"}
    ]
  }
}

响应中的 state.currentBlockId 指明 Bot 当前停在哪个 block；state.variables 传递所有已设置的变量。

8.2 继续对话

带 message 参数发送访客的回复内容。State 需要保留并回传：

curl -sS -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "publicId": "'"$PUBLIC_ID"'",
    "message": {
      "type": "text",
      "content": "I need pricing information"
    },
    "state": {
      "currentBlockId": "blk_welcome_001",
      "progress": 5,
      "variables": [
        {"name": "source", "value": "api-test"},
        {"name": "utm_campaign", "value": "2026q4"}
      ]
    },
    "isStreamEnabled": false
  }' \
  "$VIEWER_API_BASE/typebots/$PUBLIC_ID/continueChat" | python3 -m json.tool

响应：同 8.1 的 messages + state 结构。

8.3 消息类型

type	content 格式	说明
`text`	字符串	纯文本回复
`image`	Image block URL	Builder 图片块
`video`	Video block URL	Builder 视频块
`audio`	Audio block URL	Builder 音频块
`bubble`	气泡对象	复杂气泡消息

8.4 流式对话（Server-Sent Events）

设置 isStreamEnabled: true，Viewer 会通过 SSE（Server-Sent Events）逐块推送消息更新。适合实时聊天 UI：

curl -N -X POST \
  -H "Content-Type: application/json" \
  -d '{"publicId":"'"$PUBLIC_ID"'","isStreamEnabled":true,"message":{"type":"text","content":"hi"}}' \
  "$VIEWER_API_BASE/typebots/$PUBLIC_ID/continueChat"
# 输出格式为 SSE：
# data: {"event": "message", "data": {...}}
# data: {"event": "state", "data": {...}}
# data: [DONE]

九、通用约定

9.1 错误码格式

Typebot API 所有错误响应统一为：

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "data": null
}

9.2 HTTP 状态码与对应错误码

HTTP 状态	code	场景
200	—	成功
400	`BAD_REQUEST`	请求参数校验失败（如缺少必填字段、枚举值错误）
401	`UNAUTHORIZED`	Token 缺失、过期或无效
403	`FORBIDDEN`	Token 有效但无权限操作目标资源（如跨 Workspace）
404	`NOT_FOUND`	资源不存在（如 typebotId 拼写错误）
500	`INTERNAL_SERVER_ERROR`	服务端异常（查看 Builder 日志定位）

9.3 ID 格式约定

Typebot 内部使用多种 ID 前缀（非随机 UUID）：

前缀	含义	示例
`ws_`	Workspace ID	`ws_abc123`
`tb_`	Typebot ID	`tb_def456`
`blk_`	Block ID（Bot 内的节点）	`blk_ghi789`
`var_`	Variable ID	`var_jkl012`
`res_`	Result ID（对话记录）	`res_mno345`
`publicId`	公开对话 ID（12 位随机，无前缀）	`abcd1234ef56`

十、实战工作流示例

10.1 完整自动化：创建→发布→测试 Bot

# 0. 设置变量
export TOKEN='pat_xxxxxxxxxxxx'
export API='http://localhost:8128/api/v1'
export WORKSPACE_ID='ws_abc123'

# 1. 创建 Bot
echo "=== 1. Creating typebot ==="
NEW_TYPEBOT=$(curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"'"$WORKSPACE_ID"'","typebot":{"name":"API Test Bot","icon":"🧪"}}' \
  "$API/typebots")
echo "$NEW_TYPEBOT" | python3 -m json.tool | grep -E '"(id|publicId)"'

TYPEBOT_ID=$(echo "$NEW_TYPEBOT" | python3 -c "import sys,json; print(json.load(sys.stdin)['typebot']['id'])")
PUBLIC_ID=$(echo "$NEW_TYPEBOT" | python3 -c "import sys,json; print(json.load(sys.stdin)['typebot']['publicId'])")
echo "Typebot ID: $TYPEBOT_ID, Public ID: $PUBLIC_ID"

# 2. 发布 Bot（注意：空 Bot 无法真正对话，但 publish 本身会成功）
echo "=== 2. Publishing typebot ==="
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$API/typebots/$TYPEBOT_ID/publish" | python3 -m json.tool

# 3. 验证公开端点已可访问
echo "=== 3. Testing public endpoint ==="
VIEWER_API='http://localhost:8129/api/v1'
curl -sS -X POST -H "Content-Type: application/json" \
  -d '{"publicId":"'"$PUBLIC_ID"'"}' \
  "$VIEWER_API/typebots/$PUBLIC_ID/startChat" | python3 -m json.tool

# 4. 列出 Workspace 下所有 Bot 验证存在
echo "=== 4. Verifying in list ==="
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$API/typebots?workspaceId=$WORKSPACE_ID" \
  | python3 -m json.tool | grep -A1 "API Test Bot"

# 5. 清理：删除测试 Bot
echo "=== 5. Cleanup ==="
curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$API/typebots/$TYPEBOT_ID" | python3 -m json.tool

十一、常见问题

Q1：公开端点返回 404，但 Builder 内 Bot 已发布

原因：请求打到了 Builder 而不是 Viewer。

解决：公开端点（startChat / continueChat）必须走 Viewer 的公开 URL（NEXT_PUBLIC_VIEWER_URL），而非 Builder 的 NEXTAUTH_URL。检查你的 API Base URL：

# ❌ 错误
http://localhost:8128/api/v1/typebots/$PUBLIC_ID/startChat

# ✅ 正确
http://localhost:8129/api/v1/typebots/$PUBLIC_ID/startChat

Q2：创建 Bot 后 startChat 返回空 messages

原因：新建空 Bot 没有任何 block（groups 为空数组），Viewer 启动后没有可发送的内容。

解决：

在 Builder UI 内给 Bot 添加至少一个 Start block 和至少一个 Text bubble block
发布后再测试

Q3：TypeScript / Node 客户端发请求报 CORS

原因：浏览器环境直接跨域请求 Builder/Viewer 会触发 CORS 拦截。

解决：

服务器端脚本（curl、Python requests、Node axios）不受 CORS 限制
浏览器端：通过反向代理将 API 路径转发到 Builder/Viewer（同域），或在 Builder 配置 CORS（当前 Typebot v3 未暴露 CORS 配置项，建议走代理）

Q4：API Token 丢失或泄露

解决：

登录 Builder → Settings & Members → My account → API tokens
找到可疑 Token → 点击 Revoke
创建新 Token 替换

Q5：Results API 返回空数组

原因：Bot 发布后还没有访客完成对话；或 Bot 被取消发布。

解决：

确认 Bot 已 publish（非 unpublish）
用 startChat 发起完整对话（必须至少完成一个输入块）
等待 10-30 秒让结果写入数据库后再查询

十二、参考链接

官方 API Reference 首页：https://docs.typebot.com/api-reference
Authentication：https://docs.typebot.com/api-reference/authentication
Create Typebot：https://docs.typebot.com/api-reference/typebot/create
Publish Typebot：https://docs.typebot.com/api-reference/typebot/publish
Workspace API：https://docs.typebot.com/api-reference/workspace/create
公开对话（外部消息应用）：https://docs.typebot.com/guides/external-messaging-apps
完整 Typebot JSON Schema：https://github.com/baptisteArno/typebot.io/blob/main/packages/prisma/schema.prisma