Question Types

Every question in a Fly survey is written in Typeform. Simple questions are just Typeform question types — you pick "Short Text" and you are done. Everything richer (a video, a tracked link, a wait, a payment) is configured by putting a small block of JSON in the Typeform question's Description box.

This page lists every question type Fly supports, with a complete example of each. Copy the examples as they are written here.

A survey can run on Messenger or on WhatsApp, and a few of the types below behave differently — or fail outright — on one of them. Those differences are called out where they arise, and collected in one place under Channels.

Where you write question settings

In the Typeform question's Description box. There is nowhere else. The Fly dashboard does not have a question editor — its "create survey" flow just picks one of your existing Typeform forms, gives it a shortcode, and imports it. To change a question you edit it in Typeform and re-import the form.

Open the question in the Typeform editor, find the Description field underneath the question title, and paste the JSON in:

{"type": "webview", "url": "https://www.who.int/hpv", "buttonText": "Read more"}

Three things about that box are not obvious, and they cause most of the problems researchers run into.

The type key replaces the Typeform question type

If the JSON in the Description box has a "type", that is the question type Fly uses, and Typeform's own question type is ignored. A Typeform Statement whose description says {"type": "moviehouse", "videoId": "164118668"} is a video question, not a statement.

This means Typeform's question type only decides how the question looks in the Typeform editor. When a type below says "In Typeform, pick Statement", that is a convention for keeping your form readable — the "type" in the description is what actually decides the behaviour.

Settings that do not change the question type — validate, keepMoving, wait, responseMessage — are written without a "type" key, and the Typeform question type is kept.

It has to be valid JSON, or it is ignored in silence

If the Description box does not parse, Fly does not warn you and does not fail. It keeps the question as its plain Typeform type and throws your whole configuration away. A video question quietly becomes a statement.

Before saving, check that every string is in double quotes, every key/value pair is separated by a comma, and the braces balance. If a question is behaving as if its description were not there, a JSON error is the first thing to suspect.

Typeform turns pasted URLs into links

When you paste https://www.who.int/hpv into a Typeform description, Typeform may rewrite it as [www.who.int/hpv](https://www.who.int/hpv). Fly unwraps that back to the plain URL for you, so a pasted link is safe — as long as it is inside double quotes, which it always is when you write JSON. This is the main reason to write JSON here rather than anything looser.

Referring to other answers

Question titles and descriptions can both refer to values you already have:

• {{hidden:id}} — a hidden field
• {{field:some_ref}} — the answer to an earlier question

These are substituted before the description is read, so you can build values out of them. Inside a URL they are escaped for you, so an answer containing a space or an & will not break the link. See Hidden Fields for the full list of what you can refer to and the transforms you can apply.

Every question type at a glance

Short Text and Long Text

A free text answer. Whatever the respondent types is accepted.

In Typeform, pick Short Text or Long Text. Nothing goes in the description. The two behave identically in a chat — the difference only exists in Typeform.

Number

Accepts a number and nothing else. If the respondent types anything that is not a number, they are asked the question again.

In Typeform, pick Number. Nothing needs to go in the description.

Numbers written in non-Latin numerals — Arabic-Indic (٤٢), Devanagari (४२), Bengali, Thai and others — are understood and recorded as ordinary digits, so you do not need to ask respondents to switch keyboards.

To restrict what counts as a valid answer, add a validate block. Note there is no "type" key here: you are adding a rule to a Number question, not changing what kind of question it is.

{"validate": {"min": 18, "max": 120, "integer": true}}

The message a respondent gets when their answer is rejected is set for the whole survey, not per question — see Messages.

Email

Accepts a valid email address and nothing else.

In Typeform, pick Email. Nothing goes in the description.

Phone Number

Accepts a real, dialable phone number.

In Typeform, pick Phone Number. Nothing goes in the description.

The number must carry its country code. +2348012345678 is accepted; 08012345678 is not, because Fly has no way to know which country it belongs to. Say so in the question text — "Please include your country code, e.g. +234…" — or you will lose answers.

When you pass a phone answer to a payment provider, use the |e164 transform ({{field:phone|e164}}) so trailing text the respondent typed does not travel with the number. See Hidden Fields.

Date

Sends the question and accepts the respondent's reply as text.

In Typeform, pick Date. Nothing goes in the description.

