Destinations

Every study needs a destination: where do the recruitment ads send the people who click them? Destinations need to be connected to Virtual Lab so that it not only knows where to send people, but also knows how to collect information about those who become study participants, and knows how to optimize the ads.

Virtual Lab supports a set of destinations, and is written so that it is easy to add a new one. When configuring your study you can create one or more destinations, and each needs a unique name (key) that you refer to it by elsewhere.

Fields every destination has

• name: The name of the destination, used to refer to it in other configuration screens.
• This study's ad refs: whether the ad carries a plain ref or an encoded ref — see What an ad's ref carries below. Leave it alone if you do not know what it means; the default is the way Virtual Lab has always worked.

The chat destinations (Messenger, WhatsApp, Multi) also share:

• Initial Shortcode: The shortcode of the first Fly form people should be sent to.
• Welcome Message: What the respondent sees before the conversation starts.
• Additional Metadata: Optional extra key-value pairs — written as JSON, e.g. {"wave": "2"} — added to every ad's ref and to its attribution record. Use it for facts about the destination that are not stratification variables.

Messenger

A Fly Messenger survey destination. This creates Messenger ads for when you want the respondent to be directed into a Fly survey on Facebook Messenger.

• Initial Shortcode
• Welcome Message: When someone clicks your ad they are directed to a Messenger chat with this initial message.
• Button Text: The button they tap in the chat, in response to the welcome message, to start the survey.
• Additional Metadata (optional)

WhatsApp

A click-to-WhatsApp destination. This creates ads that open a WhatsApp chat with your study's number, with the first message already typed for the respondent.

• Initial Shortcode: letters, digits, _ and - only. A shortcode is shareable by design — someone may type it into WhatsApp by hand — so it has to be typeable, not merely encodable. Anything else is refused when you save.
• Welcome Message: Shown above the compose box on the WhatsApp welcome screen. It is not part of the routing, and it is not the prefilled message.
• WhatsApp Phone Number: the number itself, e.g. +1-541-920-2635 — not a phone_number_id. Required. Meta treats it as optional and falls back to whichever number on the page happens to be "primary", so leaving it out means recruiting into a number you did not choose.
• Additional Metadata (optional)

There is no Button Text. WhatsApp has no quick-reply button; what the respondent gets is a prefilled compose box, and the text in it is what routes them into your survey.

Multi (Messenger or WhatsApp)

One ad that opens either Messenger or WhatsApp, with Meta choosing per respondent based on which app it predicts they are most likely to reply from.

• Initial Shortcode: one shortcode, for both arms — never one per channel.
• Welcome Message
• Button Text: the Messenger arm's button.
• WhatsApp Phone Number: as above.
• Additional Metadata (optional)

Two constraints:

• Your recruitment Optimization Goal must be CONVERSATIONS. Saving fails otherwise, naming both fields.
• Your survey must work on both channels. You cannot know which channel a given respondent gets, so every WhatsApp limit applies. See Channels.

Attribution is unaffected: one ad, one stratum, one attribution record, whichever channel a respondent lands on. But the channel itself is only recoverable from the response data (Fly records it as platform), never from the ad.

The WhatsApp arm of a multi ad is newer than the rest of this and has been verified less thoroughly than the Messenger arm. On the first study that uses one, watch arrivals on both channels before scaling the budget.

Web

• Url Template: The URL of the web survey, with {ref} wherever you want the Virtual Lab ref inserted into the URL.

App

• Facebook App ID: The app ID for Facebook.
• Deeplink Template: The deeplink template to link to the app, with {ref} wherever you want the Virtual Lab ref inserted.
• App Install State: The app install state, as per Facebook.
• User Device: The targeted devices.
• User OS: The targeted install states.

What an ad's ref carries

Every recruitment ad carries a ref: a string that comes back to Virtual Lab when someone clicks it. The ref is how a respondent is connected back to the ad that recruited them, and therefore to their stratum.

The destination form offers two, and they have names — the same names used throughout this documentation:

This study's ad refs

• Plain ref — The ref spells the stratum out, so gender and region arrive as columns in your response data with nothing to join. The ref is long and editable anywhere the respondent can see it, so use this only where they cannot: Messenger hides it, WhatsApp does not.
• Encoded ref — The ref is a short code, so the respondent never sees anything readable. Strata come from the ad-attributions export instead, joined to your responses on ref_token. Works the same on every channel, which is why a study running on more than one should prefer it.

Plain ref (the default)

The ref spells out the stratum:

creative.StaticHausa.gender.men.Age.25_34.form.mnchweek

Every value travels with every message, and arrives as metadata on the respondent's record. Your export already has gender and Age as columns and there is nothing to join.

This is how Virtual Lab has always worked, and it is what a study with no setting saved does. Choose it when:

• your Fly survey branches on ad metadata — logic jumps that read creative or gender need the values present in the conversation; or
• you want the simplest possible export.

Encoded ref

The ref carries a short opaque token instead:

r.AQhtbmNod2Vla6QffA6T

Nothing about the respondent's stratum travels with the ad. Virtual Lab records what each ad meant when it created it, and you join the two afterwards using the Ad Attributions export. Choose it when:

• the ref is visible to the respondent — it is, on WhatsApp — and you would rather not describe people back to themselves;
• your stratum values contain characters that do not travel well; or
• you simply do not need the values inside the survey.

Changing it on a live study

Changing this setting changes the ad, so every ad in the study is rewritten on the next reconciliation run: real spend, possibly another round of Meta review, and the learning phase starting over. Live posts people have already shared start pointing at the new link. The dashboard warns you before saving.

Respondents who already arrived keep the attribution they came with. Respondents who arrived before the change are not retro-fitted to the new mechanism, which is the other reason to decide this before recruitment starts rather than during it.

Destinations and the channel an ad opens

You do not set the channel separately. The ad set's destination type is derived from the destinations you configured:

Two consequences:

• A Destination Experiment can now have a Messenger arm and a WhatsApp arm, which was previously impossible.
• A running study cannot change channel. Ad sets are matched by name and persist for the study's lifetime, so the channel is fixed once recruitment starts.

All the creatives within one stratum must agree on the channel — Virtual Lab refuses to build a study whose creatives disagree, rather than publishing half its ads to the wrong place.