DingTalk AI Table Skill

Responsible for all operations of DingTalk AI Table (multi-dimensional table in

.able

format), implemented via the Notable API of DingTalk Open Platform.

Core Concepts:

AI Table (
```
.able
```
file): Multi-dimensional table, uses Notable API (
```
/v1.0/notable
```
), is not a regular spreadsheet
base_id: nodeId of the AI Table file, the unique identifier of the table in DingTalk document system
Worksheet (Sheet): A single table inside the AI Table, contains fields and records
Field: Column definition, with name and type (
```
text
```
,
```
number
```
,
```
date
```
, etc.)
Record: Data row, contains values of each field

For API details, see

references/api.md

Configuration Management (Must Read Before Each Start)

Configuration File Path

~/.dingtalk-skills/config

(persisted across sessions, shared by all dingtalk-skills)

Configuration Instructions Required for This Skill

Key	Description	Source
`DINGTALK_APP_KEY`	DingTalk application appKey	Open Platform → Application Management → Credential Information
`DINGTALK_APP_SECRET`	DingTalk application appSecret	Same as above
`DINGTALK_OPERATOR_ID`	Operator unionId	See the "Why operatorId is required" section below
`DINGTALK_AI_TABLE_BASE_ID`	nodeId of AI Table	Extracted from AI Table share link

Startup Process (Before Each Task Execution)

Read configuration: Check if
```
~/.dingtalk-skills/config
```
exists, parse existing key-value pairs
Identify missing items: Find the keys in the above table that have not been configured yet
One-time collection: Combine all missing items into one question, do not ask one by one, for example:
The following information is required to proceed (no need to fill in existing information):
- DingTalk application appKey (DingTalk Open Platform → Application Management → Credential Information)
- DingTalk application appSecret
- AI Table link (used to extract base_id)
- Your DingTalk userId or unionId (to operate the table as your identity)
Persistence: Append the values provided by the user to the config, read directly later without asking again
Execute task: Start operation after configuration is complete

Note:
APP_KEY
/
APP_SECRET
/
OPERATOR_ID
are credentials, it is forbidden to print them completely in the output, only show the first 4 digits +
****
when confirming.

Authentication

Before each API call, use appKey/appSecret to get the current accessToken (valid for 2 hours):

POST https://api.dingtalk.com/v1.0/oauth2/accessToken
Content-Type: application/json

{ "appKey": "<应用 appKey>", "appSecret": "<应用 appSecret>" }

All requests need to carry:

Request header:

x-acs-dingtalk-access-token: <accessToken>

Query parameter:
```
operatorId=<user unionId>
```
(required for all write operations and some read operations)

Why base_id is required

Each file (document, spreadsheet, AI Table) in the DingTalk document system has a globally unique nodeId, which is

base_id

. Its function is similar to a database primary key - the API locates the specific AI Table file through it, because there may be multiple

.able

files under the account.

Extract base_id from link:

https://alidocs.dingtalk.com/i/nodes/<base_id>?...
                                     ↑ This part is base_id

Ask the user to provide the share link of the AI Table, and intercept the ID fragment after

/nodes/

. Write it to the config after the first acquisition, no need to ask again later.

Why operatorId (unionId) is required

DingTalk Open Platform requires all write operations to be performed on behalf of a real user identity, not an anonymous application identity.

operatorId

is to declare "who performed this operation" - it will be recorded in the change log, trigger the corresponding user's notification, and be used for permission verification.

The value is the operator's unionId
(DingTalk cross-organization unique ID), not
```
userId
```
(only unique within the organization)
Incorrectly passing userId will cause permission errors or incorrect operation attribution

How to get unionId

Method 1: Known userId → exchange for unionId (most commonly used)

userId

can usually be obtained directly from scenarios such as address book, free login, message callback, etc.

Step 1: Get the old

access_token

(different from the new version of accessToken, obtained separately here):

GET https://oapi.dingtalk.com/gettoken?appkey=<appKey>&appsecret=<appSecret>

Return:

{ "access_token": "xxx", "expires_in": 7200 }

Step 2: Query user details with userId and get unionId:

POST https://oapi.dingtalk.com/topapi/v2/user/get?access_token=<旧式token>
Content-Type: application/json

{ "userid": "<钉钉 userId>" }

The returned field

result.unionid

(no underscore) is unionId.

Note:
result.union_id
(with underscore) may be empty in exclusive DingTalk organizations, please use
result.unionid
.

Method 2: Bot/message scenario

When a user triggers via DingTalk bot or message, the message body directly contains the

senderUnionId

field, which can be used directly as

operatorId

without additional query.

Method 3: Ask the user directly

If the above methods are not available, ask the user to provide userId or unionId during the initial configuration phase (both can be viewed on the DingTalk personal information page). Write it to the config after acquisition, no need to obtain it repeatedly for subsequent operations.

Core Operations

1. List worksheets

GET https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets?operatorId={operatorId}
x-acs-dingtalk-access-token: <accessToken>

Return:

json

{
  "value": [
    { "id": "HAcL4SD", "name": "项目" },
    { "id": "nr2iEiW", "name": "任务" }
  ]
}

2. Query single worksheet

GET https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}?operatorId={operatorId}

Return:

{ "id": "HAcL4SD", "name": "项目" }

3. Create new worksheet

POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets?operatorId={operatorId}
Content-Type: application/json

{
  "name": "新工作表名称",
  "fields": [
    { "name": "标题", "type": "text" },
    { "name": "数量", "type": "number" }
  ]
}

fields

is optional (empty worksheet is created if not passed).
Return:

