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" }
}
target | Writes to |
|---|---|
contact_field | A standard contact field |
custom_field | A custom field |
tag | Adds tags |
list_subscription | Subscribes to lists (with consent) |
variable_only | Nothing; 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" }
field | Allowed components | Notes |
|---|---|---|
first_name, last_name | TextInput, TextArea, Dropdown, RadioButtonsGroup | Whitespace is collapsed. |
email | same | Lower-cased and checked. Use input_type: "email" (otherwise warning mapping.email_input_type). |
language | same | A language code such as de or de-AT. |
birthday | DatePicker, CalendarPicker, TextInput | ISO 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 tickedOptIn, 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."
}
}
mode | Effect |
|---|---|
add (default) | Ticked lists are subscribed. Nothing is unsubscribed. |
sync | Ticked 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. synconly 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" } }
| Source | Shape | Notes |
|---|---|---|
| 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
idis a stored value of the field, exactly as stored (spaces, case and umlauts kept), in the field's order. Thetitleis the same value, shortened to 30 characters with "…". A yes/no field gives the two optionstrueandfalse. - 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,RadioButtonsGroupor aChipsSelectorwithmax_selected_items: 1. A multi-select field needs aCheckboxGrouporChipsSelector. A yes/no field needs aDropdownorRadioButtonsGroupwith exactly two options. RadioButtonsGroup,CheckboxGroupandChipsSelectortake at most 20 options, aDropdownup to 200. A field with more values needs aDropdown.options_sourcestays in SendSeven. It is not part of the flow JSON sent to WhatsApp.
Validator codes:
| Code | Level | Meaning |
|---|---|---|
options_source.unknown_field | error | The field doesn't exist or is inactive. |
options_source.type_incompatible | error | The field type isn't single-choice, multi-select or yes/no, or the input doesn't fit it. |
options_source.too_many_options | error | The field has more values than the input allows. |
options_source.drift | warning | The 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.