Skip to main content

​
What it does

Data Collection - v0.2 is the standard way to collect and verify one field from a caller by voice — a name, a phone number, or an alphanumeric code such as a policy or booking reference. You place one tool step in your flow; on the call it runs a complete collection exchange:
  • the first ask (with an optional custom opening line),
  • confirmation read-back of what was heard,
  • optional spelling and spell-back verification,
  • correction loops with attempt limits, so a mis-heard value gets fixed rather than saved,
  • a quick confirm of a pre-existing value instead of asking fresh, and
  • skipping entirely when the value is already known.
It is a composite tool: the whole exchange runs behind a single step, and the caller experiences it as a natural part of the conversation. Each use collects exactly one field — to collect a first name and a mobile number, place two Data Collection steps.

​
Collection types

The Type input selects one of three collection behaviours. Choose the type that matches the data, not just the prompt wording — each type verifies differently.

​
User name

For names and other short spoken words. The assistant asks for the value, reads it back for confirmation (when Confirm is on), and can ask the caller to spell it and spell it back for final verification (when Spell is on). A pre-populated Existing Value is tidied up and quick-confirmed rather than asked fresh. Use it for first names, last names, and similar single-word or short answers where the caller says the value rather than dictating characters.

​
Phone number

For phone numbers. Verification works digit-by-digit rather than by a separate confirmation question: the assistant reads the number back in short spoken groups of digits and the caller corrects any digit by its position, with the country prefix kept intact. If the caller already volunteered their number in the last few turns of conversation before this step, the tool picks it up and goes straight to the read-back instead of asking again. An Existing Value is sanity-checked (it must look like a complete number) before being quick-confirmed.

​
Alphanumeric

For codes that mix letters, digits and symbols — reference numbers, booking codes, registration plates. Values of up to 10 characters are accepted. The read-back spells the value unambiguously: letters use phonetic words (A for Alpha), digits are read as digit names, and symbols are named (dot, dash), in short groups so the caller can follow along. Case is preserved exactly as collected, corrections are made character-by-character, and — like phone numbers — a code the caller already mentioned in recent turns is picked up without re-asking.

​
Inputs

Confirm and Spell shape the user-name exchange; for phone numbers and alphanumeric codes the grouped read-back described above is itself the verification, so those types always read the value back regardless of the toggles.

​
How a collection runs

Every use of the tool enters through the same gate, in this order:
  1. Skip If Set — if the referenced variable already holds a real value, the step ends immediately with a true result. Nothing is spoken.
  2. Existing Value — if a pre-populated value is present (and isn’t a placeholder), the assistant quick-confirms it: “I have your first name as Jane — is that right?” A yes keeps it; a no drops into the normal collection exchange.
  3. Recent turns — for phone numbers and alphanumeric codes, the tool checks whether the caller already volunteered the value in the last few turns; if so it goes straight to the read-back.
  4. Fresh ask — otherwise the assistant asks for the value, using First Message if you set one.
From there the confirmation, spelling and correction loops run as the type requires. Each stage of the exchange (asking, confirming, spelling) has an attempt limit of five; when a limit is reached the tool gives up gracefully and finishes with a false result rather than trapping the caller in a loop.

​
Outputs

​
Variables this tool writes

The data_collection namespace also holds temp_* working fields — private to the tool. A later Data Collection step overwrites the whole namespace, so always map Collected Value to a durable variable rather than reading {{data_collection.output_result}} in later steps.

​
Routing and wiring tips

  • true — value collected (or skipped because it was already set). Otherwise — collection failed (attempt limits reached or the caller refused).
  • For an optional field, point true and otherwise at the same next step so a failed collection never blocks the call.
  • Use the standard contact fields for standard data: wire Existing Value and Skip If Set to the {{contact.*}} field being collected, and map Collected Value back to that same field. Don’t invent custom variables for names, phones or emails.
  • If the contact record already holds the value and you skip the Existing Value input, the caller gets asked from scratch instead of a quick confirm.
  • Point Skip If Set at the same variable the output writes to, so repeat visits to the step skip cleanly instead of re-collecting.
  • To collect an email address, use SMS | Get Valid Email instead — emails are far more reliable over an SMS round-trip than spelled aloud.

​
Next Steps

  • Composite Tools — how composite steps run, and how inputs, results and outputs connect to your call.
  • SMS | Get Valid Email — collect a validated email address by SMS round-trip.
  • Tool Steps — configuring inputs, conditions and output mapping on a step.
  • Variables — the full reference of variables tools read and write.