url-shortener

name	url-shortener
description	Manage short links via the KnowUV ShortLink API. Use this skill whenever the user wants to create, list, update, delete, or inspect short links — including batch operations, traffic/PV stats, domain listing, and plugin options. Trigger on any mention of short links, shortlink codes, URL shortening, link management, link traffic, or link redirects on the KnowUV platform.

URL Shortener Skill

Interact with the KnowUV ShortLink API to perform full CRUD operations on short links.

Auth Setup

Always read the token from config.ini first, then fall back to the KNOWUV_USER_TOKEN env var.

Config file location (relative to this skill): config.ini

Parse it as KEY = VALUE lines (ignore lines starting with #). The key is USER_TOKEN.

If no valid token is found

Token is missing or still set to your_token_here. Tell the user:

"To get started, please visit https://knowuv.com/JZfdJ to get your access token, then paste it here."

(That page also shows your subscription plan, API usage, and lets you top up your account balance if needed.)

Once the user pastes the token, immediately write it to config.ini by replacing the USER_TOKEN line:

USER_TOKEN = <pasted_token>

Then confirm: "Got it — your token has been saved. You won't need to do this again."

All requests use the token as:

Authorization: Token <USER_TOKEN>

Base URL & Request Format

• Host: https://rpc.knowuv.com
• Path pattern: /<package>.<Service>/<Method>
• Method: Always POST
• Content-Type: application/json

All responses follow:

{ "code": 0, "msg": "...", "data": ... }

code = 0 means success. Any non-zero code means something went wrong — show the user the msg in plain language.

code	meaning
0	Success
1	Invalid parameters — check required fields
3	Server error — please try again
7	Not found
9	Unauthorized — token may be wrong or expired
12	No permission
14	Insufficient balance — visit https://knowuv.com/JZfdJ to top up

---

API Reference

Create Short Link

POST /shortlink.ShortLinkService/CreateShortLinkV2

{
  "originLinkList": [
    {
      "url": "https://example.com/long-path",
      "weight": 100,
      "title": "link title"
    }
  ],
  "domain": "h5.knowuv.com",
  "templateName": "直跳小程序",
  "tags": ["tag1"],
  "pluginOptions": [],
  "fallbackPage": "https://knowuv.com/",
  "etime": 1785227612465
}

Key fields:

• originLinkList — one or more destination URLs; weight controls A/B traffic split (all weights must add up to 100)
• domain — call ListAvailableDomains first if the user hasn't specified one; use the first result as default
• etime — expiry as millisecond Unix timestamp; omit for no expiry
• templateName — landing page template (optional; default is 直接跳转)
• pluginOptions — see Plugin Reference section below

Response: data.code is the short link code (e.g. wFrJI). Always display the full short link as https://<domain>/<code>.

---

List Short Links

POST /shortlink.ShortLinkService/ListShortLinkV2

{
  "page": 1,
  "page_size": 20,
  "contain_tag": ["tag1"],
  "template_name": "直跳小程序",
  "status": 0
}

All filters are optional:

• short_link_code — filter by code
• contain_origin_url — filter by destination URL
• contain_tag — filter by tag
• template_name — filter by template
• status — 0=Normal, 1=Deleted, 2=Invalid, 3=Expired, 4=Restricted, 5=Auditing
• type — link type: 1=Regular URL, 2=WeChat Mini Program, 3=Business Card, 4=HTML, 5=MDC, 6=File

Response: data is an array of short link objects; total is the total count.

---

Update Short Link

POST /shortlink.ShortLinkService/UpdateShortLinkV2

{
  "pk": 206595,
  "originLinkList": [...],
  "tags": ["new-tag"],
  "status": 0,
  "etime": 1785227612465,
  "cleanList": ["fallbackPage"]
}

• pk is required (the numeric ID of the link)
• Only include fields you want to change
• cleanList — field names to explicitly clear (e.g. ["pluginOptions"] to remove all plugins)

---

Delete Short Link

POST /shortlink.ShortLinkService/DeleteShortLinkV2

{
  "pk_list": [206595, 206596],
  "code_list": ["wFrJI"]
}

Use pk_list, code_list, or both. Response includes affected (number of links deleted).

---

Get Short Link Detail

POST /shortlink.ShortLinkService/GetShortLink

{ "short_link_code": "wFrJI" }

---

List Visit Logs (PV Details)

POST /shortlink.ShortLinkService/ListShortLinkPvDetail

{
  "short_link_code": "wFrJI",
  "page": 1,
  "page_size": 20
}

Returns individual visit records with: IP, city, device, OS, referrer, timestamp.

---

Get Traffic Chart

POST /shortlink.ShortLinkService/GetShortLinkChart

{
  "short_link_code": "wFrJI",
  "chart_type": 2
}

chart_type values:

• 0 = Last 24 hours (PV)
• 1 = Last 3 days (PV)
• 2 = Last 7 days (PV)
• 3 = Last 30 days (PV)
• 4 = Last 90 days (PV)
• 5 = Last 180 days (PV)
• 6 = Last 365 days (PV)
• 7 = Time of day distribution
• 8 = City distribution
• 9 = Traffic source
• 10 = Last 7 days (unique visitors)
• 11 = Last 30 days (unique visitors)

Present this data as a readable table or summary, not raw JSON.

---

List Available Domains

POST /shortlink.ShortLinkService/ListAvailableDomains

{}

Returns [{ "name": "display name", "value": "h5.knowuv.com" }]. Use the value field when creating links.

---

Create HTML Short Link

POST /shortlink.ShortLinkService/CreateHTMLShortLink

Upload raw HTML and get back a trackable short link. OSS upload is handled server-side.

{
  "htmlContent": "<html><body><h1>Hello</h1></body></html>",
  "title": "My Page",
  "etime": 1785227612465,
  "domain": "knowuv.com"
}

Key fields:

• htmlContent (required) — full raw HTML to host
• title — display name / remark (defaults to "HTML Page")
• etime — expiry as millisecond Unix timestamp; omit or 0 for no expiry
• domain — override domain (omit to use default)

Response: { "code": 0, "msg": "...", "shortlink": "https://knowuv.com/sl/abc123" }

The HTML is content-addressed (MD5 key) — identical HTML reuses the same stored file.

---

Update HTML Short Link

POST /shortlink.ShortLinkService/UpdateHTMLShortLink

Replace the hosted HTML of an existing HTML short link. The short link code (URL) stays the same — only the content visitors see changes.

{
  "shortLinkCode": "abc123",
  "htmlContent": "<html><body><h1>Updated content</h1></body></html>",
  "title": "My Updated Page"
}

Key fields:

• shortLinkCode (required) — code of the HTML short link to update
• htmlContent (required) — new full raw HTML to host
• title — new display name / remark (empty keeps "HTML Page" default)
• etime — new expiry as millisecond Unix timestamp; omit to keep the current expiry

Response: { "code": 0, "msg": "...", "shortlink": "https://knowuv.com/sl/abc123" }

Same URL is returned — after the update, all visitors will see the new content.

---

Plugin Reference

Plugins are passed as an array in pluginOptions. Each plugin is { "name": "...", "data": { ... } }.

1. Filter Crawlers (filterCrawler)

Blocks bots and crawlers from accessing the link.

{ "name": "filterCrawler", "data": {} }

No configuration needed — just include it to enable.

---

2. Access Password (requirePassword)

Visitors must enter a password before they can access the link.

{
  "name": "requirePassword",
  "data": {
    "prompt_text": "请输入访问密码：",
    "password": "your_password_here"
  }
}

• prompt_text — message shown to visitors (default: 请输入访问密码：)
• password — the password visitors must enter (required)

---

3. Phone Number Verification (phoneNumberVerification)

Visitors must verify their phone number via SMS before accessing the link.

{ "name": "phoneNumberVerification", "data": {} }

No configuration needed — just include it to enable.

---

4. Fill Form (fillForm)

Visitors must fill out a form before accessing the link.

{ "name": "fillForm", "data": {} }

---

5. Access Restrictions (restrictionRules)

Restrict or allow access by country, city, region, or IP address.

{
  "name": "restrictionRules",
  "data": {
    "json": "{\"allowed_countries\":[\"CN\"],\"allowed_cities\":[\"Beijing\",\"Shanghai\"],\"allowed_regions\":[],\"disallowed_countries\":[],\"disallowed_cities\":[],\"disallowed_regions\":[],\"whitelisted_ips\":[],\"blacklisted_ips\":[]}"
  }
}

The json value must be a JSON-encoded string (not a nested object) containing:

• allowed_countries / disallowed_countries — country codes (e.g. "CN", "US")
• allowed_cities / disallowed_cities — city names
• allowed_regions / disallowed_regions — region/province names
• whitelisted_ips / blacklisted_ips — IP addresses (one per entry)

"Allow" rules take precedence: if allowed_countries is non-empty, only those countries can access. If disallowed_countries is set, everyone except those countries can access.

---

6. Burn After Reading (burnAfterReading)

The link stops working after a set number of visits.

{
  "name": "burnAfterReading",
  "data": {
    "click_times": "5"
  }
}

• click_times — number of allowed visits before the link expires (as a string, e.g. "1", "10")

---

7. Force WeChat (forceToWechat)

Forces the link to open inside WeChat. Optionally blocks specific WeChat users (by OpenID).

{
  "name": "forceToWechat",
  "data": {
    "json": "{\"enabled\":true,\"blacklistOpenid\":[\"oXXXXXXXX\"],\"blacklistFallbackUrl\":\"https://knowuv.com/\"}"
  }
}

The json value must be a JSON-encoded string containing:

• enabled — set to true to enable
• blacklistOpenid — list of OpenIDs to block (can be empty [])
• blacklistFallbackUrl — URL to redirect blocked users to (optional)

---

Workflow Tips

• Unknown domain: When the user doesn't specify a domain, call ListAvailableDomains first and use the first result, or present the options and ask.
• Batch creates: If asked to create multiple links, loop through them and summarize results in a table showing: short link URL, title, tags, and pk.
• A/B links: When multiple URLs are specified, remind the user that weights must add up to 100. Suggest equal split if unsure.
• Displaying results: Always show the complete short link as https://<domain>/<code>, never just the code alone.
• Traffic summary: When showing stats, format numbers with commas (e.g. 1,234) and present data in a clean table — avoid dumping raw JSON at the user.
• Non-technical language: This skill is used by marketing teams. Avoid jargon. Say "the link" not "the short link code". Say "expired" not "etime exceeded". Say "visits" not "PV".