wecomcli-crm

WeCom CRM Customer Management

Use wecom-cli to operate WeCom smart sheets and complete customer data management.

Initial Configuration (Required)

Before performing any CRM operation, first check whether CRM configuration already exists in memory. If not, guide the user through the following process:

Step 1: Get the CRM sheet URL

Ask the user:

"Please provide the link to your CRM customer management smart sheet (open the sheet in WeCom → Share in the upper right corner → Copy link)"

Step 2: Discover the sheet structure

Use the URL provided by the user to automatically discover sub-sheets and fields:

# 获取子表列表
wecom-cli doc smartsheet_get_sheet '{"url": "<用户提供的URL>"}'

# 获取第一个子表的字段定义
wecom-cli doc smartsheet_get_fields '{"url": "<用户提供的URL>", "sheet_id": "<从上一步获取>"}'

Step 3: Save the configuration to memory

Save the following information to the memory file crm-config.md：

---
name: crm-config
description: CRM 智能表格配置信息，包含 URL、sheet_id 和字段 schema
type: project
---

## CRM 表配置

- URL: <用户提供的URL>
- sheet_id: <从 API 获取>
- 子表名称: <从 API 获取>

## 字段 Schema
<从 smartsheet_get_fields 返回结果中记录每个字段的 field_title、field_type、选项列表>

Step 4: Subsequent operations

After the configuration is saved, all CRM operations read the URL and sheet_id directly from memory without asking again.

---

Operation Process

In the following commands, <URL> and <SHEET_ID> are read from crm-config in memory.

1. Query customers

wecom-cli doc smartsheet_get_records '{"url": "<URL>", "sheet_id": "<SHEET_ID>"}'

Return all records and record_id。Before updating and deleting, you must query first to obtain the record_id.

2. Add customer

wecom-cli doc smartsheet_add_records '{"url": "<URL>", "sheet_id": "<SHEET_ID>", "records": [{"values": {<字段值>}}]}'

The field value format depends on the field type. See "Field Type Write Format" below for details.

Batch is supported;records array can contain up to 500 entries at a time.

3. Update customer

Must pass key_type, otherwise the field title cannot be recognized:

wecom-cli doc smartsheet_update_records '{"url": "<URL>", "sheet_id": "<SHEET_ID>", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORD_ID", "values": {<需更新的字段>}}]}'

• key_type is fixed to "CELL_VALUE_KEY_TYPE_FIELD_TITLE"
• values only pass the fields that need to be modified
• Created time, edited time, created by, and edited by fields cannot be updated

4. Delete customer

wecom-cli doc smartsheet_delete_records '{"url": "<URL>", "sheet_id": "<SHEET_ID>", "record_ids": ["RECORD_ID"]}'

Deletion is irreversible, confirm the record_id before calling. Batch is supported;record_ids array can contain up to 500 entries at a time.

---

Field Type Write Format (General Rules)

Regardless of the specific field names in the user's sheet, the write format is determined by the field type:

Field Type	Write Format	Example
TEXT	[{"type":"text","text":"值"}]	Text fields such as company name, notes, etc.
SINGLE_SELECT	[{"text":"选项文本"}]	Single-select fields such as status, industry, etc.
PHONE_NUMBER	Pass the string directly	"13800138000"
USER	[{"userid":"用户ID"}]	Personnel fields such as sales, delivery, etc.

For detailed instructions and webhook format, see crm-schema.md。

---

Practical Notes

Common Pitfalls

1. Not passing key_type when updating — the field title cannot be recognized; it must include "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE"
2. PHONE_NUMBER used TEXT format — the contact phone is not a text field; pass the string directly, do not use [{"type":"text","text":"..."}]
3. Did not query before deleting/updating — record_id can only be obtained from query results; adding also returns record_id
4. USER field key name — in the CLI it is userid, in webhook it is user_id, the two are different
5. Option text must match exactly — The text passed to SINGLE_SELECT must exactly match the existing option text in the table

Auxiliary commands

# 重新查表结构（字段变更时用）
wecom-cli doc smartsheet_get_fields '{"url": "<URL>", "sheet_id": "<SHEET_ID>"}'

# 查通讯录（获取 userid 用于 USER 字段）
wecom-cli contact get_userlist '{}'