Fly does not check the format. Whatever the respondent types is accepted and recorded exactly as typed, so ask for the format you want in the question text ("Please write the date as DD/MM/YYYY") and expect to clean the answers afterwards. If you need a checked answer, ask for day, month and year as three Number questions instead.

Multiple Choice

A list of choices the respondent picks from by tapping.

In Typeform, pick Multiple Choice. Nothing goes in the description. The answer recorded is the choice's label — the text the respondent saw.

How many choices you can have depends on the platform:

If your survey runs on WhatsApp, keep every Multiple Choice question to 10 choices or fewer. The same limit applies to Dropdown, Picture Choice, Rating and Opinion Scale — see Channels.

If any choice is longer than about 15 characters, tapping becomes unreliable and the labels get cut off. Use letters as the choices and put the real text in the question:

Which region do you live in?
-A. North Central (Middle Belt)
-B. North East
-C. North West
-D. South East
-E. South South (Niger Delta)
-F. South West

and then make the Typeform choices A, B, C, D, E, F. The - and the . around the letters are optional but make the message easier to read.

Button Choice

The same as Multiple Choice, but on Messenger the options are sent as buttons that stay in the conversation instead of quick replies that vanish as soon as one is tapped.

In Typeform, pick Multiple Choice, and put this in the description:

{"type": "button_choice"}

Limits:

1. Three buttons maximum — this is a Facebook limit. With more than three options, use Multiple Choice.
2. Button labels are cut off at 20 characters.
3. The message text is limited to 640 characters.

On WhatsApp a Button Choice question is identical to a Multiple Choice question with three options, since WhatsApp already sends three-option questions as buttons.

Dropdown and Picture Choice

Both behave exactly like Multiple Choice in a chat: the choice labels are sent as tappable options and the label is recorded as the answer. Pictures are not sent — only the labels — so use Picture Choice only if you are also using the same form outside Fly.

In Typeform, pick Dropdown or Picture Choice. Nothing goes in the description. The platform limits under Multiple Choice apply.

Yes/No

A two-option question. The answer recorded is Yes or No.

In Typeform, pick Yes/No. Nothing goes in the description.

Legal

A two-option question for consent. The answer recorded is I Accept or I don't Accept.

In Typeform, pick Legal. Nothing goes in the description. Branch on the answer with a Typeform logic jump in the usual way.

Opinion Scale and Rating

A numbered scale sent as tappable options.

In Typeform, pick Opinion Scale or Rating, and set the number of steps there. Nothing goes in the description.

The options are the numbers themselves: a 5-step scale sends 1 2 3 4 5. If you turn Typeform's "start at 1" setting off, it sends 0 1 2 3 4 instead. The answer recorded is the number the respondent tapped.

On WhatsApp, a scale can have at most 10 steps. An 11-point scale (0–10) is 11 options, which is over WhatsApp's limit and will fail to send. Use 0–9 or 1–10.

Statement

A message that is sent without asking anything. The survey moves straight on to the next question.

In Typeform, pick Statement. Nothing goes in the description.

If you want a statement to pause the survey rather than continue, that is a Wait, which is a different question type — a wait added to a plain Statement is ignored.

Welcome Screen

The first message of the form. It is sent as a question with a single button, labelled with whatever button text you set in Typeform (Continue if you set none). The respondent taps it to begin.

In Typeform, add a Welcome Screen. Nothing goes in the description.

Ending (Thank You Screen)

The last message. It is sent, and then the respondent's survey is marked complete.

In Typeform, add an Ending / Thank You Screen. Nothing goes in the description.

Only the first line of the ending's text is sent — Typeform adds its own boilerplate below it, and that is dropped. Keep the whole message on one line.

Attachments: Image, Video, Audio, Document

An attachment question sends a file to the respondent. All four kinds share one shape — only attachment.type changes:

{"type": "attachment",
 "keepMoving": true,
 "attachment": {
    "type": "image",
    "url": "https://media.vlab.digital/a/550e8400-e29b-41d4-a716-446655440000/welcome.png"
 }
}

In Typeform, pick Statement.

The url is what you get by uploading the file in the dashboard's Media tab and clicking to copy it — see Media Library. The same URL works on WhatsApp and Messenger; there is nothing per-platform to configure.

