Skill Goals
Skill goals are part of the Conversational Agents Beta.
A goal turns a skill into a guided task: the agent collects a defined set of answers, SendSeven validates each answer, saves the valid ones to the contact, and runs your completion actions. Typical uses: qualify a lead, take a callback request, register a return, collect feedback.
- The goal is stored on the skill version. Changing it creates a new version, and pinned agents keep their old goal.
- Validation is done by SendSeven, not by the model. The agent submits answers; only answers that pass your rules are accepted and saved. The model never writes contact fields directly.
- Goals work on every surface: channels, Live Chat, email, Flows and the test console.
Add a goal to a skill
Send goal when you create or update a skill (or in a skill import):
{
"slug": "qualify-lead",
"title": "Qualify a lead",
"description": "Use when a visitor asks about pricing, a demo or buying for a team.",
"default_mode": "model_selected",
"body": "Be friendly and brief. Ask one question at a time.",
"goal": {
"objective": "Find out whether the visitor is a good fit for a sales call.",
"completion_criteria": "We know the company size, the budget and the email address.",
"outputs": [
{"key": "company_size", "label": "Company size", "type": "select", "options": ["1-10", "11-50", "51-200", "200+"],
"bind": {"kind": "custom_field", "field_id": "CUSTOM_FIELD_ID"}},
{"key": "budget", "label": "Monthly budget (EUR)", "type": "number", "constraints": {"min": 0, "max": 1000000}},
{"key": "email", "bind": {"kind": "contact_standard", "field": "email"}},
{"key": "website", "type": "url", "required": false}
],
"on_max_attempts": "handoff",
"actions": {
"save_contact_fields": {"enabled": true, "overwrite_existing": false},
"assign": {"strategy": "round_robin_by_tag", "tag_id": "TAG_ID_SALES", "add_tag_ids": ["TAG_ID_LEAD"], "prefer_online": true},
"webhook": {"enabled": true},
"after": {"type": "none"}
}
}
}
Send "goal": null on PATCH to remove the goal; omit it to keep the current one.
Goal fields
| Field | Notes |
|---|---|
objective | Required. What the agent should achieve. 1-2,000 characters. |
completion_criteria | Optional. When the goal counts as done. Max 2,000. |
outputs | Up to 20 answers to collect. Can be empty for an objective-only goal. |
on_max_attempts | What happens when an answer is still invalid after max_attempts: handoff (default) hands over to a human, skip leaves it empty and moves on. |
actions | Completion actions. |
Outputs
| Field | Notes |
|---|---|
key | Required. ^[A-Za-z][A-Za-z0-9_]{0,63}$. Unique (case-insensitive). The key in webhooks and Flow variables. |
label | Max 100. |
description | Max 500. Help for the agent, for example what to ask. |
required | Default true. |
type | text, number, integer, boolean, date, datetime, email, phone, url, select, multiselect. Bound outputs take the type of their field; an unbound output without a type is text. |
options | For select and multiselect. Up to 100 non-empty strings, max 255 characters each. |
bind | Where the answer is saved. See Binding. |
constraints | Extra validation rules. See Constraints. |
max_attempts | 1..5, default 3. Invalid answers allowed before on_max_attempts applies. |
Binding to contact fields
bind | Saves to |
|---|---|
{"kind": "contact_standard", "field": "…"} | A standard contact field: first_name, last_name, name, language (text), birthday (date), email, phone |
{"kind": "custom_field", "field_id": "…"} | An active custom field in your workspace |
- A bound output uses the field's type. Declaring a different
typereturnstype_mismatch. - One field can be bound to only one output.
- A bound
select/multiselectoutput may restrictoptionsto a subset of the field's options. - Location and collection custom fields cannot be bound.
- The custom field's own validation rules always apply.
Constraints
| Key | Types |
|---|---|
min, max | number, integer |
min_length, max_length (0..10000) | text, email, phone, url |
pattern (1-200 characters, a safe regular expression) | text, email, phone, url |
date_min, date_max (ISO date or "today") | date, datetime |
boolean, select and multiselect take no constraints. For a bound output, constraints may only tighten the field's own rules: a wider range, a longer maximum or a different pattern returns constraint_loosens.
How the agent works with a goal
- The goal becomes active when its skill is loaded (by the classifier, by
load_skill, as a Flow skill, or as an always-on skill). - The agent asks for the answers and submits them with
submit_goal_fields, each with evidence: the contact's own words for that answer. Each answer is normalised and validated; invalid answers come back with an error code (for exampletoo_smallorinvalid_email) so the agent can ask again. See Grounded answers. - The agent finishes with
complete_goal. This succeeds only when every required output was accepted, skipped or declined. A goal without outputs can be completed after at least 1 contact message following activation, or at least 2 when the goal has completion actions. When every required answer came from the contact record (see Values on record), completion also needs at least 1 contact message after those values were filled in, so the contact can confirm them. - The completing turn has the outcome
goal_completed(task_completedinside a Flow), and the completion actions run.
More rules:
- One active goal at a time. Loading another skill with a goal pauses the current one. Up to 3 paused goals are kept and resume when their skill is loaded again.
- The active goal's skill stays loaded on the following turns, unless the conversation moves to another topic.
- Goal tools are free and get 2 extra tool calls on top of
max_tool_calls. - Goal progress is kept per conversation. In the test console it travels in the
stateyou send back (key_agent_goal).
complete_goal errors the agent may receive: no_active_goal, goal_unavailable, ungrounded_values (a required answer was refused as not given by the contact in this turn, with remaining_required), required_fields_missing (with remaining_required), too_early, and for a goal with choose_tag tag_choice_required and tag_not_allowed.
Grounded answers
An answer counts only when the contact actually gave it. submit_goal_fields takes values (output key to value), evidence (output key to the contact's own words, quoted from their message) and declined (output key to the contact's words refusing or saying they don't know).
-
The evidence, or the value itself, must appear in a message from the contact in the conversation history the agent sees, including messages sent before the goal started. Button and list replies count as the button title. Matching ignores case, accents and diacritics, punctuation and spacing, and maps all digits to 0-9, so it works across scripts.
-
A short quote (under 15 characters after normalisation, such as
b,2oryes) can back only one answer per contact message that contains it, and never two answers in the same call. -
Answers whose value is unchanged (a resubmit, or a confirmed value on record) need no evidence.
-
When the contact's current message carries a file the agent reads directly, an answer with evidence that is not in the text is accepted (a value read off the file).
-
Refused answers come back in
rejectedwith the codenot_answered,evidence_sharedorevidence_used. They do not count as an attempt towardsmax_attempts. -
A declined output stores no value, is not saved to the contact, counts as resolved for
complete_goaland appears asdeclinedin the goal progress. It also needs the contact's words. -
Finish with
complete_goal, nothandoff. Tags and assignment of a goal are applied only when the goal completes. When the goal has tags, an assignment strategy orafter.type: "handoff", the agent is told to finish it withcomplete_goal. Before completion the agent says it has noted a value, not that it was saved, because saving can still be refused (for exampleconflict).set_stateonly stores the agent's own notes: it never tags, assigns or changes the conversation or the contact.
Hand-off while a goal is active
When the agent calls handoff while a goal with routing actions (an assign.strategy other than none, assign.add_tag_ids, choose_tag, or after.type: "handoff") is active:
- Every required answer is present (answers from the contact record count), or the goal has no required outputs: the goal is completed and its completion actions run (save, assign and tags, webhook), then the conversation is handed off. The minimum-messages rule of
complete_goaldoes not apply. The hand-off replaces the goal'safterstep:after.type: "start_flow"is not started and the turn trace reports it as skipped. A tag the agent passes tohandoffis added on top of the goal's tags (never twice). Actions still run once per goal activation. The turn outcome stayshandoff. - Required answers are missing: the conversation is handed off without completing the goal (no actions run).
- Inside a Flow running the skill's goal: unchanged, the Run AI Assistant node continues on its
escalatedbranch and the goal is not completed.
Goals with only save_contact_fields, webhook or after.type: "start_flow" are not completed by a hand-off.
Values on record
When a goal becomes active, outputs bound to the contact's email, phone, name, first_name, last_name or a custom field are filled from the record of the contact who is chatting, if it has a value. They count as collected, the agent asks the contact to confirm them briefly, and a different answer from the contact replaces them.
| Conversation | Pre-filled |
|---|---|
| WhatsApp, SMS, Telegram, Messenger, Instagram | Every bound output with a value (on WhatsApp a missing phone falls back to the number of this chat) |
| Live Chat with a contact token, a signed identity or a verification in this chat | Only verified values: an email or phone whose contact method is marked verified (or came with a signed identity), and custom values whose source is not visitor or ai (values the visitor typed or a goal saved are never pre-filled here) |
| Anonymous Live Chat (cookie only) | Nothing; on the next turn after the visitor verifies |
Only an email output, with the sender address of the conversation | |
| Test console | Nothing |
| Other channels | Nothing |
- A stored value that fails the output's validation is not pre-filled.
- A custom field is pre-filled only when its AI access allows reading it.
- Saving an unchanged pre-filled value writes nothing; the turn trace reports it as
unchanged. - Pre-fill runs once per goal activation (anonymous Live Chat retries until the visitor is verified).
Completion actions
Actions run once per goal activation, in live conversations only, in this order:
| Action | Fields | Effect |
|---|---|---|
save_contact_fields | enabled (default true), overwrite_existing (default false) | Saves the accepted answers to their bound fields. With overwrite_existing: false, a field that already has a value is left alone. |
assign | strategy, tag_id, add_tag_ids (max 10), tag_target (default conversation), prefer_online (default true) | strategy: none (default), round_robin_all, least_busy_all, round_robin_by_tag, least_busy_by_tag (tag_id required). Assigns an unassigned conversation; an assigned one is never reassigned. add_tag_ids are added where tag_target says (see Where tags go). The tag_id of a by-tag strategy always tags the conversation. |
choose_tag | tag_ids (2-10 tags), max (1-3, default 1), required (default true), hints (tag id to text, max 200 characters each), target (default conversation) | Optional; leave it out or send null for none. The agent picks up to max of tag_ids when it completes the goal, guided by hints, and they are added where target says, together with add_tag_ids. See Let the agent choose a tag. |
webhook | enabled (default true) | Sends agent.goal_completed. |
after | type: none (default), handoff or start_flow; flow_id; variable_prefix (default goal, ^[A-Za-z][A-Za-z0-9_]{0,31}$) | handoff hands the conversation to a human (needs escalation on; with a *_by_tag strategy the assign.tag_id is the hand-off tag). start_flow starts a published, manually startable Flow for the conversation with the answers in {{vars.<variable_prefix>.<key>}}. |
Where tags go
assign.tag_target (for add_tag_ids) and choose_tag.target (for the chosen tags) take conversation (default), contact or both. Set them separately, for example a fixed "Needs callback" on the conversation and a chosen "Hot / Warm / Cold" lead status on the contact. When you send conversation, the key is left out of the stored goal.
- A tag on the contact is added exactly like tagging the contact by hand: it sends the
contact.tag_addedwebhook and starts automations that react to a contact tag. - Tags only ever go to the conversation's own contact. If the conversation has no contact, the contact part is skipped (
no_contact); withboth, the conversation part is still added. - A tag the agent passes to
handoffitself always goes on the conversation only.
Let the agent choose a tag
add_tag_ids are always added. With choose_tag the agent decides which tag fits, for example hot, warm or cold for a lead:
"choose_tag": {
"tag_ids": ["TAG_ID_HOT", "TAG_ID_WARM", "TAG_ID_COLD"],
"max": 1,
"required": true,
"hints": {"TAG_ID_HOT": "Wants to buy within 30 days", "TAG_ID_COLD": "Only browsing"}
}
tag_idsmust be existing tags of your workspace (tag_not_foundotherwise); duplicates are removed.maxmust not be greater than the number of tags. Hints for tags that are not intag_idsare dropped.- The agent sees the tags by name with their hints and passes its choice by name in the
tagargument ofcomplete_goal(a list whenmaxis greater than 1). Withrequired: trueit cannot complete the goal without a choice (tag_choice_required); a name outside the list or more thanmaxtags is refused as a whole (tag_not_allowed), and the agent can try again. Tags that no longer exist are not offered; when none of the tags exists any more, the goal completes without a chosen tag. - When the agent hands off while the goal is active, it can pass its choice in the
goal_tagargument ofhandoff(separate from the agent's own hand-offtag). A missing or invalid choice does not stop the hand-off; the goal is completed without a chosen tag (when every required answer is present, see Hand-off while a goal is active). - The
engine_tracerecords the choice as reason codes only, never the agent's arguments: agoalstep withevent: "tag_chosen","tag_choice_rejected"(reason:tag_choice_requiredortag_not_allowed) or"tag_choice_skipped"(reason:tag_choice_missingortag_choice_invalid). - The choice is checked again when the actions run: only tags from
tag_idsthat still exist are added, at mostmax. Tags are never created. A tag that is also inadd_tag_ids, or that the hand-off already added, is added only once. - A goal with
choose_tagcounts as a goal with routing actions (see Hand-off while a goal is active).
Inside a Flow, actions run too, but after is skipped: the Flow continues on the Run AI Assistant node's done branch instead. See Agents in Flows.
In the test console nothing is executed. The engine_trace contains a goal_actions_dry_run step whose would_execute lists the fields that would be saved, the assignment, the chosen tag (choose_tag.chosen_tag_ids), where tags would go (assign.tag_targets, choose_tag.targets), the webhook and the after action.
Goal progress in the turn trace
Each turn (test console response and turn log) has goal_progress for the conversation's current goal, with field keys only, never values:
{
"skill": "qualify-lead", "skill_title": "Qualify lead", "status": "completed",
"collected": ["email", "company_size"], "missing": [], "prefilled": ["email"],
"actions": {
"completed_via": "handoff",
"saved": [{"key": "company_size", "label": "Company size", "field": "custom"}],
"skipped": [{"key": "email", "label": "Email", "field": "email", "reason": "unchanged"}],
"tags_added": [{"id": "…", "name": "Sales", "source": "fixed", "targets": ["conversation"]}, {"id": "…", "name": "Hot", "source": "chosen", "targets": ["contact"]}],
"assigned": true,
"after": "handoff",
"after_skipped": "start_flow"
},
"can_complete_now": null,
"tag_reasons": ["tag_choice_required", "tag_chosen"]
}
actionsis set only on the turn whose completion actions ran, otherwisenull. In the test console it describes what would happen and has"dry_run": true.completed_via:complete_goalorhandoff(see Hand-off while a goal is active).field: the bound field (email,phone,name,first_name,last_name,language,birthday) orcustom.skipped[].reason:conflict(the email or phone already belongs to another contact),unchanged,already_has_value(withoverwrite_existing: false),invalid,no_contactorerror.after:none,handofforstart_flow;nullinside a Flow (the Flow continues ondone).after_skippedisstart_flowwhen a hand-off replaced it.tag_reasons(only for a goal withchoose_tag, only on a turn where something happened; absent otherwise): up to 4 codes for this turn.tag_chosenmeans a choice was accepted;tag_choice_requiredandtag_not_allowedmean acomplete_goalcall was refused;tag_choice_missingandtag_choice_invalidmean a hand-off or completion went ahead without a chosen tag. Codes only, never the agent's arguments.tags_added[].targets: where the tag was added (conversation,contactor both). When the contact part is skipped,reasonisno_contact(the conversation has no contact) orerror; a contact-only tag that was not added anywhere is listed withtargets: [].tags_added[].nameisnullwhen the tag no longer exists.tags_added[].source:fixed(assign.tag_idoradd_tag_ids),chosen(picked by the agent forchoose_tag) orhandoff(passed with the hand-off).
agent.goal_completed webhook
Subscribe your webhook endpoint to agent.goal_completed (see Webhook setup). The event uses the standard envelope:
{
"id": "evt_4f9c2a7b1d3e5f60",
"type": "agent.goal_completed",
"created_at": "2026-10-05T10:00:01Z",
"tenant_id": "…",
"event_id": "6f1c1d1e-2b3a-4c5d-8e9f-0a1b2c3d4e5f",
"data": {
"agent": {"id": "…", "name": "Sales Assistant"},
"skill": {"id": "…", "slug": "qualify-lead", "version": 3},
"conversation_id": "…",
"contact_id": "…",
"channel_type": "whatsapp",
"outputs": {"company_size": "11-50", "budget": 5000, "email": "[email protected]", "website": null},
"saved_fields": ["company_size", "email"],
"completed_at": "2026-10-05T10:00:00Z",
"flow_run_id": null
}
}
event_ididentifies the goal activation and is the same on every delivery attempt. Use it to de-duplicate.outputshas at most 20 keys. Skipped optional answers arenull. Text is cut at 4,000 characters and lists at 50 items.- Full reference: Webhook events — agent.goal_completed.
Statistics
GET /automation/skills/{skill_id}/goal-stats?days=30 returns started, completed and handed-off goals, the completion rate and a per-version breakdown. See Skills API — Goal statistics.
Errors
An invalid goal is rejected with 422:
{
"detail": {
"code": "invalid_goal",
"message": "The skill goal is invalid",
"errors": [
{"path": "outputs[1].constraints.max", "code": "constraint_loosens", "message": "…"}
]
}
}
Up to 50 errors are returned, each with the path of the problem.
code | Meaning |
|---|---|
invalid, invalid_type, invalid_value | Malformed goal, wrong type or value |
options_required, duplicate_option, options_not_applicable, options_not_subset | Problems with options |
constraint_not_applicable, min_greater_than_max, constraint_loosens | Problems with constraints |
unknown_standard_field, type_mismatch, duplicate_bind, unsupported_field_type | Problems with bind |
custom_field_not_found, custom_field_inactive | The bound custom field does not exist or is inactive |
tag_not_found | assign.tag_id, an add_tag_ids entry or a choose_tag.tag_ids entry is not in your workspace |
flow_not_found, flow_not_published, flow_not_manually_startable | Problems with after.flow_id |
Answer validation codes the agent can receive: required, not_in_options, not_a_number, not_an_integer, too_small, too_large, too_short, too_long, pattern_mismatch, invalid_email, invalid_phone, invalid_url, invalid_date, date_too_early, date_too_late, invalid_boolean, invalid_language, unsupported.