Knowledge Management Permissions (Query Metadata) Overview

Control the knowledge scope accessible to AI assistants through Query Metadata. See the "Start Building" subpages for detailed configuration.

What Is Query Metadata?

When deploying AI conversations, different users often need access to different scopes of knowledge: visitors can only query public information, VIP members get an additional plan document, and internal employees can access the employee handbook.

Query Metadata is a set of conditions that narrow the knowledge retrieval scope: it specifies which "knowledge bases, documents, FAQs, and label-matched content" a given identity, conversation, or message can reference during retrieval. It does not replace identity mechanisms — instead, it enables identities to take effect conditionally:

Contacts, conversations, and messages are containers. Query Metadata is the condition attached to the container that determines the visible scope.

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

Configurable Levels

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

Level	Effective Scope	Configuration Method
Message	That single message only	message.queryMetadata in the Conversation API; knowledge selection on the right side of the internal Q&A interface; queryMetadata in Web Chat embed (sent at the message level)
Conversation	All messages in that conversation	Passed in when creating a conversation via API
Contact	All conversations for that user	Contact editing in the dashboard (Query Builder or JSON), Contact API

Resolution Order

During retrieval, the system checks from top to bottom and uses the first level that has a configuration:

Message > Conversation > Contact > None set (no restriction — all knowledge bases attached to the AI assistant are searchable)

• If a level is not set (null) → check the next level down

• The first level with a configuration takes full effect and is not merged with lower levels — the upper-level configuration completely overrides lower levels

• An "empty object {}" also counts as configured (meaning no restriction) and stops the downward lookup — for the precise semantics of "empty set vs. unset," see the JSON Format Guide

What about internal members? Which resources members can see within the platform is controlled by role permissions (a separate mechanism). When members use the internal Q&A, they select the knowledge scope per message — this is the message level in the table above (see the Graphical Interface Guide).

How Conditions Narrow the Scope

A Query Metadata configuration consists of two parts that progressively narrow the retrievable scope:

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

2. label_relations: Within the accessible documents, further filter by label conditions (AND/OR, supports nesting)

Query Metadata only constrains knowledge base retrieval: it does not enter the LLM prompt, and the AI cannot read the conditions themselves. To make the AI "aware" of a value (such as a product ID), use contextData.

Two Ways to Build

Method	Best For	Guide
Query Builder (graphical)	Manually configuring contact permissions in the dashboard, per-message selection in internal Q&A	Start Building — Using the Query Builder
JSON Format	API integration, Web Chat embed, complex nested conditions	Start Building — Using JSON Format

Practical Use Cases

Identity	Conditions Passed (query_metadata)	Response Result
Visitor	Knowledge base: General Documents: None Labels: Visitor FAQs: 1, 2	Retrieves documents with the Visitor label from the General knowledge base, plus FAQ 1 and FAQ 2
Regular Member	Knowledge base: General Documents: A, B, C Labels: None FAQs: None	Retrieves documents A, B, C and all FAQs from the General knowledge base
Customer Service Agent	Knowledge base: Employee Documents: None Labels: Customer Service FAQs: None	Retrieves documents labeled Customer Service and all FAQs from the Employee knowledge base
Internal Employee	Knowledge base: Employee Documents: A, B Labels: None FAQs: None	Retrieves documents A, B and all FAQs from the Employee knowledge base
Admin	Knowledge bases: Employee, General Documents: None Labels: None FAQs: None	Retrieves all documents and FAQs from both the Employee and General knowledge bases

When a single AI assistant serves multiple identities, you only need to change the conditions instead of duplicating the assistant — this is the core value of Query Metadata: multi-dimensional identity cross-control (tier × department × product line), per-query control (the backend dynamically assembles conditions based on the current identity), and flexible authorization for large knowledge bases (labels and knowledge bases split by scenario).