keepMoving: true sends the attachment and moves straight on to the next question without waiting for a reply. Leave it out if you want the respondent to answer something before the survey continues.

The four types

Note that documents use "type": "file", not "document":

{"type": "attachment",
 "keepMoving": true,
 "attachment": {
    "type": "file",
    "url": "https://media.vlab.digital/a/1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9/consent-form.pdf"
 }
}

On WhatsApp, the filename in the URL is what the respondent sees when the document arrives — so name the file properly before you upload it.

GIF and WebP images are not supported: convert them to PNG, JPEG, or MP4.

Captions

On WhatsApp, the Typeform question title is sent as the caption, so it appears with the image, video or document. On Messenger the platform supports no caption and the title is not shown — if the text matters there, send it as a separate Statement.

Using your own URL

Any public HTTPS URL works in place of a Media library one:

{"type": "attachment",
 "keepMoving": true,
 "attachment": {
    "type": "image",
    "url": "https://example.org/my-image.png"
 }
}

It has to stay publicly reachable for the life of the survey, and it has to respect the formats and limits above — neither of which we can check for you until the moment we send. Uploading to the Media library avoids both problems and sends faster.

{"attachment": {"type": "image", "attachment_id": "3656576331230635"}}

Upload (receiving files from respondents)

Tracked links

Sends a link as a button and records who clicked it and when. You write the destination; Fly builds the rest of the link.

In Typeform, pick Statement, and put this in the description:

{
  "type": "link_tracking",
  "url": "https://www.who.int/hpv",
  "buttonText": "Read about HPV",
  "keepMoving": true
}

That is the whole question.

The question title is the message text; buttonText is the button under it.

Phone, email and SMS buttons

tel:, mailto: and sms: destinations work the same way and are recorded the same way. Write the whole thing in the url:

{
  "type": "link_tracking",
  "url": "tel:+2340700220112",
  "buttonText": "Call the helpline",
  "keepMoving": true
}

{
  "type": "link_tracking",
  "url": "mailto:support@example.org",
  "buttonText": "Email us",
  "keepMoving": true
}

Whether the respondent's phone actually opens a dialler or a mail app is up to their phone. The click is recorded either way.

This is the only way to send one of these on WhatsApp. A tracked link becomes an ordinary web address that redirects, which WhatsApp accepts; a tel: written straight into a plain link does not send there at all.

Videos

Plays a video and records what the respondent does with it — every play, pause, seek and finish, plus a signal every 30 seconds while it is playing. You write the video id; Fly builds the rest.

In Typeform, pick Statement, and put this in the description:

{
  "type": "moviehouse",
  "videoId": "164118668",
  "buttonText": "Watch the video",
  "keepMoving": true
}

The videoId is the number in the Vimeo address: https://vimeo.com/164118668 is 164118668. Keep it in quotes, as above.

You do not choose which video player to use, and you do not need to know whether the survey is running on WhatsApp or Messenger. Fly handles both.

What a video records

All of these are recorded whether or not you wait on any of them, so you can analyse watching behaviour afterwards without changing the question.

Waiting for a click or a play

A tracked link or a video can hold the survey until the respondent actually clicks or actually plays. Replace keepMoving with a wait:

{
  "type": "moviehouse",
  "videoId": "164118668",
  "buttonText": "Watch the video",
  "responseMessage": "Please watch the video before continuing.",
  "wait": {
    "type": "external",
    "value": {"type": "moviehouse:play"}
  }
}

and for a link:

{
  "type": "link_tracking",
  "url": "https://www.who.int/hpv",
  "buttonText": "Read about HPV",
  "responseMessage": "Please open the link before continuing.",
  "wait": {
    "type": "external",
    "value": {"type": "linksniffer:click"}
  }
}

Leave the value as short as it is written above. {"type": "linksniffer:click"} matches the click on this question's own button, and {"type": "moviehouse:play"} matches a play of this question's own video. There is nothing else to fill in.

Set keepMoving or wait, never both. They ask for opposite things — one continues immediately, the other holds the survey until the respondent acts — so every question uses one or the other.

Plain links

For a link to a page that is not ours, and whose clicks you do not need recorded, use webview. It sends exactly the address you write, with nothing added:

{
  "type": "webview",
  "url": "https://asiapacific.unwomen.org/en/countries/india",
  "buttonText": "Visit UN Women",
  "extensions": false,
  "keepMoving": true
}

