Skip to main content

Field Mapping

Every input in a builder doc can carry a mapping. When the contact completes the flow, SendSeven writes the answer to the contact. You do not need any code for this. Every answer, mapped or not, is also delivered in the completion webhook and to automations.

{
"type": "TextInput",
"name": "email",
"label": "E-Mail",
"input_type": "email",
"required": true,
"mapping": { "target": "contact_field", "field": "email" }
}
targetWrites to
contact_fieldA standard contact field
custom_fieldA custom field
tagAdds tags
list_subscriptionSubscribes to lists (with consent)
variable_onlyNothing; the answer is only stored with the response

Write-back rules​

  • Empty answers never clear a value. An untouched optional field leaves the contact as it was.
  • Tags are only added, never removed.
  • The phone number is never writable. It identifies the contact on WhatsApp.
  • An e-mail address that belongs to another contact is not moved. The answer is kept in the response and reported as skipped (owned_by_other_contact).
  • A value that cannot be converted (for example an invalid e-mail) is skipped with a reason; the rest is still written.
  • Write-back is safe to repeat: subscriptions are idempotent, tags add-only, fields set-only.

The outcome of each write is reported in the writeback object.

Contact field​

{ "target": "contact_field", "field": "first_name" }
fieldAllowed componentsNotes
first_name, last_nameTextInput, TextArea, Dropdown, RadioButtonsGroupWhitespace is collapsed.
emailsameLower-cased and checked. Use input_type: "email" (otherwise warning mapping.email_input_type).
languagesameA language code such as de or de-AT.
birthdayDatePicker, CalendarPicker, TextInputISO date (YYYY-MM-DD).

Other components return mapping.wrong_component.

Custom field​

{ "target": "custom_field", "custom_field_id": "3f1c…" }

Any active custom field can be filled (mapping.custom_field_unknown otherwise). The field's "editable by contact" setting does not matter here. The value is converted to the field's type (text, number, date, boolean, select, multi-select), and the input must fit that type (mapping.type_incompatible), for example a CheckboxGroup for a multi-select field. For choice fields, link the options to the field so the option ids are the field's stored values, or use the custom_field_options resolver on a dynamic flow.

Tag​

{ "target": "tag", "tag_id": "b7d2…" }
  • tag_id: added when the answer is "truthy" (a ticked OptIn, a non-empty answer).
  • option_tags: for selection inputs (Dropdown, RadioButtonsGroup, CheckboxGroup, ChipsSelector), a map from option id to tag id. Each selected option adds its tag.
{
"type": "RadioButtonsGroup",
"name": "budget",
"label": "Budget",
"options": [
{ "id": "small", "title": "Unter 5.000 €" },
{ "id": "large", "title": "Über 5.000 €" }
],
"mapping": { "target": "tag", "option_tags": { "large": "tag_hot_lead" } }
}

Codes: mapping.tag_missing (neither set), mapping.tag_unknown, mapping.option_unknown, mapping.wrong_component (option_tags on a non-selection input).

List subscription​

List subscriptions need recorded consent. consent must be true and consent_text must contain the exact wording the contact agrees to. SendSeven stores a snapshot of this text, the flow version and the time with the subscription. Because the contact ticks the box themselves inside WhatsApp, no extra double opt-in message is sent.

Only an OptIn or a CheckboxGroup can subscribe (mapping.list_wrong_component).

OptIn: one list​

{
"type": "OptIn",
"name": "newsletter",
"label": "Ja, ich möchte den Newsletter erhalten",
"mapping": {
"target": "list_subscription",
"list_id": "a9c4…",
"consent": true,
"consent_text": "Ja, ich möchte den Newsletter per WhatsApp erhalten. Abmeldung jederzeit möglich.",
"consent_version": "2026-10"
}
}

An OptIn needs a list_id (mapping.list_missing).

CheckboxGroup: several lists​

Either map each option to a list with option_lists, or leave option_lists empty and use list ids as option ids, which is what the lists resolver produces:

{
"type": "CheckboxGroup",
"name": "topics",
"label": "Themen",
"options": "${data.lists}",
"init_value": "${data.subscribed}",
"mapping": {
"target": "list_subscription",
"mode": "sync",
"consent": true,
"consent_text": "Ich möchte zu den gewählten Themen Nachrichten per WhatsApp erhalten."
}
}
modeEffect
add (default)Ticked lists are subscribed. Nothing is unsubscribed.
syncTicked lists are subscribed, unticked lists that were offered are unsubscribed. Use it for a preference centre. CheckboxGroup only (mapping.sync_needs_checkbox).

Safety rules:

  • Only static and newsletter lists can be subscribed (list_type_not_allowed).
  • Only lists that were actually shown to the contact count (not_offered). A forged reply cannot subscribe to other lists.
  • sync only unsubscribes lists that were offered and are visible in the preference centre.

