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, 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, broadcast, or guide 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 which messaging resource it should be attributed to.
• Give the Knock agent context about intent so it can propose and improve messaging against those outcomes.

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, 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.

Goals are scoped to an environment. Create and edit them on the environment's main branch. Goals cannot be created or updated on a branch.

When you save a goal, Knock publishes it and measurement starts immediately. Goals have version history but do not use the full commit-and-promote model that other versioned resources use.

Changes to a goal's title, description, or condition create a new goal version. Messaging Resource Attachments reference the goal by key, not pinned version. New completions use the latest condition. Completions that already happened stay associated with previous versions.

You can clone a goal into the same environment or another environment. Clone creates a new goal: you set a new key and title. In the dashboard, these default to {key}-copy and {name} (Copy). In the Management API, you pass key and name. Cloning copies the latest 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 to the destination environment.

Archiving a goal soft-deletes it in every environment that shares the same project and key. Knock stops calculating new completions and attributions, retains historical versions and completions, and rewrites the key with an -archived suffix so the original key is free to reuse. You cannot un-archive a goal.

Detach the goal from every workflow, broadcast, and guide in the project before you archive. Knock refuses the archive if any of those resources still have the goal attached.

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, 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, such as Segment or Stripe.	Optional. Filter on event properties under event.*.
Audience entry / exit	A recipient enters or exits a dynamic audience. Static audiences are not supported.	Not required.

For supported operators, see the conditions docs.

Knock records a completion when it sees a matching event for a recipient in that environment. A goal does not need to be attached to messaging for completions to be recorded. Attachments only control attribution.

What has to be true depends on the event type:

• Integration source. The environment has a connected source that ingested the event, and the event is associated with a recipient Knock knows about.
• Audience entry / exit. The dynamic audience exists in the same environment, and the recipient entered or exited it.

To attach a goal, open the workflow, broadcast, or guide in the dashboard. On the resource, attach a goal, select the goal, and set the attribution window. Then commit or publish the resource if it uses the commit model. You cannot attach a goal while working on a branch.

• 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. Must be between 1 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 model.

When a recipient meets a goal condition, Knock records a completion, including when the goal has no attached resources. If the goal is attached to one or more messaging resources, Knock then decides whether the completion is an attributed completion.

NOCOMMIT TODO ANDY CONFIRM THIS

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.

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).

NOCOMMIT TODO ANDY CONFIRM THIS

Goal 1 is attached to Workflow A (7-day window) and Guide B (30-day window). Recipient X received messaging from:

• 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 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.

Goal 1 is attached to Workflow A and Guide B. Both attachments have a 30-day window. Recipient X received messaging from:

• 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.

Open a goal on the Goals page to see:

• Overview. Time series of completions and attributed completions for a selected range, with totals and completion rate. Completion rate is attributed completions divided by unique recipients messaged in that range.
• 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.

NOCOMMIT TODO ANDY CONFIRM THIS (THE SLA FOR reporting)

Attributed completions are a strict subset of completions. Attribution for analytics can take up to 15 minutes to appear after a completion.

The Knock agent has full read access to goals and their fields. The agent can propose, create, and update goals, reuse an existing goal, or define a new one when building or improving messaging. It can attach a goal by setting goal_attachment on a workflow, broadcast, or guide. The agent cannot archive or clone a goal. 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.

You can create, update, clone, and archive goals, and attach them to messaging resources, with the Management API.

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).

The following are not available in this release:

• Using a goal as exit criteria to cancel an in-flight workflow run.
• Recipient-updated goal conditions.
• Tenant-property goal conditions.
• Attaching more than one goal to a single messaging resource.
• Promoting goals between environments (clone a goal instead).
• Creating, editing, or attaching goals on a branch.
• Managing goals with the Knock CLI (coming in a later release).