Skip to main content

Skill Goals

Beta

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​

FieldNotes
objectiveRequired. What the agent should achieve. 1-2,000 characters.
completion_criteriaOptional. When the goal counts as done. Max 2,000.
outputsUp to 20 answers to collect. Can be empty for an objective-only goal.
on_max_attemptsWhat happens when an answer is still invalid after max_attempts: handoff (default) hands over to a human, skip leaves it empty and moves on.
actionsCompletion actions.

Outputs​

FieldNotes
keyRequired. ^[A-Za-z][A-Za-z0-9_]{0,63}$. Unique (case-insensitive). The key in webhooks and Flow variables.
labelMax 100.
descriptionMax 500. Help for the agent, for example what to ask.
requiredDefault true.
typetext, 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.
optionsFor select and multiselect. Up to 100 non-empty strings, max 255 characters each.
bindWhere the answer is saved. See Binding.
constraintsExtra validation rules. See Constraints.
max_attempts1..5, default 3. Invalid answers allowed before on_max_attempts applies.

Binding to contact fields​

bindSaves 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 type returns type_mismatch.
  • One field can be bound to only one output.
  • A bound select/multiselect output may restrict options to 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​

KeyTypes
min, maxnumber, 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​

  1. 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).
  2. 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 example too_small or invalid_email) so the agent can ask again. See Grounded answers.
  3. 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.
  4. The completing turn has the outcome goal_completed (task_completed inside 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 state you 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, 2 or yes) 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 rejected with the code not_answered, evidence_shared or evidence_used. They do not count as an attempt towards max_attempts.

  • A declined output stores no value, is not saved to the contact, counts as resolved for complete_goal and appears as declined in the goal progress. It also needs the contact's words.

  • Finish with complete_goal, not handoff. Tags and assignment of a goal are applied only when the goal completes. When the goal has tags, an assignment strategy or after.type: "handoff", the agent is told to finish it with complete_goal. Before completion the agent says it has noted a value, not that it was saved, because saving can still be refused (for example conflict). set_state only 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_goal does not apply. The hand-off replaces the goal's after step: after.type: "start_flow" is not started and the turn trace reports it as skipped. A tag the agent passes to handoff is added on top of the goal's tags (never twice). Actions still run once per goal activation. The turn outcome stays handoff.
  • 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 escalated branch 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.

ConversationPre-filled
WhatsApp, SMS, Telegram, Messenger, InstagramEvery 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 chatOnly 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
EmailOnly an email output, with the sender address of the conversation
Test consoleNothing
Other channelsNothing
  • 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:

ActionFieldsEffect
save_contact_fieldsenabled (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.
assignstrategy, 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_tagtag_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.
webhookenabled (default true)Sends agent.goal_completed.
aftertype: 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_added webhook 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); with both, the conversation part is still added.
  • A tag the agent passes to handoff itself 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_ids must be existing tags of your workspace (tag_not_found otherwise); duplicates are removed. max must not be greater than the number of tags. Hints for tags that are not in tag_ids are dropped.
  • The agent sees the tags by name with their hints and passes its choice by name in the tag argument of complete_goal (a list when max is greater than 1). With required: true it cannot complete the goal without a choice (tag_choice_required); a name outside the list or more than max tags 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_tag argument of handoff (separate from the agent's own hand-off tag). 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_trace records the choice as reason codes only, never the agent's arguments: a goal step with event: "tag_chosen", "tag_choice_rejected" (reason: tag_choice_required or tag_not_allowed) or "tag_choice_skipped" (reason: tag_choice_missing or tag_choice_invalid).
  • The choice is checked again when the actions run: only tags from tag_ids that still exist are added, at most max. Tags are never created. A tag that is also in add_tag_ids, or that the hand-off already added, is added only once.
  • A goal with choose_tag counts 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"]
}
  • actions is set only on the turn whose completion actions ran, otherwise null. In the test console it describes what would happen and has "dry_run": true.
  • completed_via: complete_goal or handoff (see Hand-off while a goal is active).
  • field: the bound field (email, phone, name, first_name, last_name, language, birthday) or custom.
  • skipped[].reason: conflict (the email or phone already belongs to another contact), unchanged, already_has_value (with overwrite_existing: false), invalid, no_contact or error.
  • after: none, handoff or start_flow; null inside a Flow (the Flow continues on done). after_skipped is start_flow when a hand-off replaced it.
  • tag_reasons (only for a goal with choose_tag, only on a turn where something happened; absent otherwise): up to 4 codes for this turn. tag_chosen means a choice was accepted; tag_choice_required and tag_not_allowed mean a complete_goal call was refused; tag_choice_missing and tag_choice_invalid mean 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, contact or both). When the contact part is skipped, reason is no_contact (the conversation has no contact) or error; a contact-only tag that was not added anywhere is listed with targets: [].
  • tags_added[].name is null when the tag no longer exists. tags_added[].source: fixed (assign.tag_id or add_tag_ids), chosen (picked by the agent for choose_tag) or handoff (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_id identifies the goal activation and is the same on every delivery attempt. Use it to de-duplicate.
  • outputs has at most 20 keys. Skipped optional answers are null. 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.

codeMeaning
invalid, invalid_type, invalid_valueMalformed goal, wrong type or value
options_required, duplicate_option, options_not_applicable, options_not_subsetProblems with options
constraint_not_applicable, min_greater_than_max, constraint_loosensProblems with constraints
unknown_standard_field, type_mismatch, duplicate_bind, unsupported_field_typeProblems with bind
custom_field_not_found, custom_field_inactiveThe bound custom field does not exist or is inactive
tag_not_foundassign.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_startableProblems 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.