In Typeform, pick Statement.

keepMoving, responseMessage and buttonText mean the same as they do above. There is no click to wait on, because nothing is recorded — if you want to know who clicked, use a tracked link instead.

Set extensions to true only if the page you are linking to uses Messenger Extensions and its domain is whitelisted in your Facebook app. If it is not whitelisted, the button will not open. For most links, false is correct. It has no effect on WhatsApp.

On WhatsApp a plain link must be an ordinary web address. http:// and https:// work, and an address with no scheme at all is treated as https://. Anything else — tel:, mailto:, sms: — fails to send; use a tracked link for those. The 20-character limit on buttonText applies here too, and a longer label is a send failure rather than a truncation.

Wait

Pauses the survey and picks it up later. This is how multi-wave surveys are built.

In Typeform, pick Statement, and put this in the description:

{
    "type": "wait",
    "responseMessage": "Please wait!",
    "wait": {
        "type": "timeout",
        "value": {
            "type": "relative",
            "timeout": "2 days"
        }
    }
}

The question title is sent as a message, then the survey stops until the timeout fires. responseMessage is what a respondent gets if they write in while waiting.

Write a relative timeout as a whole number and a unit: "1 minute", "3 hours", "2 days", "1 week".

For absolute timeouts, timeouts you can change from the dashboard after the survey is live, and everything to do with waits longer than 24 hours, see Timeouts.

Waiting for an external event

Besides timeouts, a wait can be held until something happens outside the chat: a link click, a video play, a payment result.

{
  "type": "wait",
  "wait": {
    "type": "external",
    "value": {"type": "moviehouse:play"}
  }
}

The value describes which event you are waiting for. Every key you put in it has to match the event exactly, so write as little as you can get away with. {"type": "moviehouse:play"} waits for any play; adding "id": "164118668" narrows it to that one video and will match nothing if the id is off by a character.

For a click, {"type": "linksniffer:click"} on its own is what you want. If you do add a "url", write the complete destination — https:// and the whole path, exactly as it appears in the question.

Notify and recurring notifications (deprecated)

The rest of this section is kept so that an older survey can be read and understood. It is not a recommendation.

What notify did

A notify question sent Facebook's built-in "Notify Me" request, which asked the respondent for permission to send them one message later. In Typeform it was a Statement with:

{"type": "notify"}

Each permission was good for a single message. Fly stored the permissions it collected and spent one when it needed to write to somebody outside the 24-hour window — but only if the wait asked for one:

{
    "type": "wait",
    "responseMessage": "Please wait!",
    "wait": {
        "type": "timeout",
        "notifyPermission": true,
        "value": {
            "type": "relative",
            "timeout": "2 days"
        }
    }
}

Because it was only one message, that message had to be a question — the respondent had to answer before anything else could happen, which reopened the window. A long wait therefore looked like this:

1. a notify question
2. a wait with notifyPermission: true
3. a question — "would you like to answer a few more questions?"
4. a statement that stitches to the next form

It also required the permission to be enabled on the Page, under Page Settings → Advanced Messaging → one-time notification.

{"type": "notification_messages"} was the recurring version of the same idea: the respondent opted in once and could then be messaged on a schedule.

What to write instead

Replace the whole four-step pattern above with a wait and a template:

[Wait — timeout: 2 days]
       ↓
[Utility Message]  ← a Multiple Choice question if the template has buttons
       ↓
[the rest of the survey]

The respondent's tap on the template reopens the 24-hour window, exactly as their answer to the notify follow-up question used to. The difference is that nobody has to agree to anything first, and it works the same way on WhatsApp.

See Utility Message, and Timeouts for the wait itself.

Utility Message

Sends a pre-approved message template. Use this for anything that has to reach the respondent after the 24-hour messaging window has closed — survey results, prize notifications, reminders, the second wave of a longitudinal survey.

It works on both Messenger and WhatsApp, and the question you write is identical on both. What differs is where the template is approved and how strict the platform is about the window:

Utility Messages are the current replacement for every mechanism Meta retired in early 2026 — Message Tags (CONFIRMED_EVENT_UPDATE, etc.), Recurring Notifications, and the one-time Notify opt-in. On Messenger they are now the only way to message somebody after the window closes.