{ "id": "新sheetId", "name": "新工作表名称" }

4. Delete worksheet

DELETE https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}?operatorId={operatorId}

Return:

{ "success": true }

⚠️ Unrecoverable, user confirmation is required before execution.

5. List fields

GET https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/fields?operatorId={operatorId}

Return:

json

{
  "value": [
    { "id": "6mNRNHb", "name": "标题", "type": "text" },
    { "id": "BDGLCo2", "name": "截止日期", "type": "date", "property": { "formatter": "YYYY-MM-DD" } },
    { "id": "mr8APlG", "name": "数量", "type": "number", "property": { "formatter": "INT" } }
  ]
}

6. Create new field

POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/fields?operatorId={operatorId}
Content-Type: application/json

{
  "name": "字段名称",
  "type": "number"
}

Common values for

type

text

(text),

number

(number),

date

(date)
Return:

{ "id": "新fieldId", "name": "字段名称", "type": "number", "property": { "formatter": "INT" } }

7. Update field

PUT https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/fields/{field_id}?operatorId={operatorId}
Content-Type: application/json

{
  "name": "新字段名称"
}

Return:

{ "id": "fieldId" }

(confirm the name has been changed by re-querying the list)

8. Delete field

DELETE https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/fields/{field_id}?operatorId={operatorId}

Return:

{ "success": true }

⚠️ Deleting a field will delete all data in this column at the same time, user confirmation is required before execution.

9. Add records (most commonly used operation)

POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/records?operatorId={operatorId}
Content-Type: application/json

{
  "records": [
    { "fields": { "标题": "任务一", "数量": 3 } },
    { "fields": { "标题": "任务二", "数量": 5 } }
  ]
}

Use field name (not ID) as the key in

fields

.
Return:

{ "value": [{ "id": "记录ID1" }, { "id": "记录ID2" }] }

10. Query record list

POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/records/list?operatorId={operatorId}
Content-Type: application/json

{
  "maxResults": 20,
  "nextToken": ""
}

Return:

json

{
  "records": [
    {
      "id": "RNXU1Vm2L2",
      "fields": { "标题": "任务一", "数量": 3 },
      "createdTime": 1772723541439,
      "createdBy": { "unionId": "xxx" },
      "lastModifiedTime": 1772723541439,
      "lastModifiedBy": { "unionId": "xxx" }
    }
  ],
  "hasMore": false,
  "nextToken": ""
}

Pagination: When the last response

hasMore=true

, pass

nextToken

to the next request.

11. Update record

PUT https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/records?operatorId={operatorId}
Content-Type: application/json

{
  "records": [
    { "id": "记录ID", "fields": { "标题": "新标题" } }
  ]
}

Return:

{ "value": [{ "id": "记录ID" }] }

Only pass the fields that need to be modified, the fields not passed remain unchanged.

12. Delete record

POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/records/delete?operatorId={operatorId}
Content-Type: application/json

{
  "recordIds": ["记录ID1", "记录ID2"]
}

Return:

{ "success": true }

Typical Scenarios

"Check what worksheets are in the AI Table"

Ask for the AI Table link, extract base_id
```
GET /sheets
```
to get the worksheet list
Display worksheet names and IDs

"Add several records to the 'Task' worksheet of the AI Table"

```
GET /sheets
```
to find the sheet_id of the target worksheet
```
GET /fields
```
to understand the existing field names and types
```
POST /records
```
to insert in batches, use field names as keys in fields
Inform that the writing is successful and the record IDs

"Query all records in the 'Task' table"

```
GET /sheets
```
to find sheet_id
```
POST /records/list
```
to get all records by pagination
Organize into table form for display

"Delete a record"

First
```
POST /records/list
```
to locate the target record (let user confirm)
```
POST /records/delete
```
to pass recordId
Inform that the deletion is successful

"Add a 'Remark' text field to the worksheet"

```
GET /sheets
```
to find sheet_id

POST /fields

{ "name": "备注", "type": "text" }

Return the new field ID and inform success

Field Type Reference

type	Meaning
`text`	Plain text
`number`	Number (including `property.formatter` : `INT` , `PERCENT` , etc.)
`date`	Date (including `property.formatter` : e.g. `YYYY-MM-DD` )

Error Handling

HTTP Status Code / code	Meaning	Handling Method
401	Token expired	Re-acquire accessToken
403	Insufficient permissions	Check if the application has enabled Notable related permissions
`invalidRequest.document.notFound`	Invalid base_id or no access permission	Confirm that the AI Table nodeId is correct and authorized
404	Worksheet or field does not exist	Confirm that sheet_id / field_id is correct
429	Rate limit triggered	Retry after waiting for 1 second

dingtalk-ai-table

NPX Install

Tags

SKILL.md Content (Chinese)

DingTalk AI Table Skill

Configuration Management (Must Read Before Each Start)

Configuration File Path

Configuration Instructions Required for This Skill

Startup Process (Before Each Task Execution)

Authentication

Why base_id is required

Why operatorId (unionId) is required

How to get unionId

Core Operations

1. List worksheets

2. Query single worksheet

3. Create new worksheet

4. Delete worksheet

5. List fields

6. Create new field

7. Update field

8. Delete field

9. Add records (most commonly used operation)

10. Query record list

11. Update record

12. Delete record

Typical Scenarios

"Check what worksheets are in the AI Table"

"Add several records to the 'Task' worksheet of the AI Table"

"Query all records in the 'Task' table"

"Delete a record"

"Add a 'Remark' text field to the worksheet"

Field Type Reference

Error Handling