With static options and no option_lists, the validator warns mapping.option_ids_as_lists to remind you that the option ids must be list ids.

Tags on completion​

To tag every contact that completes the flow, regardless of the answers, use on_complete at the top level of the builder doc:

{ "on_complete": { "tag_ids": ["tag_lead_qualified"] } }

Prefill​

An input can show the contact's current value when the flow opens. Add prefill next to mapping:

{ "type": "TextInput", "name": "email", "label": "E-Mail", "input_type": "email",
"mapping": { "target": "contact_field", "field": "email" },
"prefill": { "source": "contact_field", "field": "email" } }
SourceShapeNotes
Contact field{ "source": "contact_field", "field": "first_name" }first_name, last_name, email, phone, language, birthday. phone can only be prefilled, never written.
Custom field{ "source": "custom_field", "custom_field_id": "3f1c…" }Any active custom field whose type fits the input (same rules as the mapping).

The value is read when the flow is sent. A contact without a value sees an empty input. Prefill works only on screens that are reached by navigation from the first screen (prefill.unreachable_screen otherwise). Photo and document pickers can't be prefilled. Other codes: prefill.unknown_field, prefill.type_incompatible.

Options from a custom field​

A Dropdown, RadioButtonsGroup, CheckboxGroup or ChipsSelector can take its options from a single-choice, multi-select or yes/no custom field. Set options_source together with the matching options, mapping and prefill:

{
"type": "RadioButtonsGroup",
"name": "plan",
"label": "Ihr Tarif",
"options": [
{ "id": "Basis", "title": "Basis" },
{ "id": "Premium Plus", "title": "Premium Plus" }
],
"options_source": { "source": "custom_field", "custom_field_id": "3f1c…" },
"mapping": { "target": "custom_field", "custom_field_id": "3f1c…" },
"prefill": { "source": "custom_field", "custom_field_id": "3f1c…" }
}
  • Each option id is a stored value of the field, exactly as stored (spaces, case and umlauts kept), in the field's order. The title is the same value, shortened to 30 characters with "…". A yes/no field gives the two options true and false.
  • Because the ids are the stored values, the answer is saved back to the field unchanged.
  • In the flow builder, linked options are read-only. Unlink them to edit them by hand.
  • Which input fits which field: a single-choice field needs a Dropdown, RadioButtonsGroup or a ChipsSelector with max_selected_items: 1. A multi-select field needs a CheckboxGroup or ChipsSelector. A yes/no field needs a Dropdown or RadioButtonsGroup with exactly two options.
  • RadioButtonsGroup, CheckboxGroup and ChipsSelector take at most 20 options, a Dropdown up to 200. A field with more values needs a Dropdown.
  • options_source stays in SendSeven. It is not part of the flow JSON sent to WhatsApp.

Validator codes:

CodeLevelMeaning
options_source.unknown_fielderrorThe field doesn't exist or is inactive.
options_source.type_incompatibleerrorThe field type isn't single-choice, multi-select or yes/no, or the input doesn't fit it.
options_source.too_many_optionserrorThe field has more values than the input allows.
options_source.driftwarningThe field's values changed since the options were set (order and titles don't count). Refresh the options and publish the flow again.

Where a custom field is used​

Before you change a custom field's values, check which flows use it:

curl https://api.sendseven.com/api/v1/whatsapp-flows/custom-field-usage/3f1c… \
-H "Authorization: Bearer YOUR_API_TOKEN"
{
"items": [
{ "definition_id": "…", "name": "Tarifwechsel", "status": "published", "published": true, "uses": ["options_source", "mapping", "prefill"] }
],
"pagination": { "total": 1, "page": 1, "page_size": 1, "total_pages": 1, "has_next": false, "has_prev": false }
}

It scans the latest and the published version of every flow that isn't archived. published: true means the live version uses the field. uses lists options_source, mapping and prefill. All matches come on one page. Scope: whatsapp_flows:read.

Variable only​

{ "target": "variable_only" }

No mapping, or variable_only, stores the answer only with the response. It is still in the webhook, the sessions API and automation variables.

PhotoPicker and DocumentPicker are always variable only (mapping.media_not_mappable). Uploaded files are stored with the response and listed in writeback.media.

Sensitive fields​

Add field names to a screen's sensitive list to hide them in WhatsApp's response summary on the contact's phone, for example a customer number or date of birth:

{ "id": "VERIFY", "title": "Identität", "sensitive": ["customer_number"], "components": [ … ] }

The sessions API and the whatsapp_flow.completed webhook mask these answers as •••• as well. Field mapping and automations inside SendSeven still receive the real values.