Knowledge Management Permissions (Query Metadata) Overview

Use Query Metadata to control the knowledge an Agent can retrieve. See the Getting Started subpage for detailed configuration.

What is Query Metadata?

Query Metadata is a set of conditions that restrict the scope of knowledge retrieval: it specifies which knowledge bases, documents, FAQs, and content matching label conditions a contact, conversation, or message can reference during retrieval. Contacts, conversations, and messages are containers; Query Metadata consists of conditions attached to those containers that determine their actual visibility scope. Roles are not containers.

For concepts, use cases, and admin operations, see Knowledge Access Permissions: Query Metadata in the user manual. This page is the entry point for engineers, covering the API fields at each level, resolution order, and condition model. For JSON syntax, see Getting Started—Using JSON.

Further reading: Introduction to Contacts and Integration, Differences Between Roles and Contacts

Supported Configuration Levels

Query Metadata can be configured at three levels, each with a different integration method:

Level	Scope	Configuration Method
Message	Only that message	message.queryMetadata in the conversation API; knowledge selection on the right side of the internal Q&A interface; queryMetadata in the Web Chat embed (submitted at the message level)
Conversation	All messages in that conversation	Included in the API request that creates the conversation
Contact	All conversations for that user	Contact editing in the admin interface (Query Builder or JSON), Contact API

Resolution Order

During retrieval, the system selects the first configured level in this order:

Message > Conversation > Contact > Agent default label filter > None configured (unrestricted; all knowledge bases attached to the Agent are searchable)

• If a level is unset (null) → check the next level

• The first configured level takes effect in its entirety, without merging with lower levels—the higher-level configuration completely overrides the lower levels

• An empty object {} also counts as configured (meaning unrestricted) and stops further lookup. For the precise semantics of empty collections versus unset values, see the JSON Guide

• The Agent default label filter (defaultLabelRelations in Agent settings) applies only when Message, Conversation, and Contact are all null: its label conditions filter all knowledge bases attached to the Agent. If any of the three levels is configured (including {}), it does not apply. For admin configuration, see Knowledge Base Label Filtering in the user manual

What about internal members? Role permissions control which resources members can see in the platform through a separate mechanism. When using internal Q&A, members select the knowledge scope per message, corresponding to the message level in the table above. For instructions, see Getting Started—Using Query Builder in the user manual.

How Conditions Narrow the Scope

Query Metadata consists of two parts that progressively narrow the retrieval scope:

1. knowledge_bases: which knowledge bases are accessible, and which documents/FAQs within each knowledge base are accessible (select all, select all with a few exclusions, or select only a few)

2. label_relations: further filter accessible documents by label conditions (AND/OR, with nesting support)

Query Metadata restricts only knowledge base retrieval: it is not included in the LLM prompt, so the AI cannot read the conditions themselves. To let the AI know a value (such as a product ID), use contextData.

It also does not apply to Text to SQL or tools: the Agent does not use Query Metadata when querying a database, and there is no request-level field for restricting tables. Database scope can only be controlled through enablement, Agent association, table selection, and account permissions. See Text to SQL: FAQ.

Two Ways to Build Conditions

Method	Best For	Guide
Query Builder (graphical)	Manually configuring contact permissions in the admin interface; per-message selection in internal Q&A	User manual: Getting Started—Using Query Builder
JSON	API integration, Web Chat embedding, complex nested conditions	Getting Started—Using JSON

Practical Use Cases

When one Agent serves multiple user identities, simply provide different Query Metadata for each identity; there is no need to duplicate the Agent. For a comparison of the conditions for visitors, members, customer service staff, internal employees, and administrators, see Practical Use Cases in the user manual.