1. Create the template in the dashboard

Go to Message Templates in the dashboard and pick the account the template is for — a Facebook page, or a WhatsApp number. A template is identified by the tuple (account, name, language): the same name can exist on several accounts and in several language variants, each approved independently.

If your body contains placeholders, the dashboard prompts for a sample value per placeholder. Reviewers see the body with these values substituted in — that is how they judge whether the content is genuinely utility and not promotional. Samples are not used at send time; real values come from params in your question's description. WhatsApp requires them for every placeholder.

Approved templates cannot be edited. To change wording or buttons, delete and recreate. A name freed by deleting an approved template stays reserved for 30 days; a rejected template's name can be reused immediately.

2. Add the question in Typeform

• Text-only template → use a Statement question.
• Template with buttons → use a Multiple Choice question whose choices match the template's approved button labels (same labels, same order, same count). Typeform's own logic editor reads those choices to drive branching.

Put this in the question's description:

{
  "type": "utility_message",
  "template": "results_ready",
  "language": "en_US",
  "params": ["{{hidden:name}}", "$5"]
}

Note there is nothing platform-specific in the question. Fly sends the right shape for whichever account the respondent is on.

Branching on a button tap

Make the Multiple Choice's choice labels exactly match the approved template's button labels — same labels, same order, same count. The value your Typeform logic sees on a tap is then the same string as the label the respondent pressed:

[Multiple Choice question]   description: {"type": "utility_message", "template": "results_ready", ...}
                             choices: [ "Yes", "No" ]
       ↓
   logic jump:
     if answer equals "Yes" → [show results]
     if answer equals "No"  → [thank and end]

If the labels do not match, or the count differs from the template's button count, the send fails.

Typical survey flow

Utility messages are usually sent after a long wait — that is when the 24-hour window matters:

[Consent questions]
       ↓
[Wait - timeout: 3 days]
       ↓
[Utility Message] "Your {{1}} results are in, {{2}}!"   ← sent outside the 24h window
       ↓
[the rest of the wave]   ← their reply reopens the 24-hour window

See Timeouts for timeout setup, and WhatsApp Surveys for what the window means in practice on WhatsApp.

Common rejection and send errors

Stitch

Moves the respondent from this form to another one. Everything after the stitch happens in the new form.

In Typeform, pick Statement, and put this in the description:

{"type": "stitch",
 "stitch": {"form": "FORM_SHORTCODE"}}

where FORM_SHORTCODE is the shortcode of the form you want to move to.

The "type" must be stitch. A Statement that carries a stitch but no type is treated as an ordinary statement and the stitch never happens.

You can also set hidden fields on the way in. They are merged into whatever the respondent already carries, so the new form can branch on them:

{"type": "stitch",
 "stitch": {"form": "FORM_SHORTCODE",
            "metadata": {"arm": "treatment", "wave": "2"}}}

Payment

Read about payment question types under Incentive Payments.

Passing Thread Control (Handoff)

Messenger only. WhatsApp has no equivalent of Facebook's handover protocol, so a handoff question does nothing there — keep it off any path a WhatsApp respondent can take.

Hands the conversation to another Facebook app (a "secondary receiver" in Facebook's handover protocol), and picks the survey back up when that app hands control back.

In Typeform, pick Statement, and put this in the description:

{
  "type": "handoff",
  "handoff": {
    "target_app_id": "123456789",
    "mode": "wait",
    "metadata": {"check": "my_handoff"}
  }
}

How it works

1. The question title is sent to the respondent as a message.
2. Control of the conversation passes to target_app_id.
3. The survey waits.
4. When the other app hands control back, the survey resumes at the next question.

You do not add a wait — waiting for the handback is automatic. Declare type: handoff and the handoff block, and nothing else.

Values coming back from the other app

Any metadata the other app includes when it hands control back becomes hidden fields prefixed e_handover_metadata_. If the returning app sends {"status": "ok", "answer": "blue"}, later questions can use {{hidden:e_handover_metadata_status}} and {{hidden:e_handover_metadata_answer}}. The app id that regained control is available as {{hidden:e_handover_target_app_id}}.

What the other app needs

It must be configured as a Secondary Receiver on the Facebook Page, and to hand control back it calls Facebook's pass_thread_control API with target_app_id set to the Fly app ID.