Tally Forms API

通过 Tally.so 提供的 REST API 以编程方式创建和编辑表单。

认证

TALLY_KEY=$(cat ~/.config/tally/api_key)

端点

区块结构

Tally 表单由 区块（blocks） 构成。问题需由 多个共享同一 groupUuid 的区块组成：

{
  "uuid": "q1-title",
  "type": "TITLE",
  "groupUuid": "group-q1",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["Question text here", [["tag", "span"]]]]
  }
},
{
  "uuid": "q1-input",
  "type": "INPUT_TEXT",
  "groupUuid": "group-q1",
  "groupType": "QUESTION",
  "payload": {"isRequired": true}
}

关键点： TITLE 区块与输入区块必须使用相同的 groupUuid。

区块类型

结构类

• FORM_TITLE — 表单标题及提交按钮
• TEXT — 段落文本
• HEADING_1、HEADING_2、HEADING_3 — 分节标题
• TITLE — 问题标签（位于 QUESTION 类型分组内）
• DIVIDER — 分隔线

输入类

• INPUT_TEXT — 短文本
• INPUT_NUMBER — 数字
• INPUT_EMAIL — 邮箱
• INPUT_DATE — 日期选择器
• INPUT_PHONE_NUMBER — 电话号码
• TEXTAREA — 长文本

选择类

• MULTIPLE_CHOICE_OPTION — 单选（groupType: MULTIPLE_CHOICE）
• CHECKBOX — 多选（groupType: CHECKBOXES）
• DROPDOWN_OPTION — 下拉选项

⚠️ 通过 API 渲染效果不佳的类型

• RATING — 星标无法正常显示
• LINEAR_SCALE — 量表无法正常显示

临时解决方案： 使用 MULTIPLE_CHOICE_OPTION 配合星标 emoji（⭐）模拟评分控件。

示例

表单标题

{
  "uuid": "title-001",
  "type": "FORM_TITLE",
  "groupUuid": "group-title",
  "groupType": "FORM_TITLE",
  "payload": {
    "title": "My Survey",
    "button": {"label": "Submit"}
  }
}

分节标题

{
  "uuid": "sec1-head",
  "type": "HEADING_2",
  "groupUuid": "group-sec1",
  "groupType": "TEXT",
  "payload": {
    "safeHTMLSchema": [["📊 Section Title", [["tag", "span"]]]]
  }
}

文本输入题

{
  "uuid": "q1-title",
  "type": "TITLE",
  "groupUuid": "group-q1",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["What is your name?", [["tag", "span"]]]]
  }
},
{
  "uuid": "q1-input",
  "type": "INPUT_TEXT",
  "groupUuid": "group-q1",
  "groupType": "QUESTION",
  "payload": {"isRequired": true}
}

单选题（单选）

{
  "uuid": "q2-title",
  "type": "TITLE",
  "groupUuid": "group-q2",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["How did you hear about us?", [["tag", "span"]]]]
  }
},
{
  "uuid": "q2-opt1",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q2",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 0, "isFirst": true, "isLast": false, "text": "Social media"}
},
{
  "uuid": "q2-opt2",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q2",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 1, "isFirst": false, "isLast": true, "text": "Friend referral"}
}

多选题（多选）

{
  "uuid": "q3-title",
  "type": "TITLE",
  "groupUuid": "group-q3",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["What features interest you?", [["tag", "span"]]]]
  }
},
{
  "uuid": "q3-cb1",
  "type": "CHECKBOX",
  "groupUuid": "group-q3",
  "groupType": "CHECKBOXES",
  "payload": {"index": 0, "isFirst": true, "isLast": false, "text": "Feature A"}
},
{
  "uuid": "q3-cb2",
  "type": "CHECKBOX",
  "groupUuid": "group-q3",
  "groupType": "CHECKBOXES",
  "payload": {"index": 1, "isFirst": false, "isLast": true, "text": "Feature B"}
}

评分题（使用星标 emoji 的临时方案）

{
  "uuid": "q4-title",
  "type": "TITLE",
  "groupUuid": "group-q4",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["How would you rate our service?", [["tag", "span"]]]]
  }
},
{
  "uuid": "q4-opt1",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 0, "isFirst": true, "isLast": false, "text": "⭐ Poor"}
},
{
  "uuid": "q4-opt2",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 1, "isFirst": false, "isLast": false, "text": "⭐⭐ Fair"}
},
{
  "uuid": "q4-opt3",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 2, "isFirst": false, "isLast": false, "text": "⭐⭐⭐ Good"}
},
{
  "uuid": "q4-opt4",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 3, "isFirst": false, "isLast": false, "text": "⭐⭐⭐⭐ Very good"}
},
{
  "uuid": "q4-opt5",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 4, "isFirst": false, "isLast": true, "text": "⭐⭐⭐⭐⭐ Excellent"}
}

更新命令

TALLY_KEY=$(cat ~/.config/tally/api_key)

# 先备份
curl -s "https://api.tally.so/forms/{ID}" 
  -H "Authorization: Bearer $TALLY_KEY" > /tmp/backup.json

# 执行更新
curl -s "https://api.tally.so/forms/{ID}" 
  -X PATCH 
  -H "Authorization: Bearer $TALLY_KEY" 
  -H "Content-Type: application/json" 
  -d @/tmp/form.json

# 验证结果
curl -s "https://api.tally.so/forms/{ID}" 
  -H "Authorization: Bearer $TALLY_KEY" | jq '.blocks | length'

最佳实践

1. 始终先备份，再修改表单
2. 使用描述性 UUID（例如：q1-title、q1-input、sec1-head）
3. 分节标题：建议采用小写字母 + emoji 前缀格式（如：📊 General feedback）
4. 评分题：请使用 MULTIPLE_CHOICE 类型配合 ⭐ emoji，避免直接使用 RATING 类型
5. 更新后验证：检查返回的 .blocks | length 是否与预期一致