From 3c22cbbf36e90eeb841458690999871449a1a7e4 Mon Sep 17 00:00:00 2001 From: andy-knock Date: Fri, 28 Aug 2026 15:20:50 -0400 Subject: [PATCH 1/2] aaa --- .cursor/rules/styleguide.mdc | 1 + AGENTS.md | 1 + content/ai/agent.mdx | 4 +- content/cli/goal.mdx | 474 ++++++++++++++++++ content/cli/overview.mdx | 2 + content/cli/resources.mdx | 6 +- content/concepts/broadcasts.mdx | 2 + content/concepts/goals.mdx | 193 +++++++ content/concepts/guides.mdx | 2 + content/concepts/overview.mdx | 6 + content/concepts/workflows.mdx | 4 + .../wait-for-event-function.mdx | 2 + content/developer-tools/management-api.mdx | 1 + content/getting-started/what-is-knock.mdx | 1 + content/version-control/environments.mdx | 3 + data/sidebars/cliSidebar.ts | 17 + data/sidebars/mapiOverviewSidebar.ts | 1 + data/sidebars/platformSidebar.ts | 1 + data/specs/mapi/customizations.yml | 4 + data/specs/mapi/stainless.yml | 13 + 20 files changed, 733 insertions(+), 5 deletions(-) create mode 100644 content/cli/goal.mdx create mode 100644 content/concepts/goals.mdx diff --git a/.cursor/rules/styleguide.mdc b/.cursor/rules/styleguide.mdc index 207a3f87a..ff68eb057 100644 --- a/.cursor/rules/styleguide.mdc +++ b/.cursor/rules/styleguide.mdc @@ -42,6 +42,7 @@ Here is a list of Knock concept/feature names that should not be capitalized unl - Messages - Environments - Audiences +- Goals ## Case: always use sentence case diff --git a/AGENTS.md b/AGENTS.md index 7444e9635..4d6b7d238 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -111,6 +111,7 @@ Here is a list of Knock concept/feature names that should not be capitalized unl - Messages - Environments - Audiences +- Goals ## Case: always use sentence case diff --git a/content/ai/agent.mdx b/content/ai/agent.mdx index 5fbf96191..334298d20 100644 --- a/content/ai/agent.mdx +++ b/content/ai/agent.mdx @@ -49,11 +49,11 @@ You can optionally use the Knock agent directly from your Slack workspace using ### Read and inspect resources -The agent has full access to all of your Knock resources, including workflows, broadcasts, partials, email layouts, audiences, message types, and guides. +The agent has full access to all of your Knock resources, including workflows, broadcasts, partials, email layouts, audiences, message types, guides, and goals. ### Create and modify resources -The agent can create or update workflows, broadcasts, partials, email layouts, audiences, message types, and guides using dedicated tools. Each maps to a customer messaging primitive you manage in the dashboard. +The agent can create or update workflows, broadcasts, partials, email layouts, audiences, message types, guides, and goals using dedicated tools. Each maps to a customer messaging primitive you manage in the dashboard. ### Bulk updates and refactors diff --git a/content/cli/goal.mdx b/content/cli/goal.mdx new file mode 100644 index 000000000..29c549554 --- /dev/null +++ b/content/cli/goal.mdx @@ -0,0 +1,474 @@ +--- +title: Goals +description: Commands for managing goals in the Knock CLI. +--- + +
+ + +Goal commands enable you to manage [goals](/concepts/goals) in your Knock account from the CLI. + + +
+ +
+ + +When goals are pulled from Knock, they are stored in directories named by their goal key. Each goal directory contains a `goal.json` file that describes the goal's configuration (name, description, and condition). + +{/* prettier-ignore */} + +{`goals/ +└── trial-conversion/ + └── goal.json`} + + +If you're migrating your local goal files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using [`knock goal push --all`](/cli/goal/push). + +To attach a goal to a workflow, broadcast, or guide, set `goal_attachment` on that resource's JSON (`goal_key` and `attribution_window_days`). Attachments are not stored on the goal itself. + + +
+ +
+ + +Display all goals for an environment. Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment. + +### Flags + + + + + + + + + + + + + +```bash title="Basic usage" +knock goal list +``` + +```bash title="Pagination example" +knock goal list --after=xxx +``` + + +
+ +
+ + +Display a single goal from an environment. + +Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment. + +### Flags + + + + + + + + + + +```bash title="Basic usage" +knock goal get trial-conversion +``` + +```bash title="Get goal in a different environment" +knock goal get trial-conversion --environment=production +``` + + +
+ +
+ + +Pull one or more goals from an environment into a local file system. Knock CLI will create a new goal directory or update the existing goal directory in the local file system. + +By default this command will resolve to the goals resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--goals-dir` flag. + +Note: if pulling the target goal for the first time (or all goals), Knock CLI will ask to confirm before writing to the local file system. + +See the [Goal file structure](/cli/goal/file-structure) section for details on how goal files are organized. + +### Flags + + + + + + + + + + + + + +```bash title="Basic usage" +knock goal pull trial-conversion +``` + +```bash title="Pulling a goal in a different environment" +knock goal pull trial-conversion --environment=production +``` + +```bash title="Pulling all goals into ./goals directory" +knock goal pull --all --goals-dir=./goals +``` + + +
+ +
+ + +Push one or more goals from a local file system to Knock. Knock will update an existing goal by the matching goal key, or create a new goal if it does not exist yet. Goal upserts publish immediately; this command does not accept a `--commit` flag. + +By default this command will resolve to the goals resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--goals-dir` flag. + +Note: + +- You must be directly above the target goal directory when running the `goal push` command, so the CLI can locate the `goal.json` file. +- Use `--force` to bypass environment restrictions and overwrite content in any environment. + +See the [Goal file structure](/cli/goal/file-structure) section for details on how goal files are organized. + +### Flags + + + + + + + + + + + + +```bash title="Basic usage" +knock goal push trial-conversion +``` + +```bash title="Pushing all goals from ./goals directory" +knock goal push --all --goals-dir=./goals +``` + + +
+ +
+ + +Validate one or more goals from a local file system. Knock will validate the given goal payload in the same way as it would with the `goal push` command, except without persisting those changes. + +### Flags + + + + + + + + + + + +```bash title="Basic usage" +knock goal validate trial-conversion +``` + + +
+ +
+ + +Create a new goal with a minimal configuration. The command creates a new goal directory in your local file system. By default, this will be in the goals resource directory set by your `knock.json` file, or the current working directory if not configured. + +### Flags + + + + + + + + + + + + + + +```bash title="Create a goal interactively" +knock goal new +``` + +```bash title="Create a goal" +knock goal new --key=trial-conversion --name="Trial conversion" +``` + +```bash title="Create and push a goal" +knock goal new --key=trial-conversion --name="Trial conversion" --push +``` + + +
+ +
+ + +Open a goal in the Knock dashboard. This command opens the goal page in your default browser. + +### Flags + + + + + + + + + +```bash title="Basic usage" +knock goal open trial-conversion +``` + +```bash title="Open a goal in a different environment" +knock goal open trial-conversion --environment=production +``` + + +
+ +
+ + +Archive a goal. Archiving stops new completion and attribution calculation for the goal and cannot be undone. Historical versions and completions are retained. + + + +### Flags + + + + + + + + + + +```bash title="Basic usage" +knock goal archive trial-conversion --environment=development +``` + + +
+ +
+ + +Clone a goal into a destination environment. Cloning copies the latest version of the goal (name, description, and condition). It does not copy attachments to workflows, broadcasts, or guides. + +### Flags + + + + + + + + + + + + +```bash title="Clone a goal into production" +knock goal clone trial-conversion \ + --environment=development \ + --destination-environment=production +``` + +```bash title="Clone with a custom key and name" +knock goal clone trial-conversion \ + --environment=development \ + --destination-environment=production \ + --key=trial-conversion-prod \ + --name="Trial conversion" +``` + + +
diff --git a/content/cli/overview.mdx b/content/cli/overview.mdx index f8f612534..269ef3116 100644 --- a/content/cli/overview.mdx +++ b/content/cli/overview.mdx @@ -165,6 +165,8 @@ When you use `knock pull`, resources will be grouped by resource type within sub {/* prettier-ignore */} {`./knock/ +├── audiences/ +├── goals/ ├── guides/ ├── layouts/ ├── message-types/ diff --git a/content/cli/resources.mdx b/content/cli/resources.mdx index 70e5fc73c..6e3c94771 100644 --- a/content/cli/resources.mdx +++ b/content/cli/resources.mdx @@ -6,7 +6,7 @@ description: Commands for managing all Knock resources at once.
-These commands enable you to manage all Knock resources (workflows, partials, email layouts, translations, guides, message-types, and audiences) at once. +These commands enable you to manage all Knock resources (workflows, partials, email layouts, translations, guides, message-types, audiences, and goals) at once.
@@ -39,7 +39,7 @@ knock init
-Pulls the contents of all Knock resources (workflows, partials, email layouts, translations, guides, message-types, and audiences) from Knock into your local file system. +Pulls the contents of all Knock resources (workflows, partials, email layouts, translations, guides, message-types, audiences, and goals) from Knock into your local file system. Resources will be grouped by resource type within subdirectories of the target directory path set either by your `knock.json` file or by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands. @@ -86,7 +86,7 @@ knock pull --knock-dir=./.knock
-Pushes all local resource files (workflows, partials, email layouts, translations, guides, message-types, and audiences) back to Knock and upserts them. +Pushes all local resource files (workflows, partials, email layouts, translations, guides, message-types, audiences, and goals) back to Knock and upserts them. Resources will be pushed to the target directory path set either by your `knock.json` file or by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands. diff --git a/content/concepts/broadcasts.mdx b/content/concepts/broadcasts.mdx index 01ffeeb13..59c1be88a 100644 --- a/content/concepts/broadcasts.mdx +++ b/content/concepts/broadcasts.mdx @@ -96,6 +96,8 @@ Broadcasts can optionally be scheduled to send at a specific time. When a broadc Broadcasts produce messages, exactly as workflows do. As such, messages sent as part of a broadcast will be visible in the **Analytics** page within the Knock dashboard. Additionally, broadcast engagement metrics are available in any [connected data warehouses](/integrations/extensions/data-sync). +You can also [attach a goal](/concepts/goals) to a broadcast to measure attributed completions against a defined outcome. + Sent broadcasts include a recipient summary that highlights key delivery and engagement metrics, including: - **Sent**: The number of messages that were successfully sent to the delivery provider. diff --git a/content/concepts/goals.mdx b/content/concepts/goals.mdx new file mode 100644 index 000000000..dd519d768 --- /dev/null +++ b/content/concepts/goals.mdx @@ -0,0 +1,193 @@ +--- +title: Goals +description: Learn how to define measurable outcomes, attach them to messaging, and track attributed completions in Knock. +tags: + [ + "goals", + "attribution", + "conversions", + "completions", + "outcomes", + "analytics", + "workflows", + "broadcasts", + "guides", + ] +section: Concepts +--- + +A goal is a reusable, environment-scoped outcome that you identify as having special business meaning. For example, you might define a "Customer activated" goal that completes when a user creates their first channel or starts an agent session. + +Each goal has an immutable `key`, a title, an optional description, a condition that defines when the goal is met, and versions. When a recipient meets the goal condition, Knock records a **completion**. When that completion can be credited to a [workflow](/concepts/workflows), [broadcast](/concepts/broadcasts), or [guide](/concepts/guides) that has the goal attached, Knock also records an **attributed completion**. + +Use goals to: + +- Tell Knock what you are trying to accomplish with customer messaging, beyond opens and clicks. +- Measure how often an outcome happens, and how often messaging can be credited for it. +- Give the [Knock agent](/ai/agent) context about intent so it can propose and improve messaging against those outcomes. + +## Creating a goal + +To create a goal, navigate to the **Goals** page in the Knock dashboard, then create a new goal. Set: + +- **Key.** An immutable, environment-unique identifier for the goal. +- **Title.** A human-readable name for the goal. In the Management API and CLI, this field is `name`. +- **Description.** Optional context about what the goal means for your business. +- **Condition.** The event that must happen for Knock to record a completion. See [Goal conditions](#goal-conditions). + +Goals are scoped to an [environment](/concepts/environments). When you save a goal, Knock publishes it immediately. Goals do not use the commit-and-promote model that workflows and other versioned resources use. + +### Cloning a goal + +You can [clone a goal](/version-control/environments#clone-resources-across-environments) into the same environment or another environment. Cloning copies the latest version of the goal (key, title, description, and condition). It does **not** copy attachments to workflows, broadcasts, or guides. + +Goals are not promotable between environments. To use the same goal definition elsewhere, clone it. + +### Archiving a goal + +Archiving a goal soft-deletes it. Knock stops calculating new completions and attributions for the archived goal, and retains historical versions and completions. You cannot un-archive a goal. + +## Goal conditions + +A goal condition defines what must happen for Knock to record a completion. Goal conditions reuse a subset of the event model from the [wait for event function](/designing-workflows/wait-for-event-function), with one important difference: Knock evaluates goal conditions **globally for a recipient** when the event happens, not inside a workflow run. Match filters therefore use `event` and `recipient` only. They do not have access to workflow run state such as `data`, `refs`, or `run`. + +Supported event types: + +| Event type | Description | Match conditions | +| --- | --- | --- | +| **Integration source** | An event from a connected [integration source](/integrations/sources/overview), such as Segment or Stripe. | Optional. Filter on event properties under `event.*`. | +| **Audience entry / exit** | A recipient enters or exits an [audience](/concepts/audiences). | Not required. | +| **Recipient updated** | A [user](/concepts/users) property changes. | Required. Filter on recipient properties under `recipient.*`. | + +For supported operators, see the [conditions docs](/concepts/conditions). + +Goal conditions do not support message events, workflow run events, wait timeouts, or on-match / on-timeout controls. Those remain wait for event–only concepts. + +### Example: recipient property updated + +```json +{ + "event": { + "event_type": "recipient", + "event_key": "updated" + }, + "match_conditions": [ + { + "operator": "and", + "conditions": [ + { + "variable": "recipient.is_paid", + "operator": "equal_to", + "argument": "true" + } + ] + } + ] +} +``` + +### Example: source event with a property filter + +```json +{ + "event": { + "event_type": "integration_source", + "event_key": "order.completed", + "integration_source_key": "stripe" + }, + "match_conditions": [ + { + "operator": "and", + "conditions": [ + { + "variable": "event.data.amount", + "operator": "greater_than", + "argument": "0" + } + ] + } + ] +} +``` + +## Attaching a goal to messaging + +You can attach a goal to a [workflow](/concepts/workflows), [broadcast](/concepts/broadcasts), or [guide](/concepts/guides): + +- One goal can be attached to many messaging resources. +- Each messaging resource can have at most one attached goal. + +A goal attachment includes: + +- **Goal key.** The key of the goal to attach. +- **Attribution window.** The number of days after the attribution anchor during which a completion can be credited to the resource. Defaults to 7 days. Maximum is 30 days. Granularity is 1 day. + +The attachment lives on the messaging resource's version. Attaching, detaching, or changing the attribution window creates a new version of that workflow, broadcast, or guide, and follows that resource's [commit](/version-control/commits) model. + +## Attribution + +When a recipient meets a goal condition, Knock always records a **completion**. If the goal is attached to one or more messaging resources, Knock then decides whether the completion is an **attributed completion**. + +### Attribution window and anchor + +The attribution window is set per attachment when you attach the goal. The window starts at a per-recipient **attribution anchor**: + +- **Workflows and broadcasts.** First message sent to the recipient for the most recent run of that resource. +- **Guides.** Guide message created for the recipient (this happens asynchronously). + +A resource is **eligible for attribution** when its attribution anchor falls within the attachment's window relative to the completion time. + +### Last-touch attribution + +If multiple attached resources are eligible for the same completion, Knock attributes the completion to the resource that messaged the recipient most recently (last touch). + +### Example: attribution window + +Goal 1 is attached to Workflow A (7-day window) and Guide B (30-day window). Recipient X receives messaging from: + +- Workflow A, 1 day ago and 8 days ago +- Guide B, 6 days ago + +Is Workflow A inside its attribution window? + +- No. The first message sent for the most recent Workflow A run was 8 days ago, and the attachment has a 7-day window. + +### Example: last touch + +Goal 1 is attached to Workflow A and Guide B. Both attachments have a 30-day window. Recipient X receives messaging from: + +- Workflow A, 1 day ago and 8 days ago +- Guide B, 6 days ago + +Both resources are inside their windows. Last touch was Workflow A, so Knock attributes the completion to **Workflow A**. + +## Reporting + +On the **Goals** page in the dashboard, you can view all goals in the current environment. Open a goal to see: + +- **Completions.** Every time a recipient met the goal condition. +- **Attributed completions.** The subset of completions Knock credited to an attached messaging resource. You can filter attributed completions by resource. + +Attributed completions are a strict subset of completions. Attribution for analytics can take up to about 15 minutes to appear after a completion. + +Resource-level conversion metrics on workflow, broadcast, and guide analytics pages are not included in this release. Use the goal detail page and resource filters instead. + +## Goals and the Knock agent + +The [Knock agent](/ai/agent) has full read access to goals and their fields. The agent can propose and create goals, reuse an existing goal, or define a new one when building or improving messaging. Goal context helps the agent reason about what your messaging is trying to accomplish, even when a goal is not yet attached to a resource. + +## Managing goals programmatically + +You can create, update, clone, and archive goals, and attach them to messaging resources, with the [Management API](/mapi-reference/goals) and the [Knock CLI](/cli/goal). + +Goal upserts publish immediately. Unlike workflows and guides, the goals upsert endpoint does not accept a commit parameter. Attachments are stored on the workflow, broadcast, or guide as a `goal_attachment` (`goal_key` and `attribution_window_days`). + +## Limitations + +The following are not available in this release: + +- Using a goal as exit criteria to cancel an in-flight workflow run. +- Tenant-property goal conditions. +- Attaching more than one goal to a single messaging resource. +- Goal conversion metrics on the workflow, broadcast, or guide analytics pages. +- Promoting goals between environments (clone a goal instead). diff --git a/content/concepts/guides.mdx b/content/concepts/guides.mdx index 81a6621c1..e12340c56 100644 --- a/content/concepts/guides.mdx +++ b/content/concepts/guides.mdx @@ -37,6 +37,8 @@ Guides include an analytics summary that highlights key metrics over the last N To learn more, see our [message status documentation](/send-notifications/message-statuses). +You can also [attach a goal](/concepts/goals) to a guide to measure attributed completions against a defined outcome. + ## Guides pricing Guides usage is priced using **engaged users**, which is the distinct number of users who have **seen** or **engaged** with a guide in the billing period. diff --git a/content/concepts/overview.mdx b/content/concepts/overview.mdx index 93a88b16f..a92630d62 100644 --- a/content/concepts/overview.mdx +++ b/content/concepts/overview.mdx @@ -123,3 +123,9 @@ Variables within Knock let you set shared constants or secrets that you can use Audiences are user segments that you can notify. You can bring audiences into Knock programmatically with our API or a supported reverse-ETL source. [Learn more →](/concepts/audiences) + +## Goals + +Goals are measurable outcomes you define in Knock, such as a user activating or converting to paid. You attach goals to workflows, broadcasts, and guides to track completions and attributed completions. + +[Learn more →](/concepts/goals) diff --git a/content/concepts/workflows.mdx b/content/concepts/workflows.mdx index 5287e21e7..30e3b9936 100644 --- a/content/concepts/workflows.mdx +++ b/content/concepts/workflows.mdx @@ -64,6 +64,10 @@ All changes to workflows, including changes made to the templates inside of a wo Read more about [environments](/version-control/environments) and [versioning](/version-control/commits) in Knock. +### Goals + +You can [attach a goal](/concepts/goals) to a workflow to measure when recipients complete a defined outcome and whether that completion can be attributed to the workflow. + ### Workflow status Each workflow has an `Active`/`Inactive` status that is displayed in your dashboard's **Workflows** section. The status defaults to `Active` and can be set by clicking on the workflow and using the **Status** selector in the **Details** section of the **Overview** tab. diff --git a/content/designing-workflows/wait-for-event-function.mdx b/content/designing-workflows/wait-for-event-function.mdx index 7bdc0404b..3fb141f1d 100644 --- a/content/designing-workflows/wait-for-event-function.mdx +++ b/content/designing-workflows/wait-for-event-function.mdx @@ -17,6 +17,8 @@ section: Designing workflows A wait for event function pauses a workflow or broadcast until a matching event is received, or until a configured wait time expires. Use it when the next step in your workflow or broadcast should depend on something that happens after the run starts — such as a payment completing in an external system, a message being delivered, another workflow finishing for the same recipient, an audience membership change, or a recipient property update. +[Goal conditions](/concepts/goals#goal-conditions) reuse a subset of this event model (integration source, audience entry/exit, and recipient updated) to define measurable outcomes outside of a workflow run. + ## How it works When a workflow run reaches a wait for event step, Knock pauses execution and registers a durable wait for the configured event. The workflow stays paused until one of the following happens: diff --git a/content/developer-tools/management-api.mdx b/content/developer-tools/management-api.mdx index 50acef1e8..5cc0911e3 100644 --- a/content/developer-tools/management-api.mdx +++ b/content/developer-tools/management-api.mdx @@ -12,6 +12,7 @@ You can use the Knock management API to: - Create, update and manage your [email layouts](/integrations/email/layouts). - Create and manage the [translations](/template-editor/translations) used by your notification templates. - Create, update, and manage your [partials](/template-editor/partials). +- Create, update, clone, and archive [goals](/concepts/goals), and attach them to workflows, broadcasts, and guides. - Commit and promote changes between your Knock environments. [View management API reference](/mapi) diff --git a/content/getting-started/what-is-knock.mdx b/content/getting-started/what-is-knock.mdx index 982efb4ef..1c14e2de0 100644 --- a/content/getting-started/what-is-knock.mdx +++ b/content/getting-started/what-is-knock.mdx @@ -389,6 +389,7 @@ There is a lot more to learn about Knock, and our [concepts overview page](/conc - Creating advanced messaging logic using [subscriptions](/concepts/subscriptions) and [schedules](/concepts/schedules). - Integrating Knock with your application's data model, using [tenants](/concepts/tenants) and [objects](/concepts/objects) to power customized experiences. - Using [the template editor](/template-editor/overview) to standardize messaging templates across providers. +- Defining [goals](/concepts/goals) to measure outcomes and attribute completions to your messaging. #### Developer tools diff --git a/content/version-control/environments.mdx b/content/version-control/environments.mdx index 32f6545fd..e4defa0ef 100644 --- a/content/version-control/environments.mdx +++ b/content/version-control/environments.mdx @@ -163,6 +163,7 @@ You can clone the following resources across environments: - Message types - Email layouts - Audiences +- Goals - Partials - Translations - Reusable requests @@ -170,6 +171,8 @@ You can clone the following resources across environments: Archived resources cannot be cloned. +Goals are cloned, not promoted. Cloning a goal copies its latest definition into the destination environment and does not copy attachments to workflows, broadcasts, or guides. See [goals](/concepts/goals) for more detail. + ### Clone vs promote Clone and promote solve different problems: diff --git a/data/sidebars/cliSidebar.ts b/data/sidebars/cliSidebar.ts index 3b3ac1738..9daa3c4f7 100644 --- a/data/sidebars/cliSidebar.ts +++ b/data/sidebars/cliSidebar.ts @@ -203,4 +203,21 @@ export const CLI_SIDEBAR: SidebarContent[] = [ { slug: "/archive", title: "Archive audience" }, ], }, + { + title: "Goals", + slug: "/cli/goal", + pages: [ + { slug: "/", title: "Overview" }, + { slug: "/file-structure", title: "File structure" }, + { slug: "/list", title: "List goals" }, + { slug: "/get", title: "Get goal" }, + { slug: "/new", title: "Create a new goal" }, + { slug: "/pull", title: "Pull goals" }, + { slug: "/push", title: "Push goals" }, + { slug: "/validate", title: "Validate goal" }, + { slug: "/open", title: "Open goal" }, + { slug: "/archive", title: "Archive goal" }, + { slug: "/clone", title: "Clone goal" }, + ], + }, ]; diff --git a/data/sidebars/mapiOverviewSidebar.ts b/data/sidebars/mapiOverviewSidebar.ts index 99c7d535c..21cb7f1bb 100644 --- a/data/sidebars/mapiOverviewSidebar.ts +++ b/data/sidebars/mapiOverviewSidebar.ts @@ -9,6 +9,7 @@ export const RESOURCE_ORDER = [ "broadcasts", "email_layouts", "audiences", + "goals", "partials", "guides", "message_types", diff --git a/data/sidebars/platformSidebar.ts b/data/sidebars/platformSidebar.ts index fae5be1e9..e4134f431 100644 --- a/data/sidebars/platformSidebar.ts +++ b/data/sidebars/platformSidebar.ts @@ -36,6 +36,7 @@ export const PLATFORM_SIDEBAR: SidebarSection[] = [ { slug: "/objects", title: "Objects" }, { slug: "/subscriptions", title: "Subscriptions" }, { slug: "/audiences", title: "Audiences" }, + { slug: "/goals", title: "Goals" }, { slug: "/schedules", title: "Schedules" }, { slug: "/messages", title: "Messages" }, { slug: "/conditions", title: "Conditions" }, diff --git a/data/specs/mapi/customizations.yml b/data/specs/mapi/customizations.yml index 265e416e4..fd98a1a1f 100644 --- a/data/specs/mapi/customizations.yml +++ b/data/specs/mapi/customizations.yml @@ -92,6 +92,10 @@ resources: name: Audiences description: |- [Audiences](/concepts/audiences) are user segments that you can use to target users for workflows, guides, and broadcasts. + goals: + name: Goals + description: |- + [Goals](/concepts/goals) are measurable outcomes you define in Knock and attach to workflows, broadcasts, and guides for completion and attribution tracking. Goal upserts publish immediately and do not accept a commit parameter. Clone a goal to copy it into another environment; goals are not promotable. data_sources: name: Data sources description: |- diff --git a/data/specs/mapi/stainless.yml b/data/specs/mapi/stainless.yml index 10daee2e4..31453d5fa 100644 --- a/data/specs/mapi/stainless.yml +++ b/data/specs/mapi/stainless.yml @@ -277,6 +277,19 @@ resources: upsert: put /v1/audiences/{audience_key} validate: put /v1/audiences/{audience_key}/validate list: get /v1/audiences + goals: + models: + goal: "#/components/schemas/Goal" + goal_condition: "#/components/schemas/GoalCondition" + goal_attachment: "#/components/schemas/GoalAttachment" + clone_goal_request: "#/components/schemas/CloneGoalRequest" + methods: + archive: delete /v1/goals/{goal_key} + retrieve: get /v1/goals/{goal_key} + upsert: put /v1/goals/{goal_key} + validate: put /v1/goals/{goal_key}/validate + list: get /v1/goals + clone: post /v1/goals/{goal_key}/clone settings: disable_mock_tests: true license: Apache-2.0 From 97c11b6fa7a157341863c1f60dbf1a0941efce0e Mon Sep 17 00:00:00 2001 From: andy-knock Date: Fri, 28 Aug 2026 16:06:35 -0400 Subject: [PATCH 2/2] fix(KNO-14970): address Goals docs review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Strip premature CLI goals docs (deferred to KNO-14985), expand reporting coverage for 30-day activity and the completions log, and align the attribution window to the product 7–30 day range. --- content/ai/agent.mdx | 2 +- content/cli/goal.mdx | 474 ------------------------------------ content/cli/overview.mdx | 1 - content/cli/resources.mdx | 6 +- content/concepts/goals.mdx | 41 ++-- data/sidebars/cliSidebar.ts | 17 -- 6 files changed, 26 insertions(+), 515 deletions(-) delete mode 100644 content/cli/goal.mdx diff --git a/content/ai/agent.mdx b/content/ai/agent.mdx index 334298d20..79de83cf3 100644 --- a/content/ai/agent.mdx +++ b/content/ai/agent.mdx @@ -15,7 +15,7 @@ section: AI The Knock agent is an AI-powered assistant built into the Knock dashboard. -You can use it to do anything you'd normally do in the dashboard, including create workflows, templates, guides, broadcasts, and partials. You can also use the Knock agent to learn about Knock concepts and inspect existing resources. +You can use it to do anything you'd normally do in the dashboard, including create workflows, templates, guides, broadcasts, partials, and goals. You can also use the Knock agent to learn about Knock concepts and inspect existing resources. - - -Goal commands enable you to manage [goals](/concepts/goals) in your Knock account from the CLI. - - -
- -
- - -When goals are pulled from Knock, they are stored in directories named by their goal key. Each goal directory contains a `goal.json` file that describes the goal's configuration (name, description, and condition). - -{/* prettier-ignore */} - -{`goals/ -└── trial-conversion/ - └── goal.json`} - - -If you're migrating your local goal files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using [`knock goal push --all`](/cli/goal/push). - -To attach a goal to a workflow, broadcast, or guide, set `goal_attachment` on that resource's JSON (`goal_key` and `attribution_window_days`). Attachments are not stored on the goal itself. - - -
- -
- - -Display all goals for an environment. Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment. - -### Flags - - - - - - - - - - - - - -```bash title="Basic usage" -knock goal list -``` - -```bash title="Pagination example" -knock goal list --after=xxx -``` - - -
- -
- - -Display a single goal from an environment. - -Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment. - -### Flags - - - - - - - - - - -```bash title="Basic usage" -knock goal get trial-conversion -``` - -```bash title="Get goal in a different environment" -knock goal get trial-conversion --environment=production -``` - - -
- -
- - -Pull one or more goals from an environment into a local file system. Knock CLI will create a new goal directory or update the existing goal directory in the local file system. - -By default this command will resolve to the goals resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--goals-dir` flag. - -Note: if pulling the target goal for the first time (or all goals), Knock CLI will ask to confirm before writing to the local file system. - -See the [Goal file structure](/cli/goal/file-structure) section for details on how goal files are organized. - -### Flags - - - - - - - - - - - - - -```bash title="Basic usage" -knock goal pull trial-conversion -``` - -```bash title="Pulling a goal in a different environment" -knock goal pull trial-conversion --environment=production -``` - -```bash title="Pulling all goals into ./goals directory" -knock goal pull --all --goals-dir=./goals -``` - - -
- -
- - -Push one or more goals from a local file system to Knock. Knock will update an existing goal by the matching goal key, or create a new goal if it does not exist yet. Goal upserts publish immediately; this command does not accept a `--commit` flag. - -By default this command will resolve to the goals resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--goals-dir` flag. - -Note: - -- You must be directly above the target goal directory when running the `goal push` command, so the CLI can locate the `goal.json` file. -- Use `--force` to bypass environment restrictions and overwrite content in any environment. - -See the [Goal file structure](/cli/goal/file-structure) section for details on how goal files are organized. - -### Flags - - - - - - - - - - - - -```bash title="Basic usage" -knock goal push trial-conversion -``` - -```bash title="Pushing all goals from ./goals directory" -knock goal push --all --goals-dir=./goals -``` - - -
- -
- - -Validate one or more goals from a local file system. Knock will validate the given goal payload in the same way as it would with the `goal push` command, except without persisting those changes. - -### Flags - - - - - - - - - - - -```bash title="Basic usage" -knock goal validate trial-conversion -``` - - -
- -
- - -Create a new goal with a minimal configuration. The command creates a new goal directory in your local file system. By default, this will be in the goals resource directory set by your `knock.json` file, or the current working directory if not configured. - -### Flags - - - - - - - - - - - - - - -```bash title="Create a goal interactively" -knock goal new -``` - -```bash title="Create a goal" -knock goal new --key=trial-conversion --name="Trial conversion" -``` - -```bash title="Create and push a goal" -knock goal new --key=trial-conversion --name="Trial conversion" --push -``` - - -
- -
- - -Open a goal in the Knock dashboard. This command opens the goal page in your default browser. - -### Flags - - - - - - - - - -```bash title="Basic usage" -knock goal open trial-conversion -``` - -```bash title="Open a goal in a different environment" -knock goal open trial-conversion --environment=production -``` - - -
- -
- - -Archive a goal. Archiving stops new completion and attribution calculation for the goal and cannot be undone. Historical versions and completions are retained. - - - -### Flags - - - - - - - - - - -```bash title="Basic usage" -knock goal archive trial-conversion --environment=development -``` - - -
- -
- - -Clone a goal into a destination environment. Cloning copies the latest version of the goal (name, description, and condition). It does not copy attachments to workflows, broadcasts, or guides. - -### Flags - - - - - - - - - - - - -```bash title="Clone a goal into production" -knock goal clone trial-conversion \ - --environment=development \ - --destination-environment=production -``` - -```bash title="Clone with a custom key and name" -knock goal clone trial-conversion \ - --environment=development \ - --destination-environment=production \ - --key=trial-conversion-prod \ - --name="Trial conversion" -``` - - -
diff --git a/content/cli/overview.mdx b/content/cli/overview.mdx index 269ef3116..8f22c7da8 100644 --- a/content/cli/overview.mdx +++ b/content/cli/overview.mdx @@ -166,7 +166,6 @@ When you use `knock pull`, resources will be grouped by resource type within sub {`./knock/ ├── audiences/ -├── goals/ ├── guides/ ├── layouts/ ├── message-types/ diff --git a/content/cli/resources.mdx b/content/cli/resources.mdx index 6e3c94771..70e5fc73c 100644 --- a/content/cli/resources.mdx +++ b/content/cli/resources.mdx @@ -6,7 +6,7 @@ description: Commands for managing all Knock resources at once.
-These commands enable you to manage all Knock resources (workflows, partials, email layouts, translations, guides, message-types, audiences, and goals) at once. +These commands enable you to manage all Knock resources (workflows, partials, email layouts, translations, guides, message-types, and audiences) at once.
@@ -39,7 +39,7 @@ knock init
-Pulls the contents of all Knock resources (workflows, partials, email layouts, translations, guides, message-types, audiences, and goals) from Knock into your local file system. +Pulls the contents of all Knock resources (workflows, partials, email layouts, translations, guides, message-types, and audiences) from Knock into your local file system. Resources will be grouped by resource type within subdirectories of the target directory path set either by your `knock.json` file or by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands. @@ -86,7 +86,7 @@ knock pull --knock-dir=./.knock
-Pushes all local resource files (workflows, partials, email layouts, translations, guides, message-types, audiences, and goals) back to Knock and upserts them. +Pushes all local resource files (workflows, partials, email layouts, translations, guides, message-types, and audiences) back to Knock and upserts them. Resources will be pushed to the target directory path set either by your `knock.json` file or by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands. diff --git a/content/concepts/goals.mdx b/content/concepts/goals.mdx index dd519d768..7c2b648f3 100644 --- a/content/concepts/goals.mdx +++ b/content/concepts/goals.mdx @@ -18,7 +18,7 @@ section: Concepts A goal is a reusable, environment-scoped outcome that you identify as having special business meaning. For example, you might define a "Customer activated" goal that completes when a user creates their first channel or starts an agent session. -Each goal has an immutable `key`, a title, an optional description, a condition that defines when the goal is met, and versions. When a recipient meets the goal condition, Knock records a **completion**. When that completion can be credited to a [workflow](/concepts/workflows), [broadcast](/concepts/broadcasts), or [guide](/concepts/guides) that has the goal attached, Knock also records an **attributed completion**. +Each goal has an immutable `key`, a title, an optional description, and a condition that defines when the goal is met. When a recipient meets the goal condition, Knock records a **completion**. When that completion can be credited to a [workflow](/concepts/workflows), [broadcast](/concepts/broadcasts), or [guide](/concepts/guides) that has the goal attached, Knock also records an **attributed completion**. Use goals to: @@ -31,11 +31,11 @@ Use goals to: To create a goal, navigate to the **Goals** page in the Knock dashboard, then create a new goal. Set: - **Key.** An immutable, environment-unique identifier for the goal. -- **Title.** A human-readable name for the goal. In the Management API and CLI, this field is `name`. +- **Title.** A human-readable name for the goal. In the Management API, this field is `name`. - **Description.** Optional context about what the goal means for your business. - **Condition.** The event that must happen for Knock to record a completion. See [Goal conditions](#goal-conditions). -Goals are scoped to an [environment](/concepts/environments). When you save a goal, Knock publishes it immediately. Goals do not use the commit-and-promote model that workflows and other versioned resources use. +Goals are scoped to an [environment](/concepts/environments). When you save a goal, Knock publishes it. Goals do not use the commit-and-promote model that workflows and other versioned resources use. Goal definition changes create a new goal version and keep a history of prior versions. ### Cloning a goal @@ -120,13 +120,13 @@ You can attach a goal to a [workflow](/concepts/workflows), [broadcast](/concept A goal attachment includes: - **Goal key.** The key of the goal to attach. -- **Attribution window.** The number of days after the attribution anchor during which a completion can be credited to the resource. Defaults to 7 days. Maximum is 30 days. Granularity is 1 day. +- **Attribution window.** The number of days after the attribution anchor during which a completion can be credited to the resource. Must be between 7 and 30 days (day granularity). Defaults to 7 days. The attachment lives on the messaging resource's version. Attaching, detaching, or changing the attribution window creates a new version of that workflow, broadcast, or guide, and follows that resource's [commit](/version-control/commits) model. ## Attribution -When a recipient meets a goal condition, Knock always records a **completion**. If the goal is attached to one or more messaging resources, Knock then decides whether the completion is an **attributed completion**. +When a recipient meets a goal condition, Knock records a **completion**. If the goal is attached to one or more messaging resources, Knock then decides whether the completion is an **attributed completion**. ### Attribution window and anchor @@ -143,34 +143,36 @@ If multiple attached resources are eligible for the same completion, Knock attri ### Example: attribution window -Goal 1 is attached to Workflow A (7-day window) and Guide B (30-day window). Recipient X receives messaging from: +Goal 1 is attached to Workflow A (7-day window) and Guide B (30-day window). Recipient X received messaging from: -- Workflow A, 1 day ago and 8 days ago -- Guide B, 6 days ago +- Workflow A: one run that sent its first message 8 days ago (and another message 1 day ago on that same run) +- Guide B: 6 days ago Is Workflow A inside its attribution window? -- No. The first message sent for the most recent Workflow A run was 8 days ago, and the attachment has a 7-day window. +- No. The attribution anchor is the **first** message sent on the most recent Workflow A run (8 days ago), and the attachment has a 7-day window. ### Example: last touch -Goal 1 is attached to Workflow A and Guide B. Both attachments have a 30-day window. Recipient X receives messaging from: +Goal 1 is attached to Workflow A and Guide B. Both attachments have a 30-day window. Recipient X received messaging from: -- Workflow A, 1 day ago and 8 days ago -- Guide B, 6 days ago +- Workflow A: first message 8 days ago, most recent message 1 day ago +- Guide B: 6 days ago Both resources are inside their windows. Last touch was Workflow A, so Knock attributes the completion to **Workflow A**. ## Reporting -On the **Goals** page in the dashboard, you can view all goals in the current environment. Open a goal to see: +On the **Goals** page in the dashboard, you can view all goals in the current environment. The list shows a rolling **30-day activity** sparkline of attributed completions for each goal (day-level granularity). Goals with no attributed completions in the last 30 days omit the sparkline. -- **Completions.** Every time a recipient met the goal condition. -- **Attributed completions.** The subset of completions Knock credited to an attached messaging resource. You can filter attributed completions by resource. +Open a goal to see: -Attributed completions are a strict subset of completions. Attribution for analytics can take up to about 15 minutes to appear after a completion. +- **Overview.** Time series of completions and attributed completions for a selected range, with totals and completion rate. You can break the series down by goal version or by messaging resource, and see attributed completions per attached resource. +- **Completions log.** A paginated list of individual completions and attributed completions for the same range as the overview. Each row includes the recipient, completion time, triggering event, and (when attributed) the winning messaging resource and message. -Resource-level conversion metrics on workflow, broadcast, and guide analytics pages are not included in this release. Use the goal detail page and resource filters instead. +Attributed completions are a strict subset of completions. Attribution for analytics can take up to 15 minutes to appear after a completion. + +Resource-level conversion metrics on workflow, broadcast, and guide analytics pages are not included in this release. Use the goal detail page and resource breakdowns instead. ## Goals and the Knock agent @@ -178,9 +180,9 @@ The [Knock agent](/ai/agent) has full read access to goals and their fields. The ## Managing goals programmatically -You can create, update, clone, and archive goals, and attach them to messaging resources, with the [Management API](/mapi-reference/goals) and the [Knock CLI](/cli/goal). +You can create, update, clone, and archive goals, and attach them to messaging resources, with the [Management API](/mapi-reference/goals). -Goal upserts publish immediately. Unlike workflows and guides, the goals upsert endpoint does not accept a commit parameter. Attachments are stored on the workflow, broadcast, or guide as a `goal_attachment` (`goal_key` and `attribution_window_days`). +Goal upserts publish on save. Unlike workflows and guides, the goals upsert endpoint does not accept a commit parameter. Attachments are stored on the workflow, broadcast, or guide as a `goal_attachment` (`goal_key` and `attribution_window_days`). ## Limitations @@ -191,3 +193,4 @@ The following are not available in this release: - Attaching more than one goal to a single messaging resource. - Goal conversion metrics on the workflow, broadcast, or guide analytics pages. - Promoting goals between environments (clone a goal instead). +- Managing goals with the Knock CLI (coming in a later release). diff --git a/data/sidebars/cliSidebar.ts b/data/sidebars/cliSidebar.ts index 9daa3c4f7..3b3ac1738 100644 --- a/data/sidebars/cliSidebar.ts +++ b/data/sidebars/cliSidebar.ts @@ -203,21 +203,4 @@ export const CLI_SIDEBAR: SidebarContent[] = [ { slug: "/archive", title: "Archive audience" }, ], }, - { - title: "Goals", - slug: "/cli/goal", - pages: [ - { slug: "/", title: "Overview" }, - { slug: "/file-structure", title: "File structure" }, - { slug: "/list", title: "List goals" }, - { slug: "/get", title: "Get goal" }, - { slug: "/new", title: "Create a new goal" }, - { slug: "/pull", title: "Pull goals" }, - { slug: "/push", title: "Push goals" }, - { slug: "/validate", title: "Validate goal" }, - { slug: "/open", title: "Open goal" }, - { slug: "/archive", title: "Archive goal" }, - { slug: "/clone", title: "Clone goal" }, - ], - }, ];