获取自定义字段列表

该接口用于获取已创建的自定义字段

请求方法

get /custom_fields

请求参数

参数名 必填 类型 说明 限制
category 字符串 要获取的自定义字段类型,具体说明见下文,默认为工单 枚举,取值范围:["ticket", "customer", "organization"]

category 说明

选项 说明
ticket 工单自定义字段
customer 客户自定义字段
organization 客户公司自定义字段

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
custom_fields 数组 自定义字段列表,具体见下文

custom_fields 中元素说明

属性名 类型 说明
id 整型 id
field_name 字符串 字段标识
field_label 字符串 字段显示名称
content_type 字符串 字段类型,具体见下文
comment 字符串 字段备注
options 数组 字段选项,仅选择类型字段返回,具体见下文
customer_permission 字符串 客户权限,仅客户字段与工单字段返回,具体见下文
agent_permission 字符串 客服权限,仅客户字段与客户公司字段返回,具体见下文

content_type 取值范围

取值 说明
text 单行文本
area_text 多行文本
date 日期
time 时间
datetime 日期时间
link 超链接
location 地理位置
number 正整数
numeric 数值
droplist 下拉列表
radio 单选
checkbox 多选
chained_droplist 级联

options 说明

数组元素结构

属性名 类型 说明
title 字符串 选项文字描述
value 字符串 选项值
subs 数组 子选项,仅级联字段包含,结构与options相同

customer_permission 取值范围

取值 说明
none 客户不可见
readonly 客户可见,但不可编辑
readwrite 客户可编辑
must 客户必填

agent_permission 取值范围

取值 说明
readonly 客服可见,但不可编辑
readwrite 客服可编辑
must 客服必填

示例

请求

curl -s "https://demo.udesk.cn/open_api_v1/custom_fields?email=admin@udesk.cn&timestamp=1503298812sign=4a38e71a044e4dccb6069418abd2153e905a31cb&category=customer"

返回

{
    "code": 1000,
    "custom_fields": [
        {
            "field_name": "TextField_1",
            "field_label": "单行文本字段",
            "content_type": "text",
            "comment": null,
            "options": null,
            "customer_permission": "readwrite",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_2",
            "field_label": "多行文本字段",
            "content_type": "area_text",
            "comment": null,
            "options": null,
            "cusotmer_permission": "readwrite",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_3",
            "field_label": "日期字段",
            "content_type": "date",
            "comment": null,
            "options": null,
            "customer_permission": "read",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_4",
            "field_label": "日期时间字段",
            "content_type": "datetime",
            "comment": null,
            "options": null,
            "customer_permission": "read",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_5",
            "field_label": "链接字段",
            "content_type": "link",
            "comment": null,
            "options": null,
            "customer_permission": "must",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_6",
            "field_label": "地理位置字段",
            "content_type": "location",
            "comment": null,
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_7",
            "field_label": "时间字段",
            "content_type": "time",
            "comment": null,
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_8",
            "field_label": "正整数字段",
            "content_type": "number",
            "comment": null,
            "options": null,
            "customer_permission": "none",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_9",
            "field_label": "数值字段",
            "content_type": "numeric",
            "comment": null,
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "SelectField_1",
            "field_label": "下拉列表字段",
            "content_type": "droplist",
            "comment": null,
            "customer_permission": "read",
            "agent_permission": "readwrite",
            "options": [
                {"title": "下拉选项1", "value": "0"},
                {"title": "下拉选项2", "value": "1"}
            ]
        },
        {
            "field_name": "SelectField_2",
            "field_label": "单选框字段",
            "content_type": "radio",
            "comment": null,
            "customer_permission": "read",
            "agent_permission": "readwrite",
            "options": [
                {"title": "单选框选项1", "value": "1"},
                {"title": "单选框选项2", "value": "0"}
            ]
        },
        {
            "field_name": "SelectField_3",
            "field_label": "多选框字段",
            "content_type": "checkbox",
            "comment": null,
            "customer_permission": "none",
            "agent_permission": "must",
            "options": [
                {"title": "多选框选项1", "value": "3"},
                {"title": "多选框选项2", "value": "4"},
                {"title": "多选框选项3", "value": "1"},
                {"title": "多选框选项4", "value": "7"}
            ]
        },
        {
            "field_name": "SelectField_4",
            "field_label": "级联字段",
            "content_type": "chained_droplist",
            "comment": null,
            "options": [
                {"title": "北京市", "value": "0", "subs": [
                    {"title": "海淀区", "value": "0", "subs": [
                        {"title": "知春路", "value": "0"}
                    ]}
                ]},
                {"title": "天津市", "value": "0", "subs": [
                    {"title": "和平区", "value": "0"}
                ]}
            ],
            "customer_permission": "none",
            "agent_permission": "must"
        }
    ]
}

更新自定义字段

该接口用于更新指定自定义字段,暂不支持级联字段

请求方法

PUT /open_api_v1/custom_fields/:field_name

通过获取自定义字段列表接口可以获取所有自定义字段信息

请求参数

参数 必填 类型 说明 限制
field_name 字符串 field_name该参数可在自定义字段配置页面中的字段ID列获取,或者通过获取自定义字段列表api接口返回数据中的field_name字段获取 如TextField_97SelectField_166
title 字符串 自定义字段标题
comment 字符串 自定义字段备注
select_options 数组 选择形字段选项参数,仅更新选择性字段时需要此参数。如果不更新选择性字段的选项,该参数可不填

select_options中的元素说明

通过获取自定义字段列表接口可以获取自定义字段信息

参数 必填 类型 说明 限制
title 字符串 选项标题
value 字符串 选项值 1.value为系统自动生成,不要修改! 2. 当新增选项时,不需要传递value选项!
default 布尔值 默认生效选项 如果使用了该参数,那么它的值只能为true

value 为系统自动生成,不要修改!

当新增选项时,不需要传递value选项!

示例

更新单选字段

curl https://demo.udesk.cn/open_api_v1/custom_fields/SelectField_1?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X PUT \
-H 'content-type:application/json' \
-d '
{
  "title": "api测试更改单选框自定义字段",
  "comment": "api测试更改单选框自定义字段",
  "select_options": [
      {
          "title": "第一个选项",
          "value": "0",
          "default": true
      },
      {
          "title": "第二个选项",
          "value": "1",
      },
      {
          "title": "新增第三个选项",
      }
  ]
}'

更新单行文本字段

curl https://demo.udesk.cn/open_api_v1/custom_fields/TextField_1?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X PUT \
-H 'content-type:application/json' \
-d '
{
  "title": "api测试更改单行文本自定义字段",
  "comment": "api测试更改单行文本自定义字段",
}'

返回值

{
  "code": 1000,
  "message": "更新成功"
}