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 a message is sent during which a completion can be credited to the resource. Each new message from that resource to the recipient resets the window. 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. Knock only attributes a completion after the goal is attached to a messaging resource.

Knock attributes a completion to the last message sent to the recipient from an attached resource, as long as that message was sent within the attachment's attribution window.

The attribution window is set per attachment. Knock measures it from when a message is sent to the recipient from that resource. When a recipient sees a guide, Knock records a sent message, so guides use the same send event as workflows and broadcasts.

Each new message from an attached resource to the recipient resets that resource's window. A resource is eligible for attribution when it has sent a message to the recipient within its window relative to the completion time.

If multiple attached resources are eligible for the same completion, Knock attributes the completion to the resource that sent the most recent message (last touch).

If the recipient meets the goal again with no new message in between, Knock records another completion but does not attribute it. A new message from an attached resource makes the next completion eligible for attribution again.

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

• Workflow A: a message 8 days ago, then another message 1 day ago
• Guide B: a message 6 days ago

Workflow A is inside its window. The window is measured from the last message sent (1 day ago), not the first message on the run.

Both resources are eligible. Last touch is Workflow A, so Knock attributes the completion to Workflow A.

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

• Workflow A: a message 10 days ago
• Workflow B: a message 8 days ago

Workflow B sent the most recent message, but that send is outside B's 7-day window. Workflow A is inside its 30-day window. Knock attributes the completion to Workflow A.

Recipient X receives a message from Workflow A, then completes the goal twice with no new message in between. Knock records two completions. Only the first is attributed to Workflow A. After Workflow A sends another message, the next completion can be attributed again.

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