Get started — using JSON format

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

Query Metadata control item description

Item category	Key name	Description	Usage
Knowledge	knowledge_base	The knowledge base referenced by the AI when generating conversations	Wrapped in an object named knowledge_bases Array→[...] Within, pass in knowledge base ids; multiple knowledge bases can be opened
Knowledge base files/documents	Chatbot_file	Files/documents within the knowledge_base that can be referenced	Passed in within the knowledge_base as Object→{...} Defined in
Q&A dataset	FAQ	The FAQ sets within the specified knowledge_base that can be referenced	Same as above
Knowledge base file/document label	label	Labels within files/documents. If Chatbot_file is not specified, you can still specify label; it restricts references to documents matching that label, used to support more granular document permission segmentation	Pass in using an object named label_relations, using "OR"/"AND" to define applicable document label conditions, passing in a property named conditions Array→[...] Defined in

Structure format example and explanation

"query_metadata": {
    "knowledge_bases": [
      {
        "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
        "chatbot_file_ids": [
          "9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e" // file document
        ],
        "faq_ids": [
          "a1b2c3d4-e5f6-7890-abcd-1234567890ab" // FAQ
        ],
        "has_user_selected_all": "False" // selected all knowledge bases
      },
  //  Multiple objects can be passed in to set referenceable files, FAQs, etc. across multiple databases at once
  //    {
  //      "knowledge_base_id": "Id2",
  //      "chatbot_file_ids": [
  //        "file_id1" // file document
  //      ],
  //      "faq_ids": [
  //        "faq_id1",
  //        "faq_id2" // FAQ
  //      ],
  //    },
    ],
 
  "label_relations": { // labels
      "operator": "OR",  // set applicable criteria (must meet all or any one)
      "conditions": [
        { "label_id": "11111111-2222-3333-4444-555555555555" },
        // Nested definitions can be used for complex conditions
        {
          "operator": "AND",
          "conditions": [
            { "label_id": "66666666-7777-8888-9999-000000000000" }, 
            { "label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
          ]
        }
      ]
    },
}

How to obtain IDs at each level?

You can view the ID field in the content of each level in the left menu (for knowledge base, for example, you can click the copy icon to directly copy all ID contents)

Location to obtain IDs at each level

Key logic explanation

1. label_relations logic

• OR Operation: accessible if any one label matches

• AND Operation: must match all labels to gain access

• Nested logic: supports multi-level, nested permission combinations

2. knowledge_bases settings

• has_user_selected_all = "True": Can access all content of that knowledge base

• has_user_selected_all = "False": Can only access the specified files and FAQs

Contact settings

You can directly write the query_metadata settings in JSON format when editing a contact:

Contact JSON editing interface

The system will automatically validate the format and apply the 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 the contact (for example: providing Web Chat service to customers without registered contact accounts), you can provide Query Metadata during embedding; the system will by default enable the message-level knowledge base document filtering mechanism

Code example

<script>
  window.maiagentChatbotConfig = {
    // Set base Web Chat parameters
    webChatId: 'The Web Chat ID obtained from the 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' // file document
          ],
          faqIds: [
            'a1b2c3d4-e5f6-7890-abcd-1234567890ab' // FAQ
          ],
          hasUserSelectedAll: 'False' // selected 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 explanation

This parameter is the exclude/use-few-items setting under a single knowledge base; it will apply label filtering conditions only on the files you have opened.

Parameter values	Behavior	Applicable scenarios
"True"	The system selects all content in that knowledge base, excluding items listed in chatbotFileIds and faqIds The items listed in	Using 98 out of 100 files, the 2 files listed in the parameter are marked as not used
"False"	The system selects chatbotFileIds and faqIds the items explicitly listed	Only 2 out of 100 files are used

Code example

// hasUserSelectedAll: True, list file IDs to exclude
{
  "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000",
  "chatbotFileIds": ["fileID_to_exclude1", "fileID_to_exclude2"],
  "faqIds": ["FAQ_ID_to_exclude1"],
  "hasUserSelectedAll": "True"
}

// hasUserSelectedAll: False, list file IDs to include
{
  "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000",
  "chatbotFileIds": ["fileID_to_include1", "fileID_to_include2"],
  "faqIds": ["FAQ_ID_to_include1"],
  "hasUserSelectedAll": "False"
}

Priority between queryMetadata and contactId

• When neither queryMetadata nor contactId is set: The system will search the entire knowledge base scope without any exclusions

• You can set queryMetadata or contactId independently

• When both are set: The system will only use the Query Metadata settings in the contact (identified by contactId)