Lark HR Approval Bot
Use this when someone asks the HR leave bot to submit a Lark leave approval from chat
(e.g. "我要请明天年假,家里有事" or "帮我请 6 月 10 到 6 月 12 的 Sick Leave").
You (the agent) run the WHOLE flow yourself with your own tools, then SUBMIT the Lark approval.
Do NOT refuse, do NOT just describe, do NOT claim "the skill only formats" — drive the flow. If a
required config (approval_code / scope) is missing, FALL BACK to posting the approval summary card
to the chat — never fail the run. Never ask the user for tokens — your NyxID-brokered tools broker
all credentials.
How to run it
Resolve inputs. From the current Lark interaction, read the message text, sender open_id,
sender user_id, and chat_id. The leave-approval approval_code is BC26F7AB-3D6F-4F8F-90D0-9AC951651F23
(baked into the builder from the source flow); the user only needs to supply one if their HR
approval definition differs. If you received a raw Lark webhook body, normalize it first by
running the builder with {mode:"parse_event", body:<webhook body>}; for url_verification
return the webhookResponse and stop, and for non-message events stop.
Collect the employee contact record from Lark. Use NyxID-brokered Lark OpenAPI via
nyxid_proxy {slug:"api-lark-bot", path:"/open-apis/contact/v3/users/{openId}?user_id_type=open_id", method:"GET"}. Use data.user as userInfo; keep user_id, leader_user_id, and
department_ids. An equivalent lark_* contact tool is fine if your runtime exposes one.
Analyze the leave request with your own model. Convert relative dates using today's date and
return exactly:
{ "has_all_info": true|false, "leave_type_name": "<Annual Leave|Sick Leave|Off in Lieu|Unpaid Leave|Childcare Leave|Hospitalisation Leave|Reservist Leave|Maternity Leave|Paternity Leave|Marriage Leave>", "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "days": <number>, "reason": "<reason>", "reply_message": "<Chinese reply>" }.
Set has_all_info: false with a Chinese reply_message when any required field is missing.
Build the exact Lark payloads by running the bundled builder. Call
scripts/build_hr_approval_payload.js via code_execute with language: "javascript" (NO stdin
— inline the data): const {buildPayload}=require('./scripts/build_hr_approval_payload.js'); console.log(JSON.stringify(buildPayload({mode:"build_payloads", openId, userInfo:<Lark data.user>, aiResult:<analysis JSON>}))). Use the lark.*Body fields from its output. If you genuinely
cannot execute code, build the bodies by following references/hr-approval-contract.md
field-for-field.
Terminal — submit the approval and reply.
- If the builder returns
lark.moreInfoBody, send it with lark_messages_send /
lark_messages_reply (REST fallback nyxid_proxy {slug:"api-lark-bot", path:"/open-apis/im/v1/messages?receive_id_type=open_id", method:"POST", body:<moreInfoBody>}),
then stop.
- If the builder returns
lark.approvalBody, SUBMIT the leave approval with nyxid_proxy
{slug:"api-lark-bot", path:"/open-apis/approval/v4/instances", method:"POST", body:<lark.approvalBody>}. After the POST succeeds, send lark.successBody via
lark_messages_send / lark_messages_reply.
- If no
approval_code / scope OR the submit fails → FALL BACK to reply_with_interaction
(an approve/reject summary card) or a plain text summary of the leave request asking for manual
approval. Never fail the run.
Report one line: who it was for, the date range, and whether a Lark approval instance was
submitted, more info was requested, or a card fallback was posted.
Payload builder reference
scripts/build_hr_approval_payload.js exports buildPayload(data). Modes: parse_event (raw Lark
webhook body, directly or under body — returns a URL challenge response, a skip reason, or parsed
messageText / openId / userId / chatId) and build_payloads (default — pass event ids,
userInfo contact fields, and the analysis JSON). It normalizes openId, userId, leaderUserId,
departmentIds, and the model fields, maps the leave type id, and returns either lark.moreInfoBody
or lark.approvalBody + lark.successBody. Exact aliases, leave type ids, widget ids, the baked
approval_code, and examples are in references/hr-approval-contract.md.
Approval status tracking (typed tools)
After a successful submit, capture the returned instance_code and include it in your report.
For anything status-related, prefer the typed approval tools over raw nyxid_proxy:
lark_approvals_get {instance_code} (read-only, auto-approved): returns normalized status
(approved / rejected / withdrawn / terminated / running / none) plus is_terminal and
should_continue_waiting, with the task list and form data. Use it when the user asks how the
approval is going, before any resubmit (avoid duplicate instances), and to report the final
decision. Optional: locale (zh-CN/en-US/ja-JP), user_id_type (open_id/user_id/union_id).
lark_approvals_list {topic} (read-only): list approval tasks visible to the bot identity when
the instance_code is lost — topics todo/pending, done/completed, initiated, cc_unread,
cc_read.
lark_approvals_act {action, instance_code, task_id}: approve / reject / transfer a pending
task — ONLY when the user explicitly asks the bot to act on it; this one is not read-only, so a
human-approval card may appear before it executes.
Check once and report; do not busy-poll inside a chat turn. Offer to re-check on demand or via a
scheduled_agent_creator reminder instead.
Guardrails
- Use real returned data only: employee ids, leader ids, department ids, leave types, dates,
approval responses, and message status must come from the trigger, Lark, or the analysis output.
- Prefer running the bundled script; it is the deterministic source of truth for the approval and
message body shapes.
- Credentials and token exchange go through your NyxID-brokered tools; never ask the user for raw
tokens or secrets.
1---2name: hr-approval-bot-payload-builder3version: "2.3"4description: Runs the Lark HR approval bot flow end to end yourself — read the Lark leave request, look up the employee contact record, analyze the request, then SUBMIT the Lark leave approval and send the reply.5metadata:6 source: https://skillmd.com/skills/chronoaiproject/hr-approval-bot-payload-builder7 category: plain8 tag:9 - aevatar10 - s-capability11 - hr-approval12 - lark13 - lark-approval14 - payload-builder15 clawdbot:16 emoji: "memo"17 files:18 - "references/*"19 - "scripts/*"20---2122# Lark HR Approval Bot2324Use this when someone asks the HR leave bot to submit a Lark leave approval from chat25(e.g. "我要请明天年假,家里有事" or "帮我请 6 月 10 到 6 月 12 的 Sick Leave").2627**You (the agent) run the WHOLE flow yourself with your own tools, then SUBMIT the Lark approval.**28Do NOT refuse, do NOT just describe, do NOT claim "the skill only formats" — drive the flow. If a29required config (`approval_code` / scope) is missing, FALL BACK to posting the approval summary card30to the chat — never fail the run. Never ask the user for tokens — your NyxID-brokered tools broker31all credentials.3233## How to run it34351. **Resolve inputs.** From the current Lark interaction, read the message text, sender `open_id`,36 sender `user_id`, and `chat_id`. The leave-approval `approval_code` is `BC26F7AB-3D6F-4F8F-90D0-9AC951651F23`37 (baked into the builder from the source flow); the user only needs to supply one if their HR38 approval definition differs. If you received a raw Lark webhook body, normalize it first by39 running the builder with `{mode:"parse_event", body:<webhook body>}`; for `url_verification`40 return the `webhookResponse` and stop, and for non-message events stop.41422. **Collect the employee contact record from Lark.** Use NyxID-brokered Lark OpenAPI via43 `nyxid_proxy` `{slug:"api-lark-bot", path:"/open-apis/contact/v3/users/{openId}?user_id_type=open_id",44 method:"GET"}`. Use `data.user` as `userInfo`; keep `user_id`, `leader_user_id`, and45 `department_ids`. An equivalent `lark_*` contact tool is fine if your runtime exposes one.46473. **Analyze the leave request with your own model.** Convert relative dates using today's date and48 return exactly:49 `{ "has_all_info": true|false, "leave_type_name": "<Annual Leave|Sick Leave|Off in Lieu|Unpaid Leave|Childcare Leave|Hospitalisation Leave|Reservist Leave|Maternity Leave|Paternity Leave|Marriage Leave>", "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "days": <number>, "reason": "<reason>", "reply_message": "<Chinese reply>" }`.50 Set `has_all_info: false` with a Chinese `reply_message` when any required field is missing.51524. **Build the exact Lark payloads by running the bundled builder.** Call53 `scripts/build_hr_approval_payload.js` via `code_execute` with `language: "javascript"` (NO stdin54 — inline the data): `const {buildPayload}=require('./scripts/build_hr_approval_payload.js');55 console.log(JSON.stringify(buildPayload({mode:"build_payloads", openId, userInfo:<Lark data.user>,56 aiResult:<analysis JSON>})))`. Use the `lark.*Body` fields from its output. If you genuinely57 cannot execute code, build the bodies by following `references/hr-approval-contract.md`58 field-for-field.59605. **Terminal — submit the approval and reply.**61 - If the builder returns `lark.moreInfoBody`, send it with `lark_messages_send` /62 `lark_messages_reply` (REST fallback `nyxid_proxy` `{slug:"api-lark-bot",63 path:"/open-apis/im/v1/messages?receive_id_type=open_id", method:"POST", body:<moreInfoBody>}`),64 then stop.65 - If the builder returns `lark.approvalBody`, SUBMIT the leave approval with `nyxid_proxy`66 `{slug:"api-lark-bot", path:"/open-apis/approval/v4/instances", method:"POST",67 body:<lark.approvalBody>}`. After the POST succeeds, send `lark.successBody` via68 `lark_messages_send` / `lark_messages_reply`.69 - **If no `approval_code` / scope OR the submit fails → FALL BACK** to `reply_with_interaction`70 (an approve/reject summary card) or a plain text summary of the leave request asking for manual71 approval. Never fail the run.72736. **Report** one line: who it was for, the date range, and whether a Lark approval instance was74 submitted, more info was requested, or a card fallback was posted.7576## Payload builder reference7778`scripts/build_hr_approval_payload.js` exports `buildPayload(data)`. Modes: `parse_event` (raw Lark79webhook body, directly or under `body` — returns a URL challenge response, a skip reason, or parsed80`messageText` / `openId` / `userId` / `chatId`) and `build_payloads` (default — pass event ids,81`userInfo` contact fields, and the analysis JSON). It normalizes `openId`, `userId`, `leaderUserId`,82`departmentIds`, and the model fields, maps the leave type id, and returns either `lark.moreInfoBody`83or `lark.approvalBody` + `lark.successBody`. Exact aliases, leave type ids, widget ids, the baked84`approval_code`, and examples are in `references/hr-approval-contract.md`.8586## Approval status tracking (typed tools)8788After a successful submit, capture the returned `instance_code` and include it in your report.89For anything status-related, prefer the typed approval tools over raw `nyxid_proxy`:9091- `lark_approvals_get` `{instance_code}` (read-only, auto-approved): returns normalized `status`92 (`approved` / `rejected` / `withdrawn` / `terminated` / `running` / `none`) plus `is_terminal` and93 `should_continue_waiting`, with the task list and form data. Use it when the user asks how the94 approval is going, before any resubmit (avoid duplicate instances), and to report the final95 decision. Optional: `locale` (`zh-CN`/`en-US`/`ja-JP`), `user_id_type` (`open_id`/`user_id`/`union_id`).96- `lark_approvals_list` `{topic}` (read-only): list approval tasks visible to the bot identity when97 the instance_code is lost — topics `todo`/`pending`, `done`/`completed`, `initiated`, `cc_unread`,98 `cc_read`.99- `lark_approvals_act` `{action, instance_code, task_id}`: approve / reject / transfer a pending100 task — ONLY when the user explicitly asks the bot to act on it; this one is not read-only, so a101 human-approval card may appear before it executes.102103Check once and report; do not busy-poll inside a chat turn. Offer to re-check on demand or via a104`scheduled_agent_creator` reminder instead.105106## Guardrails107108- Use real returned data only: employee ids, leader ids, department ids, leave types, dates,109 approval responses, and message status must come from the trigger, Lark, or the analysis output.110- Prefer running the bundled script; it is the deterministic source of truth for the approval and111 message body shapes.112- Credentials and token exchange go through your NyxID-brokered tools; never ask the user for raw113 tokens or secrets.