Tag-Based Routing & Response Segmentation

Tags are short labels Revuloop attaches to a response, like `promoter`, `vip`, or `needs_follow_up`. Once a response is tagged, every analytics view, webhook filter, and AI Ask conversation can be scoped to it. This guide covers all four ways tags get onto a response and everything you can do with them once they're there.

The four ways a response gets a tag

1. Hidden tag fields (URL params, channel metadata, static values)

Drop a Hidden Field question into the survey builder. It never appears to the respondent; Revuloop fills the value server-side at submission and persists it on the response. Pick a source:

• URL parameter: pulls from the responder's query string. Send the link as `https://revuloop.com/survey/abc?campaign_id=spring24` and any hidden field configured with `campaign_id` captures `spring24`.
• Distribution channel: pulls from the channel's metadata. Useful for tagging "all responses that came through the in-app widget" vs "all responses that came through the email blast."
• Respondent attribute: pulls from the authenticated user's account (e.g. their email, name). Only fires for non-anonymous responses.
• Static value: always uses the default you set. Useful for marking "all responses to this specific share link" without dynamic logic.

Hidden field values land in two places on the response: as a normal answer row (so they appear in exports and analytics) and as a key/value snapshot under `tagsMetadata` for downstream filters.

To add one:

1. Open the survey builder.
2. Click Add Question → Routing → Hidden Field.
3. Pick a value source and key.
4. Save.

2. Tag rules (auto-tag from answer content)

Tag rules sit alongside Skip Logic in the builder. They evaluate at response submission and add tags to the `tags` array based on what the respondent answered.

A typical rule:

• Tag: `qualified_lead`
• Conditions: `NPS > 8` AND `Country in [US, CA]`
• Match: All (AND)
• Priority: 10

When someone submits the survey with NPS = 9 and Country = US, the `qualified_lead` tag is attached automatically. No external tool, no Zap, no scripts.

To add one:

1. Open the survey builder.
2. Click the Tag Rules button in the toolbar (next to Configure Flow).
3. Click Add tag rule.
4. Pick the tag name, add conditions, choose AND/OR, save.

Conditions reuse the same operator vocabulary as Skip Logic (`equals`, `greater_than`, `contains`, `in_list`, `is_empty`, etc.), so there's only one DSL to learn.

3. Manual tagging from the analytics drawer

Open any response in the analytics view. The top of the drawer shows a chip-style tag editor. Type a tag and press Enter to add it; click the × on an existing chip to remove it. Useful for one-off triage: "this response needs follow-up," "this is a false positive," etc.

Manual edits fire a `RESPONSE_TAGS_UPDATED` webhook (if configured), so external systems stay in sync.

4. The API

Programmatic callers can set tags via:

• `POST /api/v1/surveys/:id/responses`: set tags at submission time
• `PATCH /api/survey/:id/responses/:responseId/tags`: add/remove tags on an existing response (used internally by the analytics drawer)
• `POST /api/v1/surveys/:id/tag-rules`: manage tag rules

Contact support@revuloop.com for the partner integration docs covering full schemas.

What tags unlock

Filter the response list

In Survey → Results → Analytics → Responses, the top filter bar has a tag picker. Pick one or more tags, choose any (response has at least one) or all (response has every one), and the table filters. Click any tag chip on a row to add it to the filter.

Segment the entire dashboard

The dashboard filter bar has the same tag picker. When you set it, every metric tile, every chart, the sentiment trend, the NPS card, the questions tab, and the responses tab all re-render scoped to that tag subset. Bookmark the URL to share the filtered view with a teammate.

Tag breakdown card

The dashboard shows a Responses by Tag card with bars for each tag's count and completion rate. Click any bar to add that tag to the active filter. The "untagged" line on the right shows responses that no rule matched, which is useful for spotting rule gaps.

AI Analytics Ask: scope your questions

Open the Ask panel. Above the question textarea is a Scope to tags picker. Select `promoter` and ask "what do they love about onboarding?" The AI only sees promoter responses, so the answer is automatically scoped. No prompt engineering needed.

If you've already filtered the dashboard to a tag, the Ask scope picks that up automatically on open.

Webhook routing

In Settings → Webhooks → Edit webhook, the Tag Filter section lets you say "only fire this webhook when the response has `promoter`." Combine with the Advanced: condition tree section for finer rules ("only fire when NPS > 8 AND tags contain `vip`").

The condition tree uses the same operator vocab as skip logic and tag rules.

Partner event mappings

If you're integrating Revuloop with a partner platform, event mappings can be conditional too. One `visitor.checked_in` event can route to different surveys depending on `customer.tier` or `order.total`. Set this up in the partner dashboard's Event Mappings section.

How tags interact with privacy

• Anonymous responses still get tagged. The tag itself is just a label; it doesn't carry PII unless the value you put in `tagsMetadata` does.
• Hidden field sources marked "respondent attribute" are skipped on anonymous responses: the email/name lookup has nothing to pull.
• Tag rules evaluate on the same answers the response captured; if a respondent answered anonymously, the rule sees only the non-PII content.

Tag picker autocomplete

Every tag input in Revuloop (rule authoring, manual response tagging, webhook filter, dashboard filter, Ask scope) autocompletes against the org tag dictionary, the set of tags any response in your org has ever carried, ordered by usage count. Once a tag exists anywhere in your org, it's instantly available everywhere.

You can always type a brand-new tag: the picker offers a "use 'new_tag'" footer that creates it inline.

Common patterns

Routing high-value responses to a Slack channel

1. Tag rule: `high_value` when `revenue_estimate > 10000`.
2. Webhook subscription: event `RESPONSE_SUBMITTED`, filter `tags any [high_value]`, target your Slack incoming webhook URL.

Every submission that crosses the threshold pings Slack. Everything else stays quiet.

Tracking campaign attribution

1. Add a hidden field with source `url_param`, key `campaign_id`, default `organic`.
2. Distribute the survey link as `?campaign_id=spring24`.
3. In analytics, the campaign value shows up under Tag Metadata on each response. Use the Ask panel to question "what feedback came from the spring24 campaign?"

Reviewing what tag rules missed

1. On the dashboard, look at the Untagged count in the Tag Breakdown card.
2. Click into the response list with no tag filter active: the rows with no chips are the ones no rule matched.
3. Open one, see what answers it carries, and adjust your rules accordingly.

Limits and behavior notes

• A tag value is limited to 64 characters.
• A response can carry up to 64 tags (practical limit; the column is unbounded but the picker shows a reasonable view past that).
• Tag rule evaluation runs at submission time. Changing a rule does *not* retroactively re-tag old responses. Re-running rules on historical data is a manual operation (open an issue if you need it).
• Manual tag edits do fire `RESPONSE_TAGS_UPDATED` webhooks. Tag rule evaluation at submission does not fire a separate event; the tags are part of the `RESPONSE_SUBMITTED` payload.
• The org tag dictionary updates in near real-time as responses come in. Pickers across the app see new tags within a few seconds.

Troubleshooting

My hidden field isn't showing a value. Check that the source matches what you're sending: a URL-param hidden field needs the param in the link; a distribution-channel field needs the channel to have metadata configured. If the lookup is empty and there's no default, the field is dropped from the response entirely.

My tag rule isn't firing. Open a submitted response and check the Tag Metadata section in the drawer. If the answer values you're testing against aren't what you expected (e.g. an NPS rule is checking against a string instead of a number), update the rule's condition. The skip-logic preview helps debug.

The dashboard shows "no responses" after I add a tag filter. Tags only get computed *at submission time*. Responses submitted before you added your tag rules won't have those tags. New submissions will.

My webhook isn't firing on tagged responses. Open the webhook subscription and check the Tag Filter. If you picked all match, every listed tag must be present on the response; switch to any if you want at least-one-overlap semantics.