AI Voice Agent
Let AI take over the first line of call handling!
The AI Voice Agent answers incoming calls, conducts a natural conversation with the customer, and executes the processes you define. It answers questions, gathers necessary information, uses your company's knowledge and data, and when the situation requires it – transfers the call to a consultant or initiates further actions in Thulium.
You decide who it should be, how it should talk, which knowledge to use, and what to do. AI takes care of the rest.
To start configuring the AI Voice Agent, go to the Administration section, then select AI Assistant → AI Voice Agent.
Configuring the AI Voice Agent#
In the AI Voice Agent module, you will find a list of previously created AI voice agents along with information about the language they use for conversations and their current status – active or inactive.
To add a new AI Agent, click the Add button.
Basic#
In the Basic section, specify the most important information about the AI Voice Agent you are creating:
- Name – give the Agent a name that makes it easier to identify in the system. It is helpful if it indicates its role or the process it handles, e.g., AI Reception, Order Handling, Recruiter, or Appointment Registration. This will be especially useful if your organization uses several AI voice assistants in the future.
- Conversation Language – choose the language in which the AI Voice Agent will conduct conversations with customers.
A well-chosen name will help you easily recognize the Agent during further configuration and when assigning it to the appropriate IVR scenario.
Persona#
The Persona section allows you to define who the AI Voice Agent should be, what role it plays in your organization, and how it should communicate with callers.
To simplify configuration, you can use one of the ready-made personas, such as:
- Reservations - reception – hotel or travel agency: reservations, availability, changes.
- Store - order handling – e-commerce: order status, availability, returns, and complaints.
- Registration - visits – medical facility: scheduling and canceling appointments, preparation for examinations.
- Service desk - first line – IT and hosting: receiving reports and help with common issues.
After selecting a persona, three elements are automatically filled in:
- Business Context – specifies the purpose of the Agent and which business process it supports.
- Identity – defines who the Agent is from the caller's perspective, how it should introduce itself, and what role it plays during the conversation.
- Style and Tone Rules – define how the conversation should be conducted, including the character of speech, the way questions are asked, and behaviors the Agent should avoid.
You can use these ready personas as they are or treat them as a starting point to create your own configuration. Each of the completed elements can be edited and adjusted to your company's specifics and the process the AI Voice Agent should execute.
When using a ready persona, remember to personalize it. Fill in the places marked with square brackets that require information specific to your organization, e.g., [COMPANY NAME].
Besides defining the role and communication style, you can also decide how the AI Voice Agent will sound. The available voices are matched to the previously selected conversation language.
Before choosing, you can listen to a sample of each voice and select the one that best fits your brand's character and the Agent's role. A well-chosen voice helps give the conversation the right character and influences how customers perceive the AI Voice Agent.
Conversation#
The Conversation section allows you to configure the course of contact between the AI Voice Agent and the caller. Here you define how the Agent will start and end the conversation and what information it should collect during it.
- Welcome Message – defines the first utterance the caller will hear. The greeting should be short and natural while clearly informing what the Agent can help with.
According to the transparency obligation under Article 50 AI Act, the caller should be informed that they are interacting with an artificial intelligence system. Therefore, the welcome message must explicitly state that the conversation is conducted by an AI Voice Agent / AI Assistant. The greeting is checked upon saving: if this condition is not met, the AI voice assistant will not be saved, and the reason along with a suggested correct greeting will be displayed, which you can insert with one click.
- Compliant examples: “Good day, I am an AI assistant…”, “You are speaking with an AI assistant”, “This is artificial intelligence speaking”. The abbreviation “AI” alone is sufficient.
- Non-compliant examples: “assistant”, “virtual assistant”, “automatic system”, “bot”, and also “AI” appearing only in the company or product name (e.g., “AI Solutions”), because these do not indicate who is on the other side.
The information must be given at the beginning of the greeting, before the business content, not after initial questions.
- Farewell Message – defines how the conversation ends. It is useful to inform the client what will happen next, e.g., that their case has been accepted, will be forwarded for processing, or that a consultant will contact them.
- Leading Questions – allow specifying the information the AI Voice Agent should gather during the conversation. You can plan a simple scenario and indicate specific questions the Agent should ask the caller.
For example, an Agent handling the recruitment process may collect the candidate’s name, the position they are applying for, experience details, and preferred contact time. This allows further handling to begin with a complete set of essential information.
Tools#
The Tools section lets you specify which knowledge and data sources the AI Voice Agent can use during the conversation. Thanks to these, the Agent is not limited to the prepared scenario but can provide answers based on information shared by your company. The AI Agent independently decides whether and which tool to use, guided by the When to use (description for AI) field. This is a key part of the configuration – instead of describing what a function does, focus mainly on when the voice assistant should use it.
When configuring Tools, pay attention to the time needed to retrieve data – each query may cause a brief pause in the conversation for the caller. The more precise and faster the data source, the smoother the AI Voice Agent can conduct the conversation.
Within one utterance, the Agent can perform a maximum of 5 rounds of queries to Tools. Therefore, instead of creating one extensive tool handling many cases, it is better to prepare several simpler ones dedicated to specific uses.
You have three types of tools available:
- HTTP API
The HTTP API tool enables the AI Voice Agent to fetch current data from external systems directly during the call and use it in responses. Thus, the Agent can, for example, check customer data, appointment dates, loyalty point balances, complaint status, or other information provided via API.
Communication is one-way – the AI Voice Agent sends a request to the specified API and uses the received response during the conversation.
| Field | What to enter |
|---|---|
| Function Name | Tool identifier, e.g., get_order_status. Only lowercase letters, digits, and underscores. Must be unique within the Agent; names end_call and transfer_call are reserved. |
| When to use (description for AI) | Sentence telling the Agent when to use this tool, e.g., “Use when the caller asks about the order status.” This field determines if the Agent will call the tool at all. |
| Method | GET, POST, PUT, PATCH, or DELETE. |
| URL | Endpoint address, e.g., https://api.example.com/orders/{orderId}. Use curly braces to insert parameters. |
| Body | Request content, only for methods other than GET. May also contain parameters in braces. If you do not set your own Content-Type header, the request will be sent as application/json. |
| Parameters | Data the AI Agent should extract from the conversation and insert into the URL or request body. Each parameter has a Name, Type (text, number, integer, true/false), and Description (for AI), i.e., instructions on what exactly should go there, e.g., “Order number provided by the caller.” |
| Headers | Additional HTTP headers (name and value). Values can also include parameters in braces. |
| Authentication | None, API Key (header) with header name and secret, Bearer Token with secret only, or Basic with username and secret. |
| Timeout | Time the Agent waits for a response, in milliseconds. Default 3000, allowed range: 1–15000. |
Besides parameters filled by the AI Agent, a system variable {CALL.SRC_NUMBER} is available, representing the caller's phone number as digits only, with country prefix, without the “+” sign or spaces. This allows identification of the client without asking:
GET https://api.example.com/clients?phone={CALL.SRC_NUMBER}
If the AI Voice Agent cannot determine a parameter's value from the conversation, the default value will be inserted: empty text for text type, 0 for numbers, or false for boolean.
Describe the parameter so the AI Agent knows when to ask the caller for missing information. Alternatively, ensure the API can handle empty or default values.
After calling the HTTP API, the AI Voice Agent receives the HTTP response code and its content and can use this information during the conversation. Receiving an error code, e.g., 404 or 500, does not end the conversation. The Agent can respond appropriately, e.g., inform the caller that the needed data could not be found or retrieved.
Connection issues, such as exceeding the configured timeout, also do not terminate the conversation with the AI Voice Agent.
Sensitive data used for authentication, like tokens or passwords, are stored one-way. After saving, their values are no longer displayed. When editing the AI voice assistant, you will only see the message “secret set – leave empty to keep unchanged.”
Leaving the field empty will retain the existing secret. Entering a new value will replace it.
a) Technical Requirements
- The endpoint must be publicly accessible via HTTPS. The form also accepts
http://addresses, but such calls will be rejected during the conversation, so always providehttps://. - Addresses in private and local networks are blocked:
localhost,127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.64.0.0/10, link-local addresses, and IPv6 ULA (fc00::/7). APIs exposed only in internal networks will not work. - Redirects (3xx) are not followed; you must provide the final address.
- Response timeout: default 3000 ms, maximum 15000 ms. Connection timeout: 5 s.
- Response content is truncated to 2000 characters; longer content will not reach the AI Agent fully.
- The AI Voice Agent performs up to 5 rounds of calls per utterance.
- Parameter values are URL-encoded in the address and inserted as-is in the request body and headers.
b) How to design the endpoint for the Agent
To enable smooth data use during conversation, prepare the API endpoint properly. Keep in mind best practices:
- Return only necessary data in ready-to-use form – e.g., “Delivery on March 12” instead of raw timestamp and warehouse code. The AI Agent uses the received info during conversation, so the clearer the response, the easier to convey to the caller.
- Use a simple JSON structure – avoid deep nesting and large lists with many elements. API response can contain up to 2000 characters.
- Ensure fast response time – during waiting for data, pauses may appear in the conversation. Responses longer than about 1–2 seconds may be noticeable.
- Clearly indicate lack of data – instead of an empty list or general error, return a clear message, e.g., “Order not found.” This allows the voice assistant to react appropriately.
- Validate received data on the API side – parameters may come directly from caller information, so verify them before use.
- Do not place sensitive data in the URL – tokens, keys, and other secrets should be configured using authentication mechanisms in the Authentication section.
A well-prepared endpoint not only improves data exchange but also reduces wait time and makes conversations with the AI Voice Agent more natural.
- Knowledge Base
The Knowledge Base allows the AI Voice Agent to search a specified Thulium Knowledge Base directory and use found information during the conversation. Thus, the Agent can answer questions about offers, complaint rules, regulations, or processes applicable in your company.
The search is semantic – the AI Agent matches content based on the meaning of the question, not just the words used. The query to the Knowledge Base is formulated by the AI itself, in the conversation language.
| Field | What to enter |
|---|---|
| Knowledge base directory | Directory from which the AI Voice Agent should fetch information. |
| When to use (description for AI) | Specify when the AI Agent should use the Knowledge Base, e.g., “Use when the caller asks about products, returns, or store procedures.” |
| Number of articles for the model | Number of best-matched articles the voice assistant considers. Allowed range: 1 to 10, default 3. |
| Content scope | Specify the content scope passed to the Agent: Best fragment (faster response) – default option, or Full article (more complete, slower). |
The quality of AI Voice Agent’s responses greatly depends on how the Knowledge Base articles are prepared. Best are short, specific sections with clear headings dedicated to particular topics. Avoid lengthy articles combining many independent subjects.
- Order Status
The Order Status tool allows the AI Voice Agent to check customer order information in a store integrated with Thulium and use it directly during the conversation. For each status, you can prepare your own messages, so the Agent does not just provide the status but can explain what is currently happening with the order and what the client can expect next.
This way, questions like “Where is my order?” can be handled by the AI Voice Agent based on current data without involving a consultant.
The AI Voice Agent searches for the order based on the phone number from which the client is calling. Providing the order number is not required – the AI Agent automatically finds the last order linked to the given phone number.
If the calling number is not associated with any order, the AI Voice Agent informs the caller that the order could not be found.
| Field | What to enter |
|---|---|
| When to use (description for AI) | Define when the AI voice assistant should use this tool, e.g., “Use when the client asks about order or package status.” |
| E-commerce integration | Select the store integration the tool should use. |
| Order status mapping | Define pairs: Status in store – exactly as shown in Thulium panel, e.g., processing, and Message for caller – information the Agent should convey for that status. |
In the message, you can insert order data using the { } button next to the field or by typing the tag manually:
{{STORE_ORDER.ID}} {{STORE_ORDER.CREATED_AT}}
{{STORE_ORDER.STATUS}} {{STORE_ORDER.TOTAL_COSTS}}
{{STORE_ORDER.PRODUCTS_COSTS}} {{STORE_ORDER.SHIPPING_COSTS}}
{{STORE_ORDER.PAYMENT_METHOD}} {{STORE_ORDER.SHIPPING_ADDRESS}}
{{STORE_ORDER.PRODUCTS}} {{STORE_ORDER.CUSTOMER_NAME}}
{{STORE_ORDER.CUSTOMER_SURNAME}} {{STORE_ORDER.CUSTOMER_FULL_NAME}}
{{STORE_ORDER.DELIVERY_METHOD}} {{STORE_ORDER.DELIVERY_PACKAGE_NR}}
Example message: “The package for order number {{STORE_ORDER.ID}} has been shipped. The tracking number is {{STORE_ORDER.DELIVERY_PACKAGE_NR}}.”
Fill in the mapping for all statuses used in the store. If the AI Voice Agent recognizes a status without a defined message, it will inform the client that the order status is being verified and offer to connect them to a consultant.
The AI Voice Agent tries to deliver the prepared message as unchanged as possible but may adjust its content if required by context or the client's question.
The client is identified solely by the phone number from which the call is made. Since the phone number can be spoofed, do not include sensitive data or information that should not be disclosed based only on this identification, e.g., full delivery address, in order status messages.
Thanks to Tools, the AI Voice Agent can conduct conversations based on current knowledge and real data from your company, providing clients with information tailored to their specific case.
Actions#
The Actions section allows you to specify what the AI Voice Agent should do during or after the conversation. This way, customer service does not have to end with providing answers – the AI Agent can transfer the call further or automatically start the next step in Thulium.
You have two types of actions:
- Transfer
Transfer allows you to direct the ongoing call to a chosen call center queue, e.g., when the client requests contact with a consultant, the matter is too complex, or requires individual decision.
For each transfer, you can define conditions for activation and the message the AI Voice Agent will speak before connecting to the consultant.
You can configure multiple transfers corresponding to different situations and directing calls to appropriate queues.
Each transfer is configured with fields:
- Name – short, unique transfer identifier, e.g.,
advisor. - Queue – call center queue to which the call will be forwarded.
- When to transfer (description for AI) – specify situations when the AI Voice Agent should perform the transfer, e.g., “Questions about product recommendation or selection.” The more precise the description, the better the Agent recognizes when to transfer.
- Message on transfer – message spoken immediately before transferring the call, e.g., “Connecting you to a consultant, please wait.”
- Ticket
The Ticket action allows automatically registering a case after the conversation ends, including information collected by the AI Voice Agent and its transcription. This way, a consultant receives the context needed for further handling.
During configuration, you can specify queue, category, priority, and subject so that the created ticket immediately goes to the proper process.
Each variant is configured with fields:
- Key – unique variant identifier, e.g.,
unresolved. - Ticket queue – queue where the created ticket will be assigned.
- Category – category assigned to the ticket.
- Priority – priority assigned to the ticket.
- Subject – subject of the created ticket.
- When to create (description for AI) – specifies the situation when this variant should be used, e.g., “Client's problem was not resolved during the conversation.”
After the conversation, the system analyzes the course and selects the appropriate variant. A maximum of one ticket can be created per conversation. It contains information gathered by the AI Voice Agent, and the conversation transcription is added as a system comment.
The variant with an empty When to create (description for AI) field is treated as the default variant. It will be used if none of the other conditions are met. You can configure only one default variant.
Thanks to Actions, the AI Voice Agent not only conducts the conversation but also knows what should happen next – engaging a consultant when needed or independently forwarding the case for further processing.
After completing the AI Voice Agent configuration, click Save to keep your settings.
Testing the AI Voice Agent#
Before deploying the AI Voice Agent in a real call handling scenario, it's worth checking how it behaves during a conversation and whether the prepared configuration works as expected. You can do this using the AI Agent Tester.
You can test the Agent in several ways – by conducting a text conversation, speaking voice directly in the Tester, or providing a phone number which can be used in the test scenario.
Providing a phone number is especially useful when the Agent uses tools that require caller identification. It allows you to check, for example, if it correctly retrieves data via HTTP API, finds order status, and uses the obtained information during the conversation.
The Tester lets you verify not only the conversation flow but also the functioning of Persona, Tools, and Actions. If the result is not as expected, return to the Agent configuration, make the necessary changes, and test again.
Test several different conversation scenarios – not just the ideal one. Also check how the AI voice assistant reacts to unexpected questions, missing required information, or situations where it should transfer the call to a consultant.
Deploying the AI Voice Agent in IVR#
The configured AI Voice Agent is ready to operate – now you need to specify at which point in the call handling path it should take over the conversation with the customer. To do this, go to Administration → Telecommunications → IVR Tree and place the Agent in the appropriate spot in the scenario.
This lets you precisely decide which process the AI Voice Agent will handle and in which situations calls will be directed to it.
In the IVR tree branch where the call should be handled by the AI Voice Agent, select the Switch to Voicebot action, then:
- In the Mode field, choose Built-in.
- Select the previously created AI Voice Agent – names assigned during their configuration will appear in the list.
- The Record conversation option determines whether the part of the call handled by the AI Voice Agent will be recorded.
- In the After finishing conversation with bot jump to field, you can specify the IVR branch to which the call should be routed after the AI Voice Agent finishes.
If the After finishing conversation with bot jump to field is left empty, the call will be disconnected after the AI Voice Agent finishes.
And that's it! Your AI Voice Agent can start handling calls according to the prepared scenario. Now observe how it independently conducts conversations, fulfills assigned tasks, and supports your team in daily customer service.
You define the process, and the AI Voice Agent helps execute it with every call.
An AI Agent that has already handled some calls cannot be deleted because the call history must be preserved. Instead of deleting, set it as inactive:
Monitoring the AI Voice Agent#
Want to see how the AI Voice Agent performs in handling calls? Information about the number of conversations held and details of calls handled by the AI Voice Agent can be found in a dedicated report.
To access the report, select Reports → AI Assistant → AI Voice Agent:
The report allows you to monitor the usage of AI Voice Agents and analyze the conversations they conducted. This way, you can continuously check the scale of service performed by AI and review details of individual calls.
By default, the report shows data from the current day. To analyze conversations from another period, click the Date filter and select the desired time range.
The report can display data for a maximum period of 31 days at once. To analyze a longer period, choose subsequent date ranges not exceeding this limit.
At the top of the report, tiles show key indicators related to calls handled by the AI Voice Agent during the selected period:
- Number of incoming calls – calls directed to the AI Voice Agent.
- Number of transferred calls – calls the AI Voice Agent forwarded to a call center queue for further handling.
- Average conversation time – average duration of conversations led by the AI Voice Agent.
- Calls per hour – average number of calls handled by the AI Voice Agent per hour.
Each tile also shows the trend compared to the equivalent previous period, allowing quick assessment of changes in these metrics.
The tiles help quickly evaluate the scale of AI Voice Agent usage and how it handles the directed traffic.
Below the tiles is a results table containing detailed information about individual conversations handled by the AI Voice Agent:
- Date – date and time of the conversation.
- AI Voice Assistant – name of the AI Voice Agent who conducted the call.
- Customer number – phone number of the client who spoke with the AI Voice Agent.
- Call duration – duration of the conversation with the AI Voice Agent.
- Transferred to – information about the call center queue to which the call was transferred.
- Disconnected by – information about how the conversation with the AI Voice Agent ended – by the AI Agent, the client, or due to transfer.
The table allows moving from general statistics to analyzing individual calls and checking how the AI Voice Agent handled a particular call.
To view details of a selected call, click the icon.
Observe, analyze, and improve your service with AI! The AI Voice Agent report lets you track Agents' work and analyze handled calls, giving you a fuller picture of automation performance.
The AI Voice Agent is not just a way to answer calls – it's an opportunity to automate entire service processes, from the first “Good day” to effective resolution or case forwarding.