> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/maiagent-tech-en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md).

# Getting Started—Using JSON Format

## Query Metadata Control Item Description

<table><thead><tr><th width="108.66668701171875">Item Category</th><th width="140.66668701171875">Key Name</th><th>Description</th><th>Usage</th></tr></thead><tbody><tr><td>Knowledge Base</td><td><code>knowledge_base</code></td><td>Knowledge base referenced by AI assistant when generating conversations</td><td>Wrapped in an <code>Array→[...]</code> named knowledge_bases, pass in knowledge base id to enable multiple knowledge bases</td></tr><tr><td>Knowledge Base Files</td><td><code>Chatbot_file</code></td><td>Reference files in specified knowledge base</td><td>Defined in <code>object→{...}</code> passed into knowledge_base</td></tr><tr><td>FAQ Dataset</td><td><code>FAQ</code></td><td>FAQ sets that can be referenced in specified knowledge base</td><td>Same as above</td></tr><tr><td>Knowledge Base File Labels</td><td><code>label</code></td><td>File labels, can specify labels to restrict access to only files with matching labels even without specifying Chatbot_file, used for more granular file permission control</td><td>Passed in using label_relations object, define applicable file label conditions with <code>"OR"/"AND"</code>, defined in conditions <code>Array→[...]</code></td></tr></tbody></table>

### Structure Format Example and Description

```json
"query_metadata": {
    "knowledge_bases": [
      {
        "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
        "chatbot_file_ids": [
          "9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e" // Files
        ],
        "faq_ids": [
          "a1b2c3d4-e5f6-7890-abcd-1234567890ab" // FAQ
        ],
        "has_user_selected_all": "False" // Select all knowledge bases
      },
  //  Can pass in multiple objects to configure referenceable files, FAQs etc under multiple databases at once
  //    {
  //      "knowledge_base_id": "Id2",
  //      "chatbot_file_ids": [
  //        "file_id1" // Files
  //      ],
  //      "faq_ids": [
  //        "faq_id1",
  //        "faq_id2" // FAQ
  //      ],
  //    },
    ],
 
  "label_relations": { // Labels
      "operator": "OR",  // Set applicable criteria (must match all or match any)
      "conditions": [
        { "label_id": "11111111-2222-3333-4444-555555555555" },
        // Can use nested definitions for complex conditions
        {
          "operator": "AND",
          "conditions": [
            { "label_id": "66666666-7777-8888-9999-000000000000" }, 
            { "label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
          ]
        }
      ]
    },
}
```

## How to Get IDs for Each Level?

You can view the ID field in each level's content in the left menu (taking knowledge base as an example, you can click the copy icon to directly copy all ID content)

## Key Logic Description

### 1. label\_relations Logic

* `OR` operation: Access granted if any label matches
* `AND` operation: Must match all labels to grant access
* Nested logic: Supports multi-level, nested permission combinations

### 2. knowledge\_bases Settings

* `has_user_selected_all = "True"`: Can access all content in that knowledge base
* `has_user_selected_all = "False"`: Can only access specified files and FAQs

## Contact Settings

You can directly write query\_metadata settings in JSON format when editing contacts:

The system will automatically validate the format and apply permission settings.

## Web Chat Initialization Settings

{% hint style="info" %}
For Web Chat embedding introduction, please refer to [🔗Web Chat Initialization](/tech/maiagent-tech-en/api-integration/web-chat-sdk.md)
{% endhint %}

If you want to restrict conversation content before contacts (e.g.: providing Web Chat service to customers without registered contact accounts), you can provide Query Metadata during embedding. The system will enable knowledge base document filtering at the message level by default.

### Code Example

```javascript
<script>
  window.maiagentChatbotConfig = {
    // Set Web Chat basic parameters
    webChatId: 'Web Chat ID obtained from Admin embed window',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    primaryColor: '#3854d8',
    allowDrag: true,
    
    // Set Web Chat knowledge base document search scope
    queryMetadata: {
      labelRelations: { // Labels
        operator: 'OR',
        conditions: [
          { labelId: '186a3012-44ac-4cd2-a132-a76bfda5bcae' },
          {
            operator: 'AND',
            conditions: [
              { labelId: '0267c405-cc26-4497-b17f-180aedf8b0eb' }, 
              { labelId: '60f81de6-a4b6-4d86-9781-5430783ef0b6' }
            ]
          }
        ]
      },
      knowledgeBases: [
        {
          knowledgeBaseId: '123e4567-e89b-12d3-a456-426614174000',
          chatbotFileIds: [
            '9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e' // Files
          ],
          faqIds: [
            'a1b2c3d4-e5f6-7890-abcd-1234567890ab' // FAQ
          ],
          hasUserSelectedAll: 'False' // Select all knowledge bases
        }
      ]
    },
    
    // Set Contact
    contactId: '60f81de6-a4b6-4d86-9781-5430783ef0b6'
  };
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>
```

### hasUserSelectedAll Parameter Description

This parameter is for excluding/using a few items under a single knowledge base. Label filtering conditions will be applied on top of your opened documents.

<table><thead><tr><th width="82">Parameter Value</th><th>Behavior</th><th>Applicable Scenario</th></tr></thead><tbody><tr><td><code>"True"</code></td><td>System selects all content in that knowledge base, excluding items listed in <code>chatbotFileIds</code> and <code>faqIds</code></td><td>Using 98 files out of 100, 2 files listed in parameters indicate not to use</td></tr><tr><td><code>"False"</code></td><td>System selects only items explicitly listed in <code>chatbotFileIds</code> and <code>faqIds</code></td><td>Only using 2 files out of 100</td></tr></tbody></table>

### Code Example

```js
// hasUserSelectedAll: True, list file IDs to exclude
{
  "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000",
  "chatbotFileIds": ["Unwanted File ID 1", "Unwanted File ID 2"],
  "faqIds": ["Unwanted FAQ_ID1"],
  "hasUserSelectedAll": "True"
}

// hasUserSelectedAll: False, list file IDs to use
{
  "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000",
  "chatbotFileIds": ["Wanted File ID 1", "Wanted File ID 2"],
  "faqIds": ["Wanted FAQ_ID1"],
  "hasUserSelectedAll": "False"
}
```

### queryMetadata and contactId Priority

* **When neither queryMetadata nor contactId is set**: System will search entire knowledge base scope without any exclusions
* **Can set queryMetadata or contactId individually**
* **When both are set**: System will only use Query Metadata settings in the contact (identified by contactId)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/tech/maiagent-tech-en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.