Getting Started - Using JSON Format

If you want to write more complex filtering conditions, you can use JSON format to directly specify by level IDs (such as knowledge base, single document, etc.)

Query Metadata Control Item Description

Item Category	Key Name	Description	Usage
Knowledge Base	knowledge_base	Knowledge base referenced by AI assistant when generating conversations	Wrapped in an Array→[...] named knowledge_bases, pass in knowledge base id to enable multiple knowledge bases
Knowledge Base Files	Chatbot_file	Reference files in specified knowledge base	Defined in object→{...} passed into knowledge_base
FAQ Dataset	FAQ	FAQ sets that can be referenced in specified knowledge base	Same as above
Knowledge Base File Labels	label	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	Passed in using label_relations object, define applicable file label conditions with "OR"/"AND", defined in conditions Array→[...]

Structure Format Example and Description

"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)

Location to get IDs for each level

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:

Contact JSON editing interface

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

Web Chat Initialization Settings

For Web Chat embedding introduction, please refer to 🔗Web Chat Initialization

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

<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.

Parameter Value	Behavior	Applicable Scenario
"True"	System selects all content in that knowledge base, excluding items listed in chatbotFileIds and faqIds	Using 98 files out of 100, 2 files listed in parameters indicate not to use
"False"	System selects only items explicitly listed in chatbotFileIds and faqIds	Only using 2 files out of 100

Code Example

// 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)