# 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](https://docs.maiagent.ai/tech/maiagent-tech-en/api-integration/web-chat-sdk)
{% 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)