Tally Forms API

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

身份认证

bash
TALLYKEY=$(cat ~/.config/tally/apikey)

接口端点

操作	方法	端点
列出表单	GET	https://api.tally.so/forms
获取表单

GET | https://api.tally.so/forms/{id} | | 更新表单 | PATCH | https://api.tally.so/forms/{id} | | 获取提交 | GET | https://api.tally.so/forms/{id}/submissions |

块结构

Tally表单由块组成。问题需要通过groupUuid将多个块分组：

json
{
uuid: q1-title,
type: TITLE,
groupUuid: group-q1,
groupType: QUESTION,
payload: {
safeHTMLSchema: [[问题文本在此, [[tag, span]]]]
}
},
{
uuid: q1-input,
type: INPUT_TEXT,
groupUuid: group-q1,
groupType: QUESTION,
payload: {isRequired: true}
}

关键点： TITLE块和输入块必须共享相同的groupUuid。

块类型

结构类

• - FORMTITLE - 表单标题和提交按钮
• TEXT - 段落文本
• HEADING1, HEADING2, HEADING3 - 章节标题
• TITLE - 问题标签（在QUESTION组内）
• DIVIDER - 分隔线

输入类

• - INPUTTEXT - 短文本
• INPUTNUMBER - 数字
• INPUTEMAIL - 邮箱
• INPUTDATE - 日期选择器
• INPUTPHONENUMBER - 电话
• TEXTAREA - 长文本

选择类

• - MULTIPLECHOICEOPTION - 单选（groupType: MULTIPLECHOICE）
• CHECKBOX - 多选（groupType: CHECKBOXES）
• DROPDOWNOPTION - 下拉选项

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

• - RATING - 星级不显示
• LINEAR_SCALE - 刻度不显示

解决方案： 使用带星号emoji的MULTIPLECHOICEOPTION。

示例

表单标题

json { uuid: title-001, type: FORM_TITLE, groupUuid: group-title, groupType: FORM_TITLE, payload: { title: 我的调查, button: {label: 提交} } }

章节标题

json { uuid: sec1-head, type: HEADING_2, groupUuid: group-sec1, groupType: TEXT, payload: { safeHTMLSchema: [[📊 章节标题, [[tag, span]]]] } }

文本输入问题

json { uuid: q1-title, type: TITLE, groupUuid: group-q1, groupType: QUESTION, payload: { safeHTMLSchema: [[你叫什么名字？, [[tag, span]]]] } }, { uuid: q1-input, type: INPUT_TEXT, groupUuid: group-q1, groupType: QUESTION, payload: {isRequired: true} }

单选题（单个答案）

json { uuid: q2-title, type: TITLE, groupUuid: group-q2, groupType: QUESTION, payload: { safeHTMLSchema: [[你是如何知道我们的？, [[tag, span]]]] } }, { uuid: q2-opt1, type: MULTIPLECHOICEOPTION, groupUuid: group-q2, groupType: MULTIPLE_CHOICE, payload: {isRequired: true, index: 0, isFirst: true, isLast: false, text: 社交媒体} }, { uuid: q2-opt2, type: MULTIPLECHOICEOPTION, groupUuid: group-q2, groupType: MULTIPLE_CHOICE, payload: {isRequired: true, index: 1, isFirst: false, isLast: true, text: 朋友推荐} }

复选框（多个答案）

json { uuid: q3-title, type: TITLE, groupUuid: group-q3, groupType: QUESTION, payload: { safeHTMLSchema: [[你对哪些功能感兴趣？, [[tag, span]]]] } }, { uuid: q3-cb1, type: CHECKBOX, groupUuid: group-q3, groupType: CHECKBOXES, payload: {index: 0, isFirst: true, isLast: false, text: 功能A} }, { uuid: q3-cb2, type: CHECKBOX, groupUuid: group-q3, groupType: CHECKBOXES, payload: {index: 1, isFirst: false, isLast: true, text: 功能B} }

评分量表（使用星号作为解决方案）

json { uuid: q4-title, type: TITLE, groupUuid: group-q4, groupType: QUESTION, payload: { safeHTMLSchema: [[你如何评价我们的服务？, [[tag, span]]]] } }, { uuid: q4-opt1, type: MULTIPLECHOICEOPTION, groupUuid: group-q4, groupType: MULTIPLE_CHOICE, payload: {isRequired: true, index: 0, isFirst: true, isLast: false, text: ⭐ 差} }, { uuid: q4-opt2, type: MULTIPLECHOICEOPTION, groupUuid: group-q4, groupType: MULTIPLE_CHOICE, payload: {isRequired: true, index: 1, isFirst: false, isLast: false, text: ⭐⭐ 一般} }, { uuid: q4-opt3, type: MULTIPLECHOICEOPTION, groupUuid: group-q4, groupType: MULTIPLE_CHOICE, payload: {isRequired: true, index: 2, isFirst: false, isLast: false, text: ⭐⭐⭐ 好} }, { uuid: q4-opt4, type: MULTIPLECHOICEOPTION, groupUuid: group-q4, groupType: MULTIPLE_CHOICE, payload: {isRequired: true, index: 3, isFirst: false, isLast: false, text: ⭐⭐⭐⭐ 很好} }, { uuid: q4-opt5, type: MULTIPLECHOICEOPTION, groupUuid: group-q4, groupType: MULTIPLE_CHOICE, payload: {isRequired: true, index: 4, isFirst: false, isLast: true, text: ⭐⭐⭐⭐⭐ 优秀} }

更新命令

bash
TALLYKEY=$(cat ~/.config/tally/apikey)

先备份

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