管理 Keepp 页面
什么是 Keepp
Keepp 将创作者或小企业的社交链接页面转化为一个页面:一个可分享的集合,包含产品“卡片”和链接,旨在将关注者转化为买家并获取线索。它被卖家、联盟营销者、教练、课程创作者以及 Instagram、YouTube、TikTok、Pinterest 和 X 上的链接简介创作者广泛使用。
一个 Keepp 页面由以下部分组成:
- 个人资料 — 头像、显示名称、简短简介
- 社交图标 — 指向所有者社交账户的链接
- 链接块 — 指向网站、预约页面、WhatsApp 等的按钮(以及分区标题)
- 目录卡片 — 可购买的产品卡片(图片、价格、促销代码、行动按钮)
- 模式 —
仅链接、仅目录或链接与目录
此 API 控制的内容
此 API 管理两件事:
- 目录卡片(帖子) — 创建、列出、更新和删除所有者目录中的产品卡片。
- 页面设置 — 页面的布局模式、关于文本、英雄按钮、目录卡片默认值和主题(请参阅下方“页面设置”)。
通过此 API 无法更改的内容:社交图标、链接块 和 个人资料详细信息(显示名称、头像、页面 URL)。这些内容由所有者通过 Keepp 仪表盘设置——如果用户询问,请引导其前往 Keepp 仪表盘。
身份认证
每次请求都需要所有者的 API 密钥作为 Bearer 令牌:
Authorization: Bearer keepp_live_…
基础 URL:https://api.keepp.link。密钥由 Pro 账户在仪表盘的 AI Agent 下生成。如果您没有密钥,请向用户索取。
端点
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/v1/posts?cursor= | 列出目录中的卡片(分页)。 |
| POST | /api/v1/posts | 创建一张卡片。 |
| GET | /api/v1/posts/:postId | 获取一张卡片。 |
| PATCH | /api/v1/posts/:postId | 更新一张卡片。 |
| DELETE | /api/v1/posts/:postId | 删除一张卡片。 |
卡片内容模型
创建/更新卡片时需提供三个顶级字段:imageUrls、userContent 和 cardOverrides。
{
"imageUrls": ["https://…/photo.jpg"], // 最多 5 张;系统会为您获取并存储。每张 ≤10MB,JPEG/PNG/WebP/GIF 格式,需为公开的直接 URL
"userContent": {
"name": "真丝围巾", // 简短标题(可选)
"description": "手工染色桑蚕丝,90×90cm。", // 必填
"price": "$72", // 自由文本 — "$72"、"From $50"、"₹1,499"(可选)
"promoCode": "SAVE15", // 促销 / 推荐 / 折扣代码(可选)
"category": "accessories", // 下方类别之一(可选)
"links": ["https://…"], // 卡片上显示的额外链接(可选)
"contacts": [{ "type": "whatsapp", "value": "+15551234567" }] // 可选
},
"cardOverrides": { // 卡片行为(可选;省略则继承页面默认值)
"clickAction": "open_detail", // "open_detail" | "trigger_cta"
"ctaType": "link", // "message" | "link" | "lead_collection"
"ctaUrl": "https://shop…/scarf", // 当 ctaType 为 "link" 时必填
"ctaLabel": "立即购买" // 按钮文本
}
}
description 是唯一必填字段。其他均为可选;省略 cardOverrides 将继承所有者页面的全局默认值。
类别: clothing、jewellery、accessories、home_decor、beauty、food_beverage、art、stationery、plants、fitness、travel、real_estate、services、pets、kids_baby、books_media、crafts、other。
联系方式类型: phone、email、whatsapp、telegram、other。
卡片行为——两种决策
1. clickAction — 点击卡片时的行为:
open_detail(默认)— 打开详细视图(全部图片、完整描述、价格、促销代码、行动按钮)。适用于买家在行动前需要了解上下文的情况。trigger_cta— 点击后直接触发行动,不显示详情屏幕。适用于自解释商品,旨在最小化操作步骤。
2. ctaType — 行动按钮的功能:
message— 打开向商家发送消息的界面。当没有结账链接时的安全默认值。link— 打开ctaUrl(Shopify/Etsy 页面、联盟链接、预约页面、Google 表单)。需要ctaUrl。适用于有专用目标链接的情况。lead_collection— 在页面上打开一个简短表单,捕获访问者的联系方式并保存为线索。适用于捕获尚未准备购买的人群(候补名单、销售名单、咨询)。收集的字段通过页面设置端点中的catalogCard.leadCollection在页面级别设置(详见下方)——这些设置适用于所有卡片,而非每张卡片独立设置。
将 ctaLabel 设置为与行动匹配的文本:"Buy now"、"Order now"、"Get the lookbook"、"Reserve yours"、"Get notified"。
页面设置
读取和更改页面的整体配置。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/v1/storefront | 获取当前页面设置。 |
| PATCH | /api/v1/storefront | 更改设置。仅发送您要更改的字段——它们会合并到当前配置中。 |
可编辑字段:
{
"mode": "links_and_catalog", // "links_only" | "catalog_only" | "links_and_catalog"
"about": "来自里斯本工作室的手工陶瓷。", // 页面简短标语(≤280 字符)
"mainCta": { // 页面顶部的英雄按钮
"enabled": true,
"label": "预约通话",
"url": "https://cal.com/me" // 启用时必填
},
"catalogCard": { // 所有卡片的页面级别默认值
"showCardDetails": true,
"clickAction": "open_detail", // "open_detail" | "trigger_cta"
"ctaType": "message", // "message" | "link" | "lead_collection"
"ctaUrl": "https://…", // 当 ctaType 为 "link" 时必填
"ctaLabel": "立即下单",
"leadCollection": { "phone": true, "email": true, "instagram": false, "message": true }
},
"theme": {
"useCustomTheme": true, // 必须为 true,否则 preset/brandColor 不会生效
"preset": "professional", // "calm" | "professional" | "playful" | "dark"
"brandColor": "#d7494c" // 6 位十六进制颜色
}
}
- 部分更新会合并。
PATCH {"theme":{"useCustomTheme":true,"brandColor":"#000000"}}仅更改主题;模式、卡片等保持不变。 - 主题保护: 除非
useCustomTheme为true,否则preset/brandColor会被忽略——请在同一请求中发送useCustomTheme。 catalogCard是所有卡片的默认值。 卡片的cardOverrides(见上文)的优先级高于这些设置。更改这些设置可一次性重新样式化所有卡片。leadCollection设置页面级线索表单收集哪些字段(没有按卡片单独选择字段)。- 无效组合会被拒绝并返回
400 INVALID_STOREFRONT_CONFIG(例如ctaType:"link"但未提供ctaUrl)。
用例示例
联盟营销/网红产品 + 促销代码 → 外部链接
{
"imageUrls": ["https://example.com/serum.jpg"],
"userContent": { "name": "维生素C精华", "description": "我的每日焕肤精华——使用我的代码享受 15% 折扣。", "price": "$28", "promoCode": "GLOW15", "category": "beauty" },
"cardOverrides": { "clickAction": "trigger_cta", "ctaType": "link", "ctaUrl": "https://brand.com/serum?ref=me", "ctaLabel": "使用我的代码购买" }
}
通过自有商店销售精品产品
{
"imageUrls": ["https://example.com/scarf.jpg"],
"userContent": { "name": "真丝围巾", "description": "手工染色桑蚕丝,90×90cm。", "price": "$72", "category": "accessories" },
"cardOverrides": { "clickAction": "open_detail", "ctaType": "link", "ctaUrl": "https://myshop.com/scarf", "ctaLabel": "立即购买" }
}
教练/服务——捕获线索而非直接销售
{
"imageUrls": ["https://example.com/program.jpg"],
"userContent": { "name": "1对1辅导", "description": "6周项目,帮你获得前5个客户。", "price": "From $400", "category": "services" },
"cardOverrides": { "clickAction": "trigger_cta", "ctaType": "lead_collection", "ctaLabel": "立即申请" }
}
响应与错误
成功:{ "ok": true, "data": { … } }。错误:{ "ok": false, "error": { "code": "…", "message": "…" } }。
401 NO_API_TOKEN/INVALID_API_TOKEN— 密钥缺失或已撤销。请向用户索取有效密钥。403 PLAN_REQUIRED— 账户不是 Pro 版本。422 INVALID_IMAGE— 无法获取图片 URL,或类型/大小错误、重定向或解析为私有地址。请使用直接、公开的https图片 URL。429 RATE_LIMITED— 每分钟超过 60 次请求。请降低频率后重试。
指导
- 删除卡片前请与用户确认。
- 只要有
price和promoCode,请务必设置它们——它们会显示在卡片和详情视图中,是联盟营销和促销场景的核心。 - 批量创建时,请保持每分钟不超过 60 次请求。
- 卡片会立即发布到页面上。
- 您可以管理卡片和页面设置(模式、关于文本、英雄按钮、卡片默认值、主题)。对于链接、社交图标和个人资料详情(名称、头像、页面 URL),请告知用户使用 Keepp 仪表盘。
更多信息
Keepp 的使用指南详细介绍了 Keepp 页面: