> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge and data

> The knowledge base, data sources, variables, secrets and redaction: what an agent reads, writes and protects while a conversation runs.

What an agent reads, writes and protects while a conversation runs, one section per term.

## The knowledge base

### Knowledge base

The retrieval corpus. Documents the agent searches to ground an answer. Two words, never one. Every
environment shares one knowledge base but decides which documents it includes.

**Also asked as:**
- the documents the assistant answers from
- upload our help articles so the bot can use them
- ground replies in our own content

**Related:** [Data source](#data-source) · [Document](#document) · [Knowledge base tool](/docs/resources/glossary/build#knowledge-base-tool) · [RAG](/docs/resources/glossary/ai-terms#rag)

**Documented in:** [Querying the knowledge base](/docs/documentation/build/querying-the-knowledge-base) · [Importing data sources › Knowledge base and environments](/docs/documentation/build/importing-data-sources#knowledge-base-and-environments)

### Data source

Where knowledge base content comes from: a file, a URL, or a synced integration. Web pages, sitemaps,
uploaded files and integrations such as Zendesk Help Center or Shopify products are all data sources.

**Also asked as:**
- import a website into the knowledge base
- add PDFs for the assistant to read
- crawl our help center

**Related:** [Knowledge base](#knowledge-base) · [Refresh rate](#refresh-rate) · [Metadata](#metadata)

**Documented in:** [Importing data sources › Adding a data source](/docs/documentation/build/importing-data-sources#adding-a-data-source) · [Importing data sources › Data types](/docs/documentation/build/importing-data-sources#data-types) · [Importing data sources › Troubleshooting imports](/docs/documentation/build/importing-data-sources#troubleshooting-imports) · [Shopify tool › Importing Shopify products into your Knowledge Base](/docs/documentation/build/tools/shopify#importing-shopify-products-into-your-knowledge-base) · [Zendesk tool › Syncing Zendesk Help Center with your Knowledge Base](/docs/documentation/build/tools/zendesk-tool#syncing-zendesk-help-center-with-your-knowledge-base)

### Document

One source inside the knowledge base: a file, a page, or a synced record. Retrieval returns passages
from documents, not whole documents.

**Also asked as:**
- one item in the knowledge base
- the unit the bot searches over
- a single file or page in the knowledge base
- delete or replace one uploaded item

**Related:** [Data source](#data-source) · [Chunk](/docs/resources/glossary/ai-terms#chunk)

**Documented in:** [Importing data sources › Data types](/docs/documentation/build/importing-data-sources#data-types) · [Importing data sources › Developers](/docs/documentation/build/importing-data-sources#developers)

### Refresh rate

How often a URL or integration data source is re-synced into the knowledge base, set on import or
afterwards.

**Also asked as:**
- keep the imported pages in sync with our site
- re-crawl a URL on a schedule
- the knowledge base copy of our site is out of date
- our crawled pages are stale after the site changed
- re-sync pages pulled in from a URL
- content we crawled has changed on the source site

**Related:** [Data source](#data-source)

**Documented in:** [Importing data sources › Refresh rate](/docs/documentation/build/importing-data-sources#refresh-rate)

### Chunking strategy

How a document is split into the passages retrieval returns. LLM chunking strategies use a model to
split content along its meaning rather than at fixed lengths.

**Also asked as:**
- the bot returns half a paragraph
- split documents more sensibly for search
- passages cut in the wrong place

**Related:** [Chunk](/docs/resources/glossary/ai-terms#chunk) · [Knowledge base tool](/docs/resources/glossary/build#knowledge-base-tool)

**Documented in:** [Importing data sources › LLM chunking strategies](/docs/documentation/build/importing-data-sources#llm-chunking-strategies)

### Metadata

Tags attached to a data source so the knowledge base tool can filter what is returned — by brand,
product line, locale or support tier.

**Also asked as:**
- only search the documents for one product line
- tag content by region or language
- filter which sources a question is answered from

**Related:** [Data source](#data-source) · [Knowledge base tool](/docs/resources/glossary/build#knowledge-base-tool)

**Documented in:** [Importing data sources › Metadata](/docs/documentation/build/importing-data-sources#metadata) · [Querying the knowledge base › Meta data filtering](/docs/documentation/build/querying-the-knowledge-base#meta-data-filtering)

### Custom query

Overriding the knowledge base tool's default search text (the user's last message) with a specific
variable or phrase; query re-writing lets the model rephrase the message before searching.

**Also asked as:**
- search the knowledge base on something other than what the user typed
- rewrite vague questions before retrieval
- the bot searches with the wrong phrasing

**Related:** [Knowledge base tool](/docs/resources/glossary/build#knowledge-base-tool)

**Documented in:** [Querying the knowledge base › Custom query](/docs/documentation/build/querying-the-knowledge-base#custom-query) · [Querying the knowledge base › Query re-writing](/docs/documentation/build/querying-the-knowledge-base#query-re-writing)

### Chunk limit

How many content chunks the knowledge base tool returns per query (1–10, default 3). More chunks give
more context but add latency and token usage.

**Also asked as:**
- return more passages per question
- the assistant only sees part of the answer
- how many snippets the bot reads per question
- give the assistant more context per query

**Related:** [Chunk](/docs/resources/glossary/ai-terms#chunk) · [Knowledge base tool](/docs/resources/glossary/build#knowledge-base-tool)

**Documented in:** [Querying the knowledge base › Chunk limit](/docs/documentation/build/querying-the-knowledge-base#chunk-limit)

### Source URLs

A chat-project option that makes the agent include the source URL alongside its reply so users can
verify or read more. Tool messages, similarly, script what the user sees while the search runs.

**Also asked as:**
- show a link to where the answer came from
- cite the page behind a reply
- a "searching…" message while the bot looks things up

**Related:** [Knowledge base tool](/docs/resources/glossary/build#knowledge-base-tool)

**Documented in:** [Querying the knowledge base › Show source URL(s)](/docs/documentation/build/querying-the-knowledge-base#show-source-url-s) · [Querying the knowledge base › Tool messages](/docs/documentation/build/querying-the-knowledge-base#tool-messages)

## Data

### Variable

A named slot of project state an agent reads and writes during a conversation. Inserted anywhere by
typing `{`, and set by the Set step, the Code step, tool responses or the widget.

**Also asked as:**
- store what the customer told us for later
- pass a value between steps
- a field the assistant fills in during the chat

**Related:** [Built-in variables](#built-in-variables) · [Persistent variable](#persistent-variable) · [Secret](#secret) · [Set step](/docs/resources/glossary/build#set-step)

**Documented in:** [Variables › Creating variables](/docs/documentation/build/data/variables#creating-variables) · [Variables › Using variables](/docs/documentation/build/data/variables#using-variables) · [Variables › Setting variable values](/docs/documentation/build/data/variables#setting-variable-values)

### Persistent variable

A variable whose value carries over across sessions for the same user, chosen per variable when it is
created or edited.

**Also asked as:**
- remember a detail about a customer between visits
- keep a value from one chat to the next without asking again
- data that survives the end of a session
- remember something about a customer across separate chats
- don't ask for the same detail again next time

**Related:** [Variable](#variable) · [User ID](/docs/resources/glossary/core-objects#user-id) · [Chat persistence](/docs/resources/glossary/build#chat-persistence)

**Documented in:** [Variables › Persisting variables across sessions](/docs/documentation/build/data/variables#persisting-variables-across-sessions)

### Built-in variables

Variables every project has, set automatically when a conversation begins or an event occurs:
`user_id`, `vf_memory`, `vf_now`, `last_event` and others.

**Also asked as:**
- the system variables I can read
- get the current date inside the agent
- which values Voiceflow fills in for me

**Related:** [Variable](#variable) · [User ID](/docs/resources/glossary/core-objects#user-id) · [Timezone](/docs/resources/glossary/build#timezone)

**Documented in:** [Variables › Built-in variables](/docs/documentation/build/data/variables#built-in-variables)

### Secret

A credential stored for the agent to use without exposing it in a prompt or a function. Created on
the Secrets page with a name, a value and a visibility (masked or restricted), and inserted from the
Secrets tab of the `{` menu. The name is shared across the project; each environment holds its own
value.

**Also asked as:**
- store an API key securely for the assistant to use
- keep a password out of the prompt
- reference a credential in a request header

**Related:** [Secrets across environments](#secrets-across-environments) · [API tool](/docs/resources/glossary/build#api-tool) · [Variable](#variable)

**Documented in:** [Secrets › Creating secrets](/docs/documentation/build/data/secrets#creating-secrets) · [Secrets › Using secrets](/docs/documentation/build/data/secrets#using-secrets) · [Secrets › Security](/docs/documentation/build/data/secrets#security)

### Secrets across environments

A secret's name is shared across the project, but each environment holds its own values: a default
value its published version uses, and an optional draft value its draft version uses instead. Nothing
fills in a value an environment doesn't have; a missing value is sent as the placeholder text. A merge
leaves Main's values alone unless you choose to override them; duplicating a project copies Main's
values within the workspace; exporting copies names only.

**Also asked as:**
- one credential name with a different value for staging and production
- use a sandbox key while testing without changing the live key
- why does my secret say missing value in another environment
- the secret values disappeared after I exported the project
- a credential that differs per environment under one name

**Related:** [Secret](#secret) · [Environment](/docs/resources/glossary/deploy#environment) · [Merging](/docs/resources/glossary/deploy#merging)

**Documented in:** [Secrets › Secrets in each environment](/docs/documentation/build/data/secrets#secrets-in-each-environment) · [Secrets › Testing with a non-production credential](/docs/documentation/build/data/secrets#testing-with-a-non-production-credential) · [Secrets › Merging to Main](/docs/documentation/build/data/secrets#merging-to-main) · [Secrets › Duplicating and exporting projects](/docs/documentation/build/data/secrets#duplicating-and-exporting-projects)

### Persona

A saved set of traits used to simulate a particular kind of user when testing. Personas are scoped to
the environment they were created in.

**Also asked as:**
- test the assistant as a specific kind of customer
- role-play a difficult caller when trying the agent
- pretend to be a certain type of user
- act like an impatient customer when testing the agent
- simulate a specific type of user in a test
- try the bot as if I were a difficult caller

**Related:** [Test](/docs/resources/glossary/measure#test) · [Environment](/docs/resources/glossary/deploy#environment)

**Documented in:** [Personas](/docs/documentation/build/data/personas) · [Personas › Personas and environments](/docs/documentation/build/data/personas#personas-and-environments)

## Privacy

### PII redaction

Stripping personal data from what gets stored. A model hosted inside Voiceflow's infrastructure
detects personal information in both the agent's responses and the user's inputs; production
conversations are redacted, development ones are not.

**Also asked as:**
- mask phone numbers and emails in transcripts
- are customer details stored in plain text
- strip personal data before it is saved
- are phone numbers and emails stored in plain text in transcripts
- hide personal details from the conversation logs

**Related:** [Detected PII types](#detected-pii-types) · [Protection methods](#protection-methods) · [Transcript](/docs/resources/glossary/measure#transcript) · [Protecting sensitive data](/docs/resources/glossary/build#protecting-sensitive-data)

**Documented in:** [PII redaction › How it works](/docs/documentation/build/data/pii-redaction#how-it-works) · [PII redaction › Enabling PII redaction](/docs/documentation/build/data/pii-redaction#enabling-pii-redaction) · [PII redaction › Limitations](/docs/documentation/build/data/pii-redaction#limitations) · [PII redaction › Viewing unredacted transcripts](/docs/documentation/build/data/pii-redaction#viewing-unredacted-transcripts)

### Detected PII types

The more than 35 kinds of personal information redaction detects: identity (names, date of birth,
age), contact details, financial and account numbers, and more.

**Also asked as:**
- which sensitive fields get masked
- does redaction catch credit card numbers
- what counts as personal data

**Related:** [PII redaction](#pii-redaction) · [Protection methods](#protection-methods)

**Documented in:** [PII redaction › Detected PII types](/docs/documentation/build/data/pii-redaction#detected-pii-types) · [PII redaction › What gets redacted](/docs/documentation/build/data/pii-redaction#what-gets-redacted)

### Protection methods

The four ways redaction handles content: censor (replace with a marker like `[NAME]`), erase, override
and rich-text censoring, chosen by the type of content.

**Also asked as:**
- what replaces the redacted text
- markers like NAME or EMAIL in transcripts
- how redacted names and numbers appear in transcripts
- censor versus erase in redaction

**Related:** [PII redaction](#pii-redaction) · [Detected PII types](#detected-pii-types)

**Documented in:** [PII redaction › Protection methods](/docs/documentation/build/data/pii-redaction#protection-methods) · [PII redaction › Redaction examples](/docs/documentation/build/data/pii-redaction#redaction-examples)