How to configure AI Chat Agents

How to configure AI Chat Agents

Scroll Export Button

This document provides instructions for configuring AI chat agents in x-bees and Collaboration 7, with integrations available for Generative AI, Webhooks, AWS SQS and Dialogflow CX.

Developer documentation: Wildix Developer Docs .

Created: August 2024

Updated: August 2026

Permalink: https://wildix.atlassian.net/wiki/x/4APOAQ

Introduction

AI chat agents are powerful tools for managing customer interactions, designed to efficiently handle a wide range of requests and tasks. You can integrate the following AI chat agents with x-bees and Collaboration 7: 

  • Generative AI lets you create highly interactive and intelligent chat agent without any coding expertise. You just need to provide clear instructions and the AI model generates dynamic, context-aware responses.

  • Webhooks provide real-time communication by sending HTTP POST requests to a specified URL when certain events occur. This allows for immediate processing and response, making it ideal for time-sensitive interactions

  • AWS SQS offers a reliable and scalable solution for message queuing, ensuring that even high volumes of chat events are handled efficiently. It decouples the processing of events, allowing your AI chat agent to manage requests asynchronously and at scale

  • Dialogflow CX enhances the natural language understanding (NLU) of your AI chat agent, enabling complex and multi-turn conversations with users. This integration is well-suited for advanced dialog management and contextual responses

Note: Setting up AI chat agents with Webhooks, AWS SQS, Dialogflow CX requires some technical knowledge, or a specialist who meets this requirement and can perform the setup. 

Requirements

AI Chat Agent Creation

Note: Some features described in this documentation will be available in production soon.

It is possible to set up to 50 AI chat agents per organization.

To create an AI chat agent, proceed with the following steps:

  • Navigate to WMS -> PBX -> Integrations -> Cloud integrations

  • In the AI section, choose Chat AI Agents

x-bees bots-WMS.jpg
  • Select Chat AI Agents and click Add new agent

x-bees bots-Add new chatbot.png
  • Enter a name for your Chat AI agent

  • Choose an agent category name

  • Upload a picture (optional)

  • Select the integration type for processing chat events:

    • Generative AI 

    • Webhook

    • AWS SQS

    • Dialogflow CX

x-bees bots-Create a chat bot.png
  • Configure the chosen integration type (see instructions below) 

  • To let users interact with the bot, proceed to the Visibility Settings and enable the Allow users to find the bot using search checkbox:

allow-users-to-find-the-bot-using-search.png
  • Click Add to save and activate your AI chat agent

Generative AI

When setting up Generative AI as the integration type, it's important to create a clear and detailed prompt for the AI chat agent, as this greatly affects its performance and reliability. Since prompt engineering is an ongoing process, you can improve prompt effectiveness over time based on user feedback.

You can organize your system prompts into clear sections, addressing a specific aspect of the AI chat agent's behavior. For example:

  • Identity: describe the AI agent’s persona, defining its role and setting the interaction context.

  • Style: provide instructions on how the agent should communicate with users, including such details such as tone, language, and level of formality.

  • Response Guidelines: outline the desired structure of the AI’s responses, including any required formats and limitations, if any.

  • Task and Goals: clarify the tasks the agent is expected to perform and the steps it should take to achieve its objectives.

generative-ai-tool.png

After creating the agent, to create API key click Create API Key button:

generative-ai-create-new-api-key.png
  • Enter a name for identification

  • Click Create and copy the secret using the Click to reveal button:

generative-ai-click-to-reveal-api-key.png

 

Add a capability

In case of Generative AI integration type, you can enhance capabilities of your AI chat agent:

  • Handover: allows to transfer the chat to an agent or a service

  • Delegate: allows to delegate user’s request to another AI chat agent

  • Suggestions: gives possibility to configure quick replies 

  • Knowledge Bases, Wilma Tools, etc. (see the relevant sections below)

chat-agent-capabilities-handover-delegate.png

Note: For WhatsApp, button titles created using the Suggestions tool have a 20-character limit.

Note:

  • Third-party Function option was deprecated and replaced with Wilma Tools → Webhook feature.

  • Current third-party functions in existing Chat Agents continue to work. But in case you need to edit/update them, you need to replace them with Webhook tools:

  1. Create a new Webhook tool within Wilma tools

  2. Add the Webhook tool to the Chat Agent

  3. Remove the old third-party function from the Chat Agent

In case of importing Chat Agent which includes third-party function, you can convert it to Wilma Tool. To do this:

  1. Click on the Third-party function in the imported agent

third-party-function-imported-agent.png
  1. Click Convert to Wilma Tool

convert-to-wilma-tool-button.png
  1. Confirm the conversion by clicking Convert

confirm-conversion.png

To add a capability:

  1. Click Add Capability -> choose the necessary option

  2. Fill out the required fields
    For example, for Delegate tool, you need to select AI Agent, enter description, choose pipeline – whether you wish to delegate the conversation without reply, generate a reply and delegate the conversation, generate a reply based on instructions (you need to provide instructions) and delegate the conversation:

delegate-tool-descriptions.png

 

You can add multiple tools for one AI chat agent. If you need to delete a tool, click the delete icon:

delete-tool.png

Knowledge Bases

The Knowledge Base allows you to collect and search information from different sources, such as files, Confluence pages, and Google Drive folders. See more details in the documentation How to Set up Knowledge Base in WMS.

To add Knowledge Base to a Chat Agent:

  • Navigate to the Capabilities section

  • Click Add capability

add-tool-chat-agent.png
  • In the window that opens up, navigate to the Knowledge Bases section:

knowledge-base.png
  • Select the knowledge base and click on it. The following window pops up, where you can add instructions, choose Search Strategy (Hybrid, Semantic, or Text), adjust Threshold (High, Optimal, Low), and define Search Limits to improve the accuracy of AI Chat Agent responses. Search limit defines the number of search results (possible values are from 1 to 50). Once done, click Add:

knowledge-base-settings.png

Wilma Tools

Wilma Tools includes a set of tools for AI Agents, e.g. sending message, SMS, email, setting up Webhook, etc. which can extend their functionality.

To add Wilma Tool to a Chat Agent:

  • Navigate to the Capabilities section

  • Click Add capability

  • In the window that opens up, navigate to the section below Knowledge Bases section (if available). The available Wilma Tools are displayed split into the relevant categories

wilma-tools.png
  • Select the necessary capability and click on it. Its settings are displayed in the window on the right:

capability-settings.png
  • Configure the Variables section by selecting the appropriate processing mode, if required (see Variable Processing Modes for details), and the Pipeline

  • Click Add to add the capability to the AI Chat Agent:

add-button-to-add-capability.png

Calendar

Calendar function lets AI Chat Agent handle calendar tasks like scheduling, updating, or canceling events. For instructions how to set up Calendar tool, check out the guide How to Set Up Wilma Tools.

To add a calendar function:

  1. Navigate to the Calendar section within Capabilities list:

calendar-section.png
  1. Choose the calendar function you wish to add and click on it

  2. On the window that pops up, enter the Start Message:

calendar-function-start-message.png
  1. Here you can modify variables. Depending on the calendar function chosen, there is a different list of variables. For most of them, it is recommended to leave the Auto mode. However, you can customize the following variables:

    • owner_email: Email of the user whose calendar will be modified

    • owner_name: name of the user whose calendar will be modified

    • description: event description

    • duration (create event function only): duration of the event. Note: in case you set a predefined option, make sure the duration corresponds to the duration options set in user’s Kite Calendar (x-bees / Collaboration 7 settings → Kite Settings → Calendar Settings → Duration)

    • reason (rescheduling/ cancelling event function only):

    • resource: the AI agent that created a calendar event. The variable allows you to track and distinguish the source of scheduled meetings.

    • summary: summary of the event

    • timezone: timezone of the scheduled event

When editing variables, the following options are available:

  • Auto: the Agent automatically decides how to fill out the variable (e.g. in case of owner_email - whose calendar to add the event to)

  • Guided: the option allows to you to enter instructions for the Agent (e.g. in case of owner_email you can enter instructions whose calendar to use, or you can even paste the emails of the users whose calendars should be used).

  • Predefined: the option makes the value static. For example, in case of choosing predefined value for owner_email, the Chat Agent will be able to modify only the calendar of the user whose email is entered in the predefined field.

calendar-function-variables.png
  1. Once done, click Add:

add-calendar-function.png

Capability Settings

Variable Processing Modes

When configuring variables for capabilities, the following processing modes are available:

  • Auto: The AI automatically detects or decides the value based on the variable name and context.

  • Guided: Allows you to provide specific instructions or additional context on how the agent should fill the variable.

  • Predefined: Sets a static, fixed value for the variable that does not change.

Pipeline

When adding a capability, you can modify its pipeline:

  • Blocking request: the Chat Agent waits for response from the system and uses response in the reply.

  • Blocking request guided: the Agent waits for response and uses instructions to generate a reply. You can enter the relevant reply instructions:

pipeline-blocking-request-guided.png

 

  • Async request: the Agent triggers the tool and continues the conversation immediately without waiting for a response ("fire and forget"). This is ideal for background tasks where the immediate reply doesn't depend on the tool's result.

  • Async request guided: the Agent replies without waiting for response from the system and uses the instructions that you indicate here to generate its reply:

async-request-guided.png

 

Analysis

You can also configure Analysis annotations for AI Chat agent capabilities to automatically add tags, log comments, capture capability variables, and record tool output, helping categorize, filter, and analyze conversations in Revenue Intelligence.

  1. Under Capabilities section, add or edit a supported capability

  2. In the capability configuration window, scroll to the Analysis section and click Add annotation

  3. Select the annotation type:

  • Tag – adds a tag to the chat, or conference for Revenue Intelligence analysis.

Note: Tags added through Analysis annotations can later be used to filter and categorize conversations in Revenue Intelligence.

  • Log comment – adds predefined text to the conversation timeline for users and Revenue Intelligence.

  • Log variables – records capability variable values for Revenue Intelligence and conversation details (Available only for capabilities that support variables).

  • Log result – records the tool output for Revenue Intelligence and conversation details.

ai-agent-capabilities-analysis.png

 

  1. Configure the annotation. The available settings depend on the selected annotation type. Where applicable, choose whether the annotation should be applied when the tool succeeds, fails, or both.

configure-the-annotation.png
  1. Сlick Add or Apply

  2. Click Save to save the AI agent configuration

Additional Settings

  • Model: choose the preferred AI model for generating responses. If no model is selected, the system uses the default model.

chat-bot-model.png
  • Visibility Settings: choose if you wish to allow users to find the agent using search

visability-settings.png
  • Access Settings: choose if the agent should be available to everybody or PBX users only (Authenticated option)

access-settings.png
  • ACL Group: you can assign an ACL Group to an AI Chat Agent, defining who can view the agent's recordings in analytics.

Note: Only admins can assign a PBX ACL group to an AI Agent.

acl-group.png

Generative AI Bot response rules

The AI Chat Agent response behavior depends on the type of conversation and its participants.

Simple group chats:

  • In a group chat where only the user and the Generative AI bot are participants, the bot responds to user messages without requiring @mention or Quote

  • After adding additional participants, the bot continues responding until another participant sends a message in the chat. After that, the bot responds only when explicitly mentioned via @mention or when replying to the bot’s message using Quote

  • In group chats created with three or more participants, where one of the participants is a Generative AI bot (or when a Generative AI bot is added to an existing chat with other participants), the bot responds only when explicitly mentioned via @mention or when replying to the bot’s message using Quote

Kite chats:

  • If a Kite chat has only two participants and one of them is the bot, the bot always responds, regardless of whether the other participant is an internal or external user

  • If another internal user from the same organization as the bot is added to the chat, the bot responds to same organization users only when explicitly mentioned via @mention

  • If an external user is added to the chat, the bot continues responding to that external user normally without requiring @mention or Quote

Webhook

When configuring a Webhook as the integration type, you need to specify the following fields:

  1. Target:

  • Enter the URL that the Webhook will use to send POST requests

This URL should be publicly accessible and secured with a valid HTTPS certificate. It should be designed to accept HTTP POST requests with JSON payloads and respond with status codes in the 200-299 range as quickly as possible.

It's important to ensure that your Webhook endpoint can handle multiple identical calls in case of retries due to network or server failures. AI chat agent platforms may attempt to redeliver event payloads up to 3 times if the initial delivery is unsuccessful.

  1. Secret:

  • The secret ensures that only requests from Wildix system are accepted, preventing unauthorized access or potential security breaches. The secret key is included in the headers of each POST request sent by the Webhook. Your server should validate this key to ensure the request is legitimate before processing the event data

x-bees bots-Webhook.jpg
  1. After creating the bot, click Create API Key button to create API key:

  • Enter a name for identification

  • Click Create and copy the secret using the Click to reveal button

generative-ai-create-new-api-key.png

You can configure a test Webhook bot using these instructions: https://docs.wildix.com/guides/2024/07/20/chatbot-simple/.

AWS SQS

When configuring AWS SQS as the integration type, you need to specify the following fields to establish the connection between x-bees/ Collaboration 7 and your AWS SQS queue:

  1. Target:

  • Enter the URL of your SQS queue. This is where the chat events are sent, for example, https://sqs.amazonaws.com/11111/wildix-events-queue

  1. Key:

  • Enter your AWS Access Key ID here. This key is used to sign the request that x-bees/ Collaboration 7 sends to AWS SQS

  1. Secret:

  • Enter your AWS Secret Access Key. This secret is paired with your AWS Key to securely sign the requests

x-bees bots-AWS SQS.jpg
  1. After creating the bot, click Create API Key to create API key:

  • Enter a name for identification

  • Click Create and copy the secret using the Click to reveal button

Dialogflow CX

To configure Dialogflow CX as the integration type, you'll need to provide specific information to establish the connection between x-bees/ Collaboration 7 and your Dialogflow CX agent. The fields you need to fill in are as follows:

  1. Private Key:

  • Upload the private key file associated with your Google Cloud service account

  1. Location:

  • Enter the region where your Dialogflow CX agent is deployed. This is typically a region-specific identifier, for example, us-central1, europe-west1

  1. Language:

  • Specify the language that your Dialogflow CX agent will use to understand and respond to user inputs. The language code should match the languages supported by your Dialogflow CX agent, for example, en for English, es for Spanish

  1. Agent ID:

  • Enter the unique identifier of your Dialogflow CX agent. This ID links your AI chat agent to the specific Dialogflow CX agent that you’ve configured in Google Cloud

x-bees bots-Dialogflow CX.jpg

It is possible to set up a handover to allow a AI chat agent to transfer a chat to one or multiple agents: https://docs.wildix.com/docs/messaging/bots/integrations/dialogflow.

Access Settings

For Generative AI and Dialogflow CX integration types, you can configure Access Settings:

access-settings.png

In Access Settings, you can choose if you want to make the AI chat agent available to everybody or restrict access to internal users only (option Organization). By default, chat agent is available to everybody. 

Processing Predefined Replies 

Chatbots can display and react to predefined reply options. The reply options include buttons that allow users to perform actions, such as opening a URL or triggering specific responses (e.g., "Yes," "No"). Based on user selection, when a button is pressed, the chatbot can update messages, replacing or modifying previous responses (e.g. removing the "Yes," "No" options after user selects Yes/ No). 

To configure predefined replies, you can use Conversations API (documentation: https://docs.wildix.com/api-reference/rest/x-bees/conversations/#/operations/SendMessage and https://docs.wildix.com/api-reference/typescript/xbees-conversations-client/xbees-conversations-client.sendmessagecommand/) or integrate Dialogflow to define response options. 

Also, in case you are using Welcome message with quick replies for website widget and the conversation is routed to chat agent, you can configure the chat agent (e.g. by creating necessary prompts with Generative AI integration type) to provide responses based on user selection.

Chat AI Agent application

Conversation with Chat AI Agent

You can find the Chat AI Agents in Search under the Bots category: 

When you click on it, one-on-one conversation with the chat agent opens and you can send your request: 

If you wish to have group conversation with a Chat AI Agent, create the conversation and invite the AI Agent: 

Website Widget 

Once you set up a bot, you can configure a website widget to enable customer interaction with the bot. 

  1. Go to WMS -> PBX -> Integrations -> Cloud integrations

  2. Choose Kite and select the necessary widget or create a new one

  3. Under Routing settings, select bot option and choose a specific bot from the list

kite-select-bot.png
  1. Click Save to apply the settings

  2. Embed the widget on your website

For more details, check out the guide Website widget configuration.

Chat traces

With The View Traces feature, you can closely monitor chatbot activity, including errors, tool usage, message flow, and detailed pipeline execution.

To access View Traces, follow the steps below:

  1. Go to WMS -> PBX -> Integrations -> Cloud integrations

  2. Select Chat AI Agents

  3. Click the trace diagram on the right side of the AI Agent card to open and view the traces

view-traces.png

 

  1. The Chat Traces page will open, displaying a list of all bot activity. Each trace entry includes the following columns: Trace ID, Service, User Name, Status, Duration, and Date.

  2. You can use search field to find specific trace.

chat-traces.png

To view detailed information about a specific trace follow these steps:

  1. Click on any trace entry in the list

  2. In the opened Details panel, click Request in the Pipeline section

A window will appear with full technical details, including:

  • URL

  • Headers

  • Body

  • Result