10.1 Overview

AI Voice Agents conduct automated telephone conversations using a configured artificial-intelligence model, synthesized voice, behavioral instructions, and optional business Knowledge Base.

An AI Voice Agent can be configured to:

Answer inbound telephone calls
Place individual outbound Calls
Conduct outbound Campaign conversations
Answer business questions
Qualify prospective customers
Collect survey responses
Transfer callers to a human
Record Calls
Store conversation transcripts
Track duration, turns, and estimated cost

The normal AI Voice Agent workflow is:

Create Knowledge Base
Create AI Voice Agent
Choose Agent Type, model, and voice
Write behavioral instructions
Configure greeting and transfer behavior
Save Agent
Assign Phone Number through Edit
Configure and test Twilio Webhooks
Make an internal test Call
Activate for inbound or outbound use
Monitor Live Calls
Review Call History, transcript, recording, and cost

The current application includes browser pages and API routes for Agents, Knowledge Bases, test Calls, live monitoring, Call transcripts, recordings, exports, Webhook configuration, archiving, and restoration.

Human Agents Versus AI Voice Agents

10.2 Human Agent

A human Agent is a User account operated by a person.

Human Agents can use:

Browser Softphone
Assigned Phone Numbers
Campaign Call Queue
Contacts
Call History

10.3 AI Voice Agent

An AI Voice Agent is an automated conversation configuration.

It contains:

Name
Type
Phone Number
AI model
Voice
System Prompt
First Message
Goodbye Message
Knowledge Base
Call settings
Recording preference
Transfer settings
Activity status

10.4 Different Navigation Sections

Human Agents are managed under:

Team
→ Agents

AI Voice Agents are managed under:

Conversational AI
→ AI Agents

Do not confuse an AI Voice Agent with a human Agent User account.

AI Voice Agent Architecture

10.5 Main Components

The current AI Voice Agent Call path combines:

Twilio telephone connection
Twilio speech gathering
Twilio text-to-speech Voice
OpenRouter language model
AIUNIFY conversation state
Optional Knowledge Base
Call and conversation database records
Recording callback

10.6 Speech Recognition

The reviewed TwiML conversation handler uses Twilio’s:

<Gather input="speech">

with:

Speech model:
phone_call

Language:
en-US

Enhanced recognition:
Enabled

10.7 Deepgram

The application includes a Deepgram service and an AI-agent test endpoint that can check Deepgram configuration.

However, the current standard TwiML AI conversation route uses Twilio speech gathering rather than Deepgram streaming for the live speech-recognition step.

A successful Deepgram test does not by itself prove that the current Twilio Gather conversation path is configured correctly.

10.8 AI Response Generation

Caller speech is sent to an OpenRouter-supported model.

The response is:

Sanitized for speech
Limited in length
Stored as a conversation turn
Spoken through the selected Twilio Voice

10.9 Recent Conversation Memory

The AI request includes approximately the latest:

6 nonsystem conversation turns

This normally represents about:

3 caller turns
+
3 AI turns

Older conversation turns remain stored but are not all sent back to the AI model for every response.

10.10 Base Voice Instruction

The application always prepends a shared instruction file:

public/voice-ai-base-instruction.md

before the Agent’s custom System Prompt.

The final behavioral context is assembled approximately as:

Platform Voice AI base instructions
Knowledge Base context
Agent System Prompt
Contact and Campaign context
Recent conversation history

Opening AI Voice Agents

10.11 AI Agent List

From the Sidebar:

Conversational AI
→ AI Agents

The page address is:

/ai-agents

10.12 Related AI Pages

The section also includes:

/ai-agents/create
/ai-agents/[Agent ID]
/ai-agents/[Agent ID]/edit
/ai-agents/live
/ai-agents/calls

The installed API provides Agent creation, updating, testing, archiving, restoration, Webhook configuration, Calls, transcripts, recordings, and exports.

Access Requirements

10.13 Business KYC

The normal browser pages for:

AI Voice Agents
AI Agent Live Calls
AI Agent Call History
Knowledge Bases

require:

Approved Business KYC

when KYC enforcement is enabled.

Basic KYC alone is not sufficient for these browser pages.

10.14 API KYC Inconsistency

The corresponding AI Agent and Knowledge Base API routes are protected by authenticated API access, but they do not apply the same Business KYC middleware used by the browser pages.

This is a current access-control inconsistency.

The API should enforce the same tier, role, permission, and ownership requirements as the browser interface.

10.15 Customer Ownership

The normal AI Agent API scopes Agents to:

ai_agent.user_id = signed-in User ID

A Customer normally sees only its own AI Voice Agents.

10.16 Agent User Limitation

A human Agent User does not automatically inherit the parent Customer’s AI Voice Agents through the primary AI Agent API.

AI Voice Agents are directly owned by the User account that created them.

AI Agent List

10.17 Agent Cards

Each AI Agent Card can display:

Agent Name
Active or Inactive state
Description
Agent Type
AI model
Voice
Assigned Phone Number
Total Calls
Success Rate
Total Cost
Average Duration

10.18 Search

The page provides client-side Search across fields such as:

Name
Description
Type
Model
Phone Number

10.19 Search Scope Limitation

The Agent API returns approximately:

15 Agents per page

The current page does not render pagination controls.

Search therefore applies only to the first loaded set of approximately fifteen Agents.

An Agent beyond the first page can be absent from both the visible list and Search results.

10.20 Agent Statistics Requests

The index loads additional statistics for each visible Agent.

This can produce one extra API request per Agent and make the page slower as the visible Agent count increases.

AI Agent Types

10.21 Inbound

An Inbound Agent is intended to:

Answer Calls made to its assigned Phone Number

The Agent Details page does not offer a normal outbound Make Call action for an Inbound-only Agent.

10.22 Outbound

An Outbound Agent is intended to:

Place individual outbound test or production Calls
Participate in AI-driven Campaign Calls

It should not be treated as an inbound answering Agent unless its Type is changed.

10.23 Both

A Both Agent supports:

Inbound Calls
+
Outbound Calls

10.24 Type Does Not Configure Routing Alone

Selecting Inbound or Both does not automatically make a Phone Number ring the Agent.

The Agent also requires:

Assigned Phone Number
Active status
Correct Twilio Voice Webhook
Working OpenRouter configuration

Creating an AI Voice Agent

10.25 Opening Create

Select:

Create AI Agent

or open:

/ai-agents/create

10.26 Create Form Sections

The form contains:

Basic Information
AI Configuration
Call Behavior
Knowledge Base
Agent Settings
Transfer Settings

10.27 Default Create Settings

A newly opened form starts approximately with:

Type:
Inbound

Active:
Yes

Recording:
Enabled

Transfer:
Disabled

Model:
First configured OpenRouter model

Voice:
Joanna

Temperature:
0.7

Maximum Call Duration:
600 seconds

Silence Timeout:
10 seconds

Response Timeout:
10 seconds

10.28 Phone Number Is Not on Create

The current Create form does not assign a Phone Number.

The required sequence is:

Create Agent
Open Edit
Assign Phone Number
Save
Configure Webhooks

Basic Information

10.29 Agent Name

Agent Name is required.

Maximum length:

255 characters

Examples:

Customer Support Assistant
New Lead Qualification Agent
Appointment Confirmation Agent
After-Hours Receptionist

10.30 Description

Description is optional.

Use it to explain:

Business purpose
Supported audience
Department
Expected Call type
Escalation responsibility

10.31 Agent Type

Select:

Inbound
Outbound
Both

according to the approved operating purpose.

Prompt Templates

10.32 Visible Templates

The Create form offers prompt starters for uses such as:

Inbound Support
Inbound Sales
Outbound Survey
Outbound Lead Qualification

10.33 Template Purpose

Selecting a template fills the System Prompt with a starting instruction.

It does not configure:

Phone Number
Knowledge Base
Transfer Number
Credits
Recording consent
Campaign Contacts
Webhook

10.34 Template Source Difference

The backend configuration exposes a separate Template API with Customer Support, Sales Agent, Survey Bot, and Lead Qualification templates.

The current Create page instead uses its own hard-coded prompt starters.

The text and branding in the visible templates can therefore differ from the templates returned by:

GET /api/v1/ai-agents/templates

System Prompt

10.35 System Prompt Requirement

The System Prompt is required.

It defines how the Agent should behave.

10.36 Recommended Prompt Structure

A useful System Prompt should define:

Identity
Purpose
Audience
Allowed topics
Required questions
Response length
Disclosure
Escalation rules
Prohibited actions
Call-ending rules

10.37 Example Structure

You are the AIUNIFY customer-support assistant.

Answer questions about approved services using the Knowledge Base.
Keep each response under three sentences.
Do not invent prices, policies, or account information.
Ask one question at a time.
When the caller requests a person, transfer the Call.
When you cannot verify an answer, explain that a team member must assist.

10.38 Platform Instructions Take Priority in Context

The Agent’s System Prompt is not the only instruction.

The platform’s shared Voice AI instruction file is prepended before it.

A System Prompt should not attempt to override security, compliance, or platform-level constraints.

10.39 Contact and Campaign Context

When a manually initiated AI Call is correctly linked to a Contact or Campaign, the AI can receive context such as:

Contact Name
Company
Email — marked not to read aloud unless asked
Prior Contact Notes
Campaign Name
Campaign Description

10.40 Manual Call Context Limitation

The current Make Call dialog submits only a destination Phone Number.

It does not provide a Contact or Campaign selector.

Manually initiated AI Calls normally lack the Contact and Campaign context described above.

First Message

10.41 Purpose

The First Message is the greeting spoken when the AI Call begins.

Maximum length:

500 characters

10.42 Inbound Example

Thank you for calling AIUNIFY. I am the virtual support assistant. How may I help you today?

10.43 Outbound Example

Hello {first_name}. This is the AIUNIFY virtual assistant calling about your recent request. Is now a good time to speak?

10.44 Campaign Variables

AI Agent Campaign greetings support single-brace placeholders:

{first_name}
{last_name}
{company}

This differs from static Campaign TTS variables:

{{first_name}}
{{last_name}}
{{company}}

10.45 Normal Inbound Greeting

A normal inbound AI Call does not perform the same Campaign Contact variable replacement.

Use a general inbound greeting unless the incoming Call has an independently linked Contact context.

10.46 Default Greeting

When First Message is blank, the system uses a fallback based on the Agent Type.

For example:

Hello! I'm an AI assistant. How can I help you today?

Goodbye Message

10.47 Purpose

The Goodbye Message is used when caller language indicates that the conversation should end.

Maximum length:

500 characters

10.48 End Keywords

The current conversation engine can end when caller speech contains phrases such as:

goodbye
bye
end call
hang up
stop
no thanks
not interested

10.49 Goodbye Example

Thank you for speaking with AIUNIFY. A team member will follow up when required. Have a great day.

10.50 Hard-Coded Voice Limitation

Normal conversation responses use the selected Agent Voice.

The current transfer and goodbye TwiML functions use:

Polly.Joanna-Generative

instead of the Agent’s selected Voice.

The end of a Call can therefore suddenly switch to a different Voice.

AI Models

10.51 Model Selection

The model controls how the Agent interprets caller speech and generates responses.

The current configured model list is returned by:

GET /api/v1/ai-agents/models

10.52 Current Configured Models

The current source configuration includes:

Polaris Alpha
GPT OSS 20B
DeepSeek Chat v3.1
DeepSeek Chat v3-0324
GLM 4.5 Air
Kimi K2

These entries are currently labeled Free in the application configuration.

10.53 Configured Speed Descriptions

The current build describes the options approximately as:

Polaris Alpha:
Ultra Fast

GPT OSS 20B:
Very Fast

DeepSeek models:
Fast

GLM 4.5 Air:
Fast

Kimi K2:
Fast

These are application labels rather than guaranteed response times.

10.54 Model Availability

External model availability can change.

The conversation engine attempts:

Preferred Agent model
Configured fallback models

when the preferred model fails.

10.55 Model Fallback

A Call can begin using the selected model and later receive a response from a fallback model after a provider failure.

The interface does not prominently announce this model change to the caller.

10.56 Maximum Tokens

The Maximum Tokens field limits AI response generation.

The Create and Edit interface allows approximately:

50 through 4,000

However, the live conversation service applies an additional voice-response cap and uses no more than approximately:

250 generated tokens

per response.

Entering a value above 250 does not cause the current voice path to produce a response beyond that internal cap.

10.57 Response Character Cap

After generation, spoken AI content is limited by the configured character cap, currently approximately:

800 characters

The system attempts to stop at a sentence or word boundary.

10.58 Temperature

Temperature controls response variation.

Accepted range:

0 through 2

General interpretation:

Lower:
More consistent and restrained

Higher:
More varied and less predictable

For business telephone operations, a conservative value is usually safer.

Voices

10.59 Voice Selection

The Voice determines how normal AI responses are synthesized through Twilio <Say>.

The current Voice API returns Amazon Polly and Google Chirp3-HD options.

10.60 Joanna

Provider:
Amazon Polly

Gender:
Female

Description:
Warm and natural

10.61 Matthew

Provider:
Amazon Polly

Gender:
Male

Description:
Confident and clear

10.62 Ruth

Provider:
Amazon Polly

Gender:
Female

Description:
Professional and composed

10.63 Stephen

Provider:
Amazon Polly

Gender:
Male

Description:
Authoritative and trustworthy

10.64 Aoede

Provider:
Google Chirp3-HD

Gender:
Female

Description:
Bright and expressive

10.65 Charon

Provider:
Google Chirp3-HD

Gender:
Male

Description:
Deep and composed

10.66 Kore

Provider:
Google Chirp3-HD

Gender:
Female

Description:
Warm and friendly

10.67 Fenrir

Provider:
Google Chirp3-HD

Gender:
Male

Description:
Energetic and dynamic

10.68 Puck

Provider:
Google Chirp3-HD

Gender:
Male

Description:
Playful and engaging

10.69 Leda

Provider:
Google Chirp3-HD

Gender:
Female

Description:
Calm and soothing

10.70 Voice Engine Label Difference

The configuration describes the Polly choices as Generative.

The current Voice mapper normally sends the short names to Twilio’s faster:

Polly Neural

variants.

Explicit -generative values are supported internally but are not the standard choices displayed by the form.

The Voice description and actual Twilio Voice engine can therefore differ.

10.71 Unsupported Voice Fallback

When a stored Voice cannot be mapped, the application falls back to:

Polly.Joanna-Neural

10.72 Voice Testing

The current Create form does not provide a built-in Voice preview.

Use one internal test Call before activating the Agent for production.

Knowledge Base Options

10.73 Saved Knowledge Base

The Agent can select an existing Knowledge Base record.

10.74 Inline Knowledge Base

When no saved Knowledge Base is selected, the form allows custom Knowledge Base text directly on the Agent.

10.75 Effective Knowledge Base Priority

The Agent uses:

Selected saved Knowledge Base content

when that relationship exists and contains text.

Otherwise, it falls back to:

Inline Agent Knowledge Base

10.76 Switching to a Saved Knowledge Base

Selecting a saved Knowledge Base clears the inline Knowledge Base from the current form state.

Review the Agent carefully before saving.

10.77 Knowledge Base Prompt Limit

A saved Knowledge Base can store up to approximately:

500,000 characters

However, the conversation engine currently inserts only approximately:

4,000 characters

into the AI System Prompt.

The remaining saved content is not available to that conversation turn through the current implementation. A unit test in the source confirms the prompt cap.

10.78 No Semantic Retrieval

The reviewed AI Agent Knowledge Base path does not show:

Vector indexing
Semantic retrieval
Chunk selection
Document ranking
Citation generation

It places the beginning of the Knowledge Base directly into the prompt up to the configured character limit.

Place the most important information first.

10.79 Recommended Knowledge Base Order

Use this sequence:

Core business identity
Approved services
Primary policies
Frequently asked questions
Prices or pricing rules
Escalation instructions
Restricted statements
Additional details

Knowledge Base Management

10.80 Opening Knowledge Bases

From the Sidebar:

Conversational AI
→ Knowledge Base

The page address is:

/knowledge-bases

10.81 Knowledge Base Controls

The page provides:

Search
Create Knowledge Base
Edit
Delete

10.82 Knowledge Base List Size

The current page requests up to approximately:

100 Knowledge Bases

and does not provide pagination controls.

Records beyond the loaded set are not normally accessible through the visible page.

10.83 Client-Side Search

Search applies to the loaded Knowledge Base names and content excerpts.

It does not search records that were not loaded from later API pages.

Critical Knowledge Base Ownership Limitation

10.84 No Customer Owner Field

The Knowledge Base model currently stores:

Name
Content

It does not store:

user_id
customer_id
workspace_id

10.85 Global Knowledge Bases

The Knowledge Base API returns, edits, and deletes Knowledge Bases without Customer ownership filtering.

Knowledge Bases are effectively shared global records across authenticated accounts in the current database design.

10.86 Confidentiality Risk

Until tenant ownership is added, do not place confidential Customer-specific information in a saved Knowledge Base.

Examples include:

Customer lists
Private account details
Internal pricing exceptions
Personal data
Credentials
Contracts
Unpublished business procedures

This multitenant isolation defect should be corrected before production use.

Creating a Knowledge Base

10.87 Opening Create

Select:

Create Knowledge Base

or open:

/knowledge-bases/create

10.88 Input Methods

The current form supports:

Plain Text
File Upload
URL Import

10.89 Name

Name is required.

Maximum length:

255 characters

Use a descriptive Name such as:

Customer Support Policies — July 2026

10.90 Plain Text

Enter approved information directly into the Content field.

The stored maximum is approximately:

500,000 characters

10.91 File Upload

Supported file types are:

TXT
MD
CSV
HTML

Maximum file size:

10 MB

10.92 Stored File Content

The server reads the file as text.

It does not preserve:

Original filename
Document formatting
Tables as structured data
Images
Document sections
Source metadata

Only flattened text is stored.

10.93 File Preview Editing Defect

The browser displays the selected file’s text for preview and allows the user to edit that preview.

When the form is submitted in File mode, the original file is uploaded and read again by the server.

Changes made only to the preview field are not applied.

To edit file content before saving:

Edit the original file
or
Switch to Plain Text mode and paste the corrected content

10.94 URL Import

Enter an http:// or https:// address and select Fetch.

The server:

Downloads the page
Removes script and style blocks
Removes HTML tags
Decodes entities
Collapses whitespace
Returns extracted text

10.95 URL Timeout

The server permits approximately:

15 seconds

for the URL request.

10.96 URL Content Limitation

A webpage can contain navigation, cookie text, footer information, and unrelated content.

Review and clean the extracted text before saving.

10.97 URL Security Limitation

The URL-fetch endpoint accepts general HTTP and HTTPS addresses and does not show restrictions against private network or internal service addresses.

Untrusted users should not be allowed to submit arbitrary URLs.

The endpoint should be protected with:

Public-address validation
Private-IP blocking
Redirect validation
Hostname allowlisting where appropriate
Response-size limits
Content-type checks

10.98 Empty Content

The backend permits a Knowledge Base with a Name and no Content.

Such a record does not provide useful context to the Agent.

10.99 Duplicate Names

Knowledge Base Names are not required to be unique.

Use clear versioning and dates to avoid selecting the wrong record.

Editing a Knowledge Base

10.100 Opening Edit

Select Edit on a Knowledge Base Card.

The address is:

/knowledge-bases/[Knowledge Base ID]/edit

10.101 Edit Modes

The Edit form offers the same:

Plain Text
File
URL

input methods.

10.102 File Edit Defect

The same File preview issue applies during Edit.

Changes typed into the preview are ignored when the original file is submitted.

10.103 No Version History

The current Knowledge Base system does not store:

Previous versions
Editor
Change notes
Source history
Rollback copy

Export or copy critical content before replacing it.

10.104 Changes Affect Assigned Agents

An Agent reads the current saved Knowledge Base content during conversation prompt assembly.

Editing the Knowledge Base can affect every Agent using that record.

10.105 Prompt Cache

The assembled Agent System Prompt is cached for approximately:

10 minutes

The cache key includes the Agent’s update timestamp and the shared base-instruction file timestamp.

It does not clearly include the Knowledge Base’s update timestamp.

Changing a saved Knowledge Base without updating the Agent can therefore leave previous Knowledge Base content in the cached Agent prompt until the cache expires.

Deleting a Knowledge Base

10.106 Delete Confirmation

The page warns that deletion can affect Agents using the Knowledge Base.

10.107 Effect on Agents

The database relationship is configured so that deleting a Knowledge Base can set the Agent’s:

knowledge_base_id = null

10.108 Inline Fallback

After deletion, the Agent can fall back to its inline Knowledge Base when one exists.

Otherwise, it operates without Knowledge Base context.

10.109 No Usage List

The current Knowledge Base page does not display:

Agents using this Knowledge Base
Number of assigned Agents
Last used date
Campaigns affected

Confirm assignments manually before deleting.

Call Settings

10.110 Active

When Active is enabled, the Agent can be selected for normal AI calling.

When inactive:

Inbound routing should not select it
Outbound Make Call is disabled
Campaign AI processing can reject it

10.111 Recording

Enable Recording instructs eligible outbound AI Calls to request provider recording.

The Agent Call record can later receive:

Recording SID
Recording URL
Recording Duration

through the recording callback.

10.112 Recording Consent

The technical option does not establish legal authority.

Confirm:

Required disclosure
Required consent
Permitted purpose
Retention period
Authorized access
Deletion policy

10.113 Maximum Call Duration

Accepted range:

60 through 3,600 seconds

The Call State Manager contains a method capable of checking this limit.

The reviewed TwiML conversation handler does not call that method during its normal turn-processing path.

Maximum Call Duration is therefore not confirmed as enforced for current standard AI Calls.

10.114 Maximum Conversation Turns

The configuration defines approximately:

50 turns

The same unused Call-limit helper checks this value.

The current standard TwiML handler does not visibly invoke that helper.

10.115 Silence Timeout

Accepted range:

5 through 60 seconds

The Twilio Gather timeout uses this value.

10.116 First Silence

After the first period without speech, the Agent says a prompt similar to:

Are you still there? I didn't catch that — please go ahead.

10.117 Second Silence

After the second consecutive silence, the system ends the Call with a goodbye message.

10.118 Response Timeout

Accepted range:

5 through 30 seconds

This value is used primarily as the OpenRouter HTTP response timeout, with the current service further constraining the primary-model request to a narrow range.

It is not the caller’s speech timeout; that is controlled separately by Silence Timeout.

Transfer to Human

10.119 Enabling Transfer

Turn on:

Enable Call Transfer

Then provide:

Transfer Number
Trigger Keywords

10.120 Transfer Number

Use complete E.164 format:

+13135550198

10.121 Trigger Keywords

Examples:

human
representative
manager
speak to someone
transfer me

10.122 Keyword Matching

The Agent checks whether caller speech contains any saved Trigger Keyword.

Matching is:

Case-insensitive
Substring-based

A keyword such as agent could match a larger phrase containing that text.

Use specific phrases to reduce false transfers.

10.123 Transfer Confirmation

When a Trigger Keyword matches, the Agent says a configured transfer message and dials the Transfer Number.

10.124 Transfer Timeout

The transfer Dial allows approximately:

30 seconds

for the human destination to answer.

10.125 Failed Transfer

When the human destination does not answer, the caller hears a fallback message and the Call ends.

10.126 Caller ID

The Agent’s assigned Phone Number is passed as the transfer Caller ID when available.

The number must be accepted by the connected Twilio account.

Transfer Keyword Edit Defect

10.127 Create Field

The Create form correctly reads and writes:

trigger_keywords

10.128 Edit Field

The Edit and Agent Details interfaces use:

transfer_keywords

instead.

The database and API use:

trigger_keywords

10.129 Result

After creation:

Stored Trigger Keywords can continue working

but the Edit page can:

Fail to display them
Fail to update them
Submit an ignored transfer_keywords field

10.130 Safe Transfer Procedure

Configure Trigger Keywords during initial Agent creation.

Afterward:

  1. Test every keyword.
  2. Do not assume Edit changed the keywords.
  3. Verify the stored trigger_keywords through an approved administrative process.
  4. Correct the Edit interface before production transfer use.

Saving the Agent

10.131 Create Agent

After reviewing all fields, select:

Create AI Agent

10.132 Creation Result

On success, the Agent is created under the signed-in User ID and the interface returns to the AI Agent section.

10.133 Active-by-Default Risk

The Create form defaults to Active.

The Agent still lacks a Phone Number on initial creation, but its active state can make it eligible for certain internal selections.

A safer launch process is:

Create as Inactive
Configure and test
Activate only after successful verification

Editing an AI Voice Agent

10.134 Opening Edit

Open the Agent Details page and select:

Edit

The address is:

/ai-agents/[Agent ID]/edit

10.135 Edit Capabilities

The Edit page can change:

Name
Description
Type
Phone Number
System Prompt
First Message
Goodbye Message
Knowledge Base
Model
Voice
Maximum Tokens
Temperature
Active state
Recording
Maximum Duration
Silence Timeout
Response Timeout
Transfer setting
Transfer Number

10.136 Phone Number Assignment

The Phone Number selector exists on Edit rather than Create.

Select the number intended to receive or place AI Agent Calls.

10.137 Number Reassignment

When the same Phone Number is saved on another AI Agent, the update process removes that number from the previous AI Agent.

The operation can silently reassign the number rather than returning a duplicate-number error.

10.138 Update Uniqueness Difference

Create validates the AI Agent Phone Number as unique.

Update does not use the same uniqueness validation.

Instead, it programmatically clears the number from other Agents.

10.139 Number Selector Scope

The Edit page loads the general all-numbers endpoint.

The source does not clearly show that the selector limits every displayed number to:

Current Customer
Available assignment state
Correct provider
AI-compatible configuration

Select only a Phone Number confirmed to belong to the current Customer.

10.140 Saving Additional Response Fields

The Edit page submits the loaded Agent object rather than only a tightly constructed set of editable fields.

The backend validator ignores unsupported properties, but the request can include response-only or relationship data.

10.141 Zero-Value Display Limitation

Some Edit defaults use JavaScript ||.

A valid numeric value of zero can be replaced visually by a default.

For example:

Temperature stored as 0
can display as
0.7

Saving without noticing can overwrite the intended zero value.

Phone Number and Twilio Webhooks

10.142 Inbound Routing Requirement

For an inbound Call to reach the AI Agent:

Phone Number must be assigned to Agent
Agent must be Active
Number must exist in connected Twilio account
Voice URL must point to AI Agent TwiML route
Public application URL must use HTTPS

10.143 Automatic Configuration on Edit

After saving an Agent with a Phone Number, the backend attempts to configure that number’s Twilio Webhooks automatically.

10.144 Configure Webhooks Action

The Agent Configuration Test dialog can also provide:

Configure Webhooks

This operation sets the Twilio number’s Voice URL to the AI Agent Call endpoint and adds a Call Status callback.

10.145 Global Twilio Account

The configuration action uses the platform’s global active Twilio configuration.

It does not configure a number belonging only to an unrelated Customer-owned Twilio credential.

10.146 Number Not Found

When the assigned Phone Number does not exist in the connected Twilio account, Webhook configuration fails.

10.147 Stored Webhook Flag

Successful configuration stores:

twilio_auto_configured = true

along with the provider Phone Number SID.

10.148 Stale Webhook Flag

Someone can later change the Webhook directly in Twilio.

The stored AIUNIFY flag can remain true even when the actual provider configuration no longer matches.

Testing Agent Configuration

10.149 Opening Test Configuration

From Agent Details, select:

Test Config

Then select:

Run Test

10.150 Test Categories

The dialog checks areas such as:

AI Service
Phone System
Webhook and Call Routing
Overall readiness

10.151 AI Service Check

The configuration test checks whether the OpenRouter API key is configured.

It does not necessarily generate a full live conversation during this test.

10.152 Twilio Connection

The test attempts to connect to the active Twilio account.

10.153 Phone Number Check

When an Agent has a Phone Number, the test checks whether that number exists in the Twilio account.

10.154 Webhook Check Limitation

The Webhook accessibility test checks whether the application URL begins with:

https://

It does not perform a real external request to confirm that Twilio can reach the endpoint.

A green HTTPS result does not prove:

DNS resolves correctly
SSL certificate is trusted
Firewall allows Twilio
Route returns TwiML
Proxy forwards the request

10.155 Separate Service Test

The API also provides:

POST /api/v1/ai-agents/[Agent ID]/test

This test checks:

Deepgram
OpenRouter

It does not test Twilio Webhooks.

The current Configuration Test dialog uses the broader configuration endpoint rather than exposing this separate test directly.

10.156 Complete Test Requirement

A complete production test requires:

Configuration Test
+
Actual inbound test Call
+
Actual outbound test Call where applicable
+
Transcript review
+
Recording review
+
Transfer test

Agent Details Page

10.157 Opening an Agent

Select an Agent Card.

The address is:

/ai-agents/[Agent ID]

10.158 Header Actions

Depending on Agent Type and configuration, the page can display:

Make Call
Test Config
Activate or Deactivate
Edit
Delete
Archive

10.159 Make Call Conditions

Make Call is displayed when:

Agent Type is Outbound or Both
and
Phone Number is assigned

It is disabled while the Agent is Inactive.

10.160 Statistics

The Agent Details page displays:

Total Calls
Success Rate
Total Cost
Average Duration

10.161 Success Rate

The Agent’s Success Rate is:

Completed AI Agent Calls
÷
Total AI Agent Calls
×
100

It does not independently confirm a human conversation or successful business outcome.

10.162 Average Duration

Average Duration is based on completed AI Agent Calls.

10.163 Total Cost

Total Cost is the sum of the AI Agent Calls’ stored:

cost_estimate

value.

It is not automatically the same as the Customer’s Credit statement or provider invoice.

Agent Details Tabs

10.164 Details Tab

The Details tab can display:

Agent Type
Model
Voice
Phone Number
Transfer Number
System Prompt

10.165 Missing Details

The current tab does not clearly display all saved configuration, including:

First Message
Goodbye Message
Knowledge Base content
Knowledge Base assignment
Recording setting
Maximum Call Duration
Silence Timeout
Response Timeout
Webhook status
Transfer keyword list under the correct field

Open Edit to review those values.

10.166 Recent Calls Tab

The page loads approximately:

20 recent Calls

for the Agent.

It can display:

Date
Direction
Status
Duration
Cost

10.167 Configuration Tab

The Configuration tab displays items such as:

Maximum Tokens
Temperature
Transfer Keywords

Because the page expects transfer_keywords instead of trigger_keywords, the displayed keyword list can be empty or incorrect.

Making an Outbound AI Call

10.168 Opening Make Call

From Agent Details, select:

Make Call

10.169 Destination Number

Enter a Phone Number including country code.

Recommended format:

+13135550198

10.170 Backend Number Validation Limitation

The backend requires a string but does not apply strict E.164 validation to the AI Call destination.

An improperly formatted number can reach Twilio and fail there.

10.171 No Contact Selector

The current dialog does not provide:

Contact selection
Campaign selection
Campaign Contact selection
Purpose field
Call Notes

10.172 Call Record Context

A manually initiated Call normally stores:

AI Agent
Direction = outbound
From Number
To Number
Provider Call SID
Status

It normally lacks a linked Contact or Campaign because the dialog does not submit those IDs.

10.173 Active Agent Requirement

An inactive Agent cannot place the Call.

10.174 Inbound-Only Agent

The backend rejects an outbound Call when the Agent Type is:

inbound

10.175 Phone Number Requirement

The source does not show a dedicated preflight error for an Agent with no Phone Number before the Twilio request.

The interface hides Make Call when no number is assigned, but direct API use can still reach provider failure.

10.176 Twilio Configuration

The Call uses the active global Twilio configuration.

10.177 Outbound Timeout

The initial provider Call permits approximately:

30 seconds

for the destination to answer.

10.178 Recording

When Agent Recording is enabled, the outbound Call requests recording and provides a Recording callback.

10.179 Credits Limitation

The AI Agent Call initiation controller does not show:

Credit affordability check
Credit reservation
AIUNIFY Credit deduction

for the manually initiated AI Call.

Provider and LLM costs can still be incurred.

This billing path should be reconciled with the platform’s Credit system before production use.

Inbound AI Calls

10.180 Number Matching

For an inbound Call, the TwiML handler searches for an Active AI Agent using the called Phone Number.

It accepts:

Exact Phone Number match
or
Last ten digits match

10.181 Last-Ten-Digit Risk

Two international numbers can share the same final ten digits while having different country codes.

The current matching query selects the first matching Active Agent without an ownership filter.

This can route a Call to the wrong Agent in a collision scenario.

Exact normalized E.164 matching should be used instead.

10.182 No Active Agent

When no Active Agent is found, the caller hears a message indicating that the number is not configured, and the Call ends.

10.183 New Inbound Call Record

A new inbound AI Call is created with values such as:

Status:
in-progress

Started At:
Current server time

Answered At:
Current server time

Turn Count:
0

Conversation Behavior

10.184 Initial Greeting

The first response uses:

Agent First Message
or
Default greeting

10.185 Caller Speech

The caller’s recognized speech is stored as a User conversation turn.

10.186 AI Response

The AI response is stored as an Assistant conversation turn.

10.187 Turn Count

The Call tracks the number of conversation turns.

The current code increments Turn Count in more than one place during speech processing, so the displayed number should be treated as an approximate interaction count rather than a guaranteed count of caller statements.

10.188 Speech Barge-In

The <Say> instruction is placed inside Twilio <Gather>.

This allows the caller to begin speaking while the prompt is playing and can stop the prompt.

10.189 AI Response Sanitization

Before speech playback, the service removes or reduces content such as:

Markdown symbols
Emoji
Bracketed annotations
Stage directions
Meta-commentary
Repeated whitespace

10.190 OpenRouter Failure Handling

After one failed model response, the Agent asks the caller to repeat.

After repeated failures:

Transfer to human when enabled
or
End the Call gracefully

10.191 Model Fallback

Before treating a response as failed, the engine can attempt other configured models.

10.192 Conversation End

When the caller says an end phrase, the system uses the Agent’s configured Goodbye Message where available and ends the Call.

Language Limitation

10.193 Hard-Coded Speech Language

The current Twilio speech Gather uses:

language="en-US"

10.194 No Agent Language Field

The AI Agent Create and Edit forms do not provide a language setting for speech recognition.

10.195 Non-English Calls

A System Prompt can instruct the AI model to respond in another language, but caller speech is still recognized through the current en-US Twilio setting.

Non-English recognition and pronunciation are therefore not dependable through this standard route.

AI Agent Campaign Calls

10.196 Campaign Assignment

A Campaign can automatically select an AI Agent when its chosen Phone Number is assigned to an Active AI Agent.

10.197 Campaign Greeting

The AI Agent’s First Message can use:

{first_name}
{last_name}
{company}

from the Campaign Contact.

10.198 Campaign Context

The AI Agent Call record can include:

Campaign ID
Campaign Contact ID

10.199 Missing Master Contact

The Campaign AI Call creation path does not clearly populate the AI Call’s direct:

contact_id

A Campaign Contact can therefore be linked while master Contact context remains unavailable to the Conversation Engine.

10.200 Campaign Contact Results

The Campaign AI path can update Campaign Contact Status when:

Conversation ends normally:
completed

Two consecutive silences:
no_answer

Conversation handler fails:
failed

10.201 On-Demand Difference

The Campaign On Demand Start action described in Chapter 7 does not use the Campaign AI Agent route.

It uses static TTS or Audio playback.

Use a normal controlled AI Campaign test to verify AI Agent behavior.

Live AI Calls

10.202 Opening Live Calls

From the Sidebar:

Conversational AI
→ Live Calls

The page address is:

/ai-agents/live

10.203 Live Page Information

The page can display:

Active AI Agent Calls
AI Agent
Direction
From Number
To Number
Status
Duration
Turn Count
Cost estimate
Conversation transcript
End Call

10.204 Active Statuses

Active AI Calls include:

initiated
ringing
in-progress

with no Ended At timestamp.

10.205 Initial Call List

The active Call list is loaded when the page opens.

10.206 New Call Refresh Limitation

The selected Call’s details are refreshed repeatedly.

The main active Call list itself is not continuously reloaded in the same way.

A new Call that begins after the page opens might not appear until the user selects:

Refresh

10.207 Selected Call Polling

The selected Call details are refreshed approximately every:

5 seconds

The active Call status Card can poll more frequently.

10.208 Provider Synchronization

Loading Call details can also synchronize the record with Twilio.

This can update:

Status
Duration
Ended time
Recording
Provider cost

10.209 Live Transcript

The transcript displays stored conversation turns such as:

Caller
AI Assistant

with available confidence and timing information.

10.210 Transcript Is Not Raw Audio Transcription

The live transcript is assembled from the speech text and AI response records stored during conversation.

It is not necessarily a later word-for-word transcription of the recording.

10.211 Live Duration

Duration can remain zero or stale until the database or Twilio synchronization provides an updated value.

10.212 Ending a Live Call

Select:

End Call

to request provider completion.

10.213 Missing Supervisor Controls

The Live Calls page does not provide:

Whisper
Join Call
Barge In
Mute AI
Change Prompt
Live Transfer
Send a private instruction

10.214 No Live Search

The current page has no full Search or filter controls for:

Agent
Phone Number
Direction
Status
Customer

Critical AI Call Ownership Limitation

10.215 Unscoped Call Endpoints

Several AI Agent Call API actions do not apply Customer ownership filtering, including the reviewed paths for:

Call index
Active Calls
Statistics
Export
Call Details
Synchronization
Transcript

10.216 Multitenant Exposure Risk

An authenticated API user can potentially receive AI Call information belonging to another Customer through these unscoped endpoints.

Potentially exposed information includes:

Phone Numbers
Agent identity
Call SID
Transcript
Call status
Cost
Campaign reference

10.217 Recording Endpoint Difference

The AI Agent Recording endpoint does check that the Call belongs to:

Signed-in owner
or
Administrator

This protection is not consistently applied to the other AI Call endpoints.

10.218 Required Correction

Before multitenant production use, every AI Agent Call query should be scoped through:

AiAgent owner
Customer workspace
Administrator authorization

The Live Calls, History, Statistics, Transcript, Synchronization, and Export endpoints must use the same policy.

AI Agent Call History

10.219 Opening Call History

From the Sidebar:

Conversational AI
→ Call History

The page address is:

/ai-agents/calls

10.220 History Filters

The page offers filters for:

Status
Direction
From Date
To Date

10.221 Status Options

Visible Status options include:

All
Completed
Failed
In Progress

10.222 In-Progress Filter Defect

The interface submits:

in_progress

The stored Call Status uses:

in-progress

The In Progress filter can therefore return no matching Calls.

10.223 Direction

Direction options are:

Inbound
Outbound

10.224 Date Filters

The API applies dates to:

started_at

rather than the Call record’s creation time.

10.225 No Agent Filter

The backend supports filtering by AI Agent ID.

The current Call History page does not provide an Agent selector.

10.226 No Number Search

The page does not provide Search by:

From Number
To Number
Contact
Campaign
Provider Call SID

History Pagination

10.227 Page Size

The API returns approximately:

15 Calls per page

10.228 Missing Pagination

The current History page does not render page-navigation controls.

Calls beyond the first page cannot normally be reached through the visible page.

AI Call History Table

10.229 Columns

The table displays:

AI Agent
Direction
From and To
Status
Duration
Turn Count
Cost
Started
Actions

10.230 Duration

Duration is the AI Agent Call’s stored:

duration

value in seconds.

This differs from the standard Call model, which uses duration_seconds.

10.231 Cost

The table can display:

Estimated total cost
Twilio cost
LLM cost

The field named openai_cost is used as the LLM cost even though the current model provider is OpenRouter.

10.232 Cost Currency

The AI Call model does not provide a separate visible currency code with each cost.

The page formats the value through the application currency formatter.

10.233 Cost Estimate Components

The current default estimate configuration includes rates approximately equivalent to:

Twilio:
$0.0085 per minute

Deepgram:
$0.0043 per minute

These are application estimates and may not equal the provider invoice, Customer Credit debit, recording charge, model charge, or country-specific rate.

Transcript Dialog

10.234 Opening Transcript

Select the Transcript action for a Call.

10.235 Transcript Contents

The dialog can display:

Conversation roles
Conversation text
Full joined transcript
Call information
Recording controls when available

10.236 Empty Transcript

The Transcript button is displayed even when a Call has no stored conversation turns.

The dialog can therefore open with no conversation content.

10.237 Transcript Accuracy

Accuracy can be affected by:

Background noise
Accents
Overlapping speech
Telephone quality
Twilio speech recognition
Caller interruption
Names and technical terminology

AI Agent Recordings

10.238 Secure Recording Route

Unlike the standard Call History page, the AI Agent recording endpoint proxies the recording through AIUNIFY after checking ownership.

10.239 Playback

The Transcript dialog can use the authenticated recording route for playback.

10.240 Download

The endpoint supports a download option and streams an MP3 response.

10.241 Recording Availability

A recording appears after the provider:

Completes recording
Sends recording callback
Stores Recording SID and URL

10.242 Missing Recording

Possible causes include:

Recording disabled
Call did not connect
Recording callback pending
Provider callback failed
Provider recording unavailable
Call ended before audio was captured

Exporting AI Agent Calls

10.243 Export

Select:

Export

from AI Agent Call History.

10.244 Export Filters

The export uses the current:

Status
Direction
From Date
To Date

filters.

10.245 Export Limit

The export returns up to approximately:

10,000 Calls

10.246 Filename

The filename follows:

ai-agent-calls-YYYY-MM-DD-HHMMSS.csv

10.247 Export Columns

The CSV contains:

ID
AI Agent
Direction
From Number
To Number
Contact Name
Campaign
Status
Duration in seconds
Turn Count
Cost Estimate
Transferred
Recording URL
Started At
Ended At
Created At

10.248 Export Omissions

The export does not contain:

Full Transcript
Conversation turns
System Prompt
Knowledge Base
Model actually used per response
Token counts
Separate Twilio and LLM costs
Currency code
Transfer reason
Call error details

10.249 Recording URL Security

The CSV contains the raw provider Recording URL.

Protect the file even though the normal interface uses an authenticated proxy for playback.

10.250 Export Ownership Defect

The export query currently lacks Customer ownership scoping.

This must be corrected before Customers are permitted to export data in a multitenant production environment.

Activating and Deactivating an Agent

10.251 Deactivate

Deactivation changes:

active = false

10.252 Effect

An inactive Agent should no longer:

Answer newly routed inbound AI Calls
Place new outbound Calls
Handle new AI Campaign Calls

10.253 Active Calls

Deactivation does not clearly terminate an AI Call that is already active.

End or monitor current Calls separately.

10.254 Reactivate

Select Activate to make the Agent eligible again.

Before reactivation, confirm its:

Phone Number
Webhook
Model
Knowledge Base
Transfer settings

remain valid.

Deleting an AI Agent

10.255 Permanent Delete Requirements

The backend blocks permanent deletion when the Agent has:

Active Calls
Any Call History
Linked Campaigns

10.256 Empty Agent

Permanent deletion is intended only for an Agent with no operational history or Campaign relationship.

10.257 Delete Dialog Difference

The browser Delete dialog describes permanent deletion.

When Call history exists, its Delete button can be disabled and the backend recommends archiving instead.

Archiving an AI Agent

10.258 Archive Purpose

Archive preserves historical Call data while removing the Agent from normal active use.

10.259 Archive Effects

Archiving:

Deactivates Agent
Unlinks Agent from Campaigns
Soft-deletes Agent
Preserves AI Call records

10.260 Active Call Restriction

An Agent cannot be archived while it has active Calls.

10.261 Campaign Effect

Campaigns linked to the Agent have their AI Agent assignment cleared.

Review each affected Campaign before using it again.

10.262 Archived Agent Visibility

Archived Agents are excluded from the normal Agent API list.

10.263 Restore Route

The backend provides:

POST /api/v1/ai-agents/[Agent ID]/restore

10.264 Missing Restore Interface

The current browser interface has no:

Archived Agents list
Restore button
Archive filter

Archiving is effectively one-way through the normal UI.

Restoration requires an approved API or administrative process.

10.265 Restored State

Restoration does not automatically reactivate the Agent or reconnect it to Campaigns.

Review and reconfigure it before use.

Safe AI Agent Testing Workflow

10.266 Initial Setup

Create Knowledge Base with nonconfidential test information
Create Agent as Inactive
Select model and voice
Write prompt and greeting
Configure transfer
Save Agent

10.267 Phone Setup

Open Edit
Assign test Phone Number
Save
Run Configuration Test
Configure Webhooks

10.268 Inbound Test

Activate Agent
Call assigned number from internal telephone
Confirm greeting
Ask approved Knowledge Base questions
Test silence behavior
Test transfer
End Call

10.269 Outbound Test

Open Agent Details
Select Make Call
Enter internal test number in E.164 format
Confirm correct caller ID
Complete test conversation
End Call

10.270 Review

Open AI Call History
Review status and duration
Review transcript
Play recording
Review cost
Confirm transfer result

Troubleshooting Agent Creation

10.271 System Prompt Required

Enter an approved System Prompt before saving.

10.272 Models or Voices Are Empty

Possible causes include:

API request failed
Authentication expired
Configuration array missing
JavaScript request error

The current page logs these loading failures to the browser console but does not always show a visible error.

10.273 Knowledge Bases Are Empty

The Knowledge Base API can have failed, or no records exist.

The Create page can silently continue with an empty list.

10.274 Phone Number Field Missing

This is expected on Create.

Save the Agent, then open Edit.

Troubleshooting Phone Assignment

10.275 Number Disappeared from Another Agent

Saving the same number on a new Agent clears it from the previous Agent.

10.276 Number Does Not Appear

Confirm:

Number exists in AIUNIFY
Correct Customer owns number
Number endpoint returns it
Number has not been revoked

10.277 Webhook Configuration Fails

Confirm:

Global Twilio configuration active
Number exists in that Twilio account
APP_URL uses HTTPS
Credentials valid

10.278 Configuration Says Webhook Is Ready but Calls Fail

The stored Webhook flag can be stale, and the test does not make a real public reachability request.

Review the number directly in Twilio and make an actual inbound Call.

Troubleshooting AI Responses

10.279 Agent Does Not Answer Questions Correctly

Review:

System Prompt
Knowledge Base assignment
First 4,000 Knowledge Base characters
Contact context
Selected model
Prompt cache

10.280 Later Knowledge Base Content Is Ignored

Only approximately the first 4,000 characters are inserted into the prompt.

Move essential information to the beginning or implement semantic retrieval.

10.281 Knowledge Base Change Did Not Appear

The Agent prompt can remain cached for up to approximately ten minutes.

Wait for expiration or clear the appropriate application cache through an approved process.

10.282 AI Takes Too Long

Possible causes include:

Slow selected model
Model fallback attempts
Large prompt
Network latency
OpenRouter delay
High response length

10.283 AI Repeats “Say That Again”

The model request is failing.

After repeated failures, the system can transfer or terminate depending on configuration.

10.284 Response Is Cut Short

The current service limits:

Generated tokens
Spoken response characters
Request timeout

Shorten the desired answer through the System Prompt and Knowledge Base.

Troubleshooting Voices

10.285 Wrong Voice Plays at Goodbye

Transfer and Goodbye TwiML currently use Joanna Generative regardless of the Agent’s selected Voice.

10.286 Voice Falls Back to Joanna

The saved Voice ID is not recognized by the current mapper.

10.287 Voice Description Says Generative but Sounds Different

The standard short Voice IDs map to Polly Neural voices.

Troubleshooting Transfer

10.288 Transfer Keyword Does Nothing

Check:

Transfer enabled
Transfer Number present
Keyword stored in trigger_keywords
Caller speech contains the keyword
Speech recognition captured the phrase

10.289 Edited Keyword Did Not Save

The Edit interface uses the incorrect transfer_keywords field.

10.290 Transfer Rings but Does Not Connect

Check:

Transfer Number format
Destination availability
Caller ID authorization
Twilio permissions
30-second timeout

10.291 Transfer Happens Unexpectedly

Substring matching can match a keyword inside a longer phrase.

Use more specific Trigger Keywords.

Troubleshooting Inbound Calls

10.292 Number Says Not Configured

Possible causes include:

No Active Agent
Phone Number mismatch
Webhook points elsewhere
Country code differs
Agent was archived

10.293 Wrong Agent Answers

The current fallback matches the last ten digits and selects the first result.

Review duplicate suffixes across international numbers.

10.294 Non-English Caller Is Misunderstood

Speech recognition is hard-coded to en-US.

10.295 Call Ends After Silence

Two consecutive Gather timeouts end the Call.

Increase Silence Timeout where appropriate, up to the permitted maximum.

10.296 Call Exceeds Maximum Duration

The current standard handler does not visibly invoke the available duration-limit check.

The configured Maximum Duration is not confirmed as enforced.

Troubleshooting Outbound Calls

10.297 Make Call Button Missing

The Agent is:

Inbound-only
or
Missing a Phone Number

10.298 Make Call Button Disabled

The Agent is Inactive.

10.299 Invalid Destination

Use complete E.164 format.

The backend does not strictly normalize or validate the destination before Twilio.

10.300 Call Has No Contact Name

The Make Call dialog does not link a Contact.

10.301 No Credit Deduction Appears

The manual AI Agent Call controller does not show integration with the Customer Credit ledger.

Review provider and platform billing before assuming the Call was free.

Troubleshooting Live Calls

10.302 New Call Does Not Appear

Select Refresh.

The main active Call list does not continuously reload.

10.303 Transcript Does Not Update

Confirm the selected Call is still active and refresh its details.

10.304 Duration Is Zero

The stored duration may not update until provider synchronization or completion.

10.305 End Call Fails

The Call can already be completed, or the provider Call SID can be unavailable.

Refresh the Call state.

Troubleshooting AI Call History

10.306 In-Progress Filter Is Empty

The interface submits in_progress, while stored status is in-progress.

10.307 Older Calls Are Missing

Only the first API page is displayed, and pagination controls are absent.

10.308 Agent Filter Is Missing

The API supports it, but the current page does not.

10.309 Transcript Is Empty

Possible causes include:

Call never connected
No speech was recognized
Conversation rows were not created
Call failed before greeting

10.310 Recording Does Not Play

Possible causes include:

Recording callback pending
Twilio credentials unavailable
Provider URL invalid
Recording was removed
Session lost authorization

10.311 Cost Does Not Match Credit Statement

The displayed value is an AI Call cost estimate or provider cost field, not necessarily the platform Credit charge.

Troubleshooting Knowledge Bases

10.312 Another Customer’s Knowledge Base Appears

The current Knowledge Base table has no Customer owner field.

Do not open, edit, use, or delete another organization’s content.

Report the issue immediately.

10.313 File Preview Changes Were Lost

The server reread the original uploaded file.

Use Plain Text mode for edited content.

10.314 URL Import Fails

Possible causes include:

URL inaccessible
Request exceeded 15 seconds
Remote server rejected request
Non-HTTP protocol
Invalid SSL

10.315 Imported Page Contains Unwanted Text

The extractor removes HTML tags but does not identify the page’s main article or business section.

Clean the content manually.

10.316 Deleted Knowledge Base Removed Agent Context

Deleting the record set the Agent’s Knowledge Base relationship to null.

Assign another Knowledge Base or restore approved inline content.

Security and Privacy Checklist

10.317 Knowledge Base

Confirm:

No confidential cross-Customer data
No passwords
No API keys
No payment-card data
No unnecessary personal information
Only approved business content

10.318 Prompt

Confirm:

No hidden credentials
No private internal URLs
No prohibited claims
No instruction to reveal sensitive data
No instruction to bypass consent

10.319 Recordings and Transcripts

Confirm:

Recording legally authorized
Disclosure provided
Access restricted
Retention documented
Exports protected
Raw Recording URLs not shared

10.320 Multitenant Controls

Before broad production deployment, confirm ownership enforcement for:

Knowledge Bases
AI Call list
Active Calls
Statistics
Call Details
Transcripts
Synchronization
Exports

AI Agent Readiness Checklist

10.321 Identity and Purpose

Name clear
Description complete
Type correct
Business purpose approved

10.322 Intelligence

Model selected
System Prompt approved
First Message approved
Goodbye Message approved
Temperature conservative
Response length tested

10.323 Knowledge

Correct Knowledge Base selected
Important content within first 4,000 characters
No confidential shared-tenant data
Answers manually tested

10.324 Voice

Voice selected
Pronunciation tested
Goodbye Voice difference understood
Transfer Voice difference understood

10.325 Calling

Phone Number assigned
Number belongs to correct Customer
Twilio Webhook configured
Inbound test completed
Outbound test completed

10.326 Transfer

Transfer enabled only when needed
Number in E.164 format
Keywords verified in trigger_keywords
Successful and failed transfer tested

10.327 Compliance

AI disclosure approved
Recording consent approved
Calling purpose authorized
Calling hours approved
Opt-out behavior tested
Human escalation available

Live-Call Review Checklist

10.328 During a Test Call

Review:

Correct Agent
Correct caller ID
Correct greeting
Speech recognition
Response latency
Voice
Knowledge accuracy
Transfer
Silence behavior

10.329 After the Test Call

Review:

Final Status
Duration
Turn Count
Transcript
Recording
Cost Estimate
Transfer result
End Reason

Current-Build Limitations

10.330 Confirmed Limitations

The reviewed AI Voice Agent and Knowledge Base implementation currently includes these important limitations:

Browser AI and Knowledge Base pages require
Business KYC, but corresponding APIs do not

AI Agent list loads approximately 15 Agents
and provides no pagination controls

Search covers only the loaded first page

Create does not assign a Phone Number

Edit can silently remove a Phone Number
from another AI Agent

Update does not apply the same Phone Number
uniqueness validation as Create

The number selector’s ownership and availability
scope requires stronger verification

Visible prompt templates differ from the
backend Template API

Model and Voice loading failures may appear
only in the browser console

Maximum Tokens is further capped internally
for live voice responses

Voice descriptions can say Polly Generative
while standard IDs map to Polly Neural

Transfer and Goodbye prompts use a hard-coded
Joanna Generative Voice

Transfer keywords use trigger_keywords during
Create but transfer_keywords during Edit and Show

Edited Transfer Keywords can be ignored

Twilio Webhook accessibility test checks HTTPS
format rather than actual public reachability

Stored Webhook readiness can become stale

Deepgram is tested but the current standard
TwiML conversation path uses Twilio speech Gather

Speech recognition language is hard-coded to en-US

No normal Agent language field exists

Maximum Call Duration and maximum-turn checks
exist but are not invoked by the reviewed
standard TwiML conversation handler

Only the most recent six conversation turns
are sent to the model

Knowledge Base content is capped at approximately
4,000 prompt characters

Knowledge Base changes can remain cached temporarily

No semantic Knowledge Base retrieval exists

Knowledge Bases have no Customer owner field
and are globally shared records

Any authenticated API user can potentially
view, edit, or delete global Knowledge Bases

Knowledge Base URL fetch lacks private-network
and internal-address protections

Knowledge Base file-preview edits are ignored
when the original file is submitted

No Knowledge Base version history or usage list exists

Manual Make Call does not link a Contact or Campaign

Manual destination Phone Number validation is weak

Manual AI Call initiation does not show a
Customer Credit affordability or debit process

Inbound Agent lookup permits last-ten-digit matching

Last-ten-digit matching can route international
number collisions incorrectly

Campaign AI Calls may lack a direct master Contact link

Live active Call list does not continuously reload

Live monitoring provides no whisper, join,
barge-in, or supervisor-transfer controls

Several AI Agent Call API endpoints lack
Customer ownership scoping

Unscoped endpoints include list, active Calls,
statistics, Details, synchronization,
transcript, and export

AI Call History loads approximately 15 Calls
and provides no pagination controls

The In Progress filter uses in_progress
instead of stored in-progress

No visible Agent filter or Phone Number Search exists

Transcript buttons can appear for empty transcripts

AI transcript is assembled from conversation turns,
not a post-call audio transcription

Cost estimates do not necessarily equal
Credits or provider invoices

AI Call export contains raw Recording URLs

AI Call export is not owner-scoped

Permanent deletion is blocked when history exists

Archive unlinks Campaigns and hides the Agent

No visible Archived Agent list or Restore control exists

Chapter Completion

At the end of this chapter, the user should understand the difference between a human Agent and an AI Voice Agent and know how to open:

AI Agents
Knowledge Bases
Live Calls
AI Call History

The user should understand how to create an Agent, select its Type, model, Voice, System Prompt, greeting, Goodbye Message, Knowledge Base, recording preference, timeouts, and transfer configuration.

The user should know that the current configured AI models are accessed through OpenRouter and that the live conversation service can attempt fallback models when the selected model fails.

The user should understand how the configured Voice maps to Twilio speech, why the final transfer or Goodbye Voice can differ, and why an internal telephone test is required.

The user should understand that the AI prompt contains:

Platform base instruction
+
Knowledge Base
+
Agent System Prompt
+
Contact and Campaign context
+
Recent conversation turns

The user should recognize that a Knowledge Base can store up to approximately 500,000 characters while only the first approximately 4,000 characters are inserted into the current Agent prompt.

The user should know how to create a Knowledge Base through Plain Text, File, or URL import and recognize the current file-preview, URL-fetch, versioning, and global-ownership limitations.

The user should understand how to save an Agent, open Edit, assign a Phone Number, configure Twilio Webhooks, run Configuration Test, and complete real inbound and outbound telephone tests.

The user should know how inbound AI Calls are routed, how the First Message begins the conversation, how caller speech and AI responses are stored, how silence is handled, how transfer is triggered, and how the Call ends.

The user should understand how to monitor Live Calls, open transcripts, end an active Call, review recordings, inspect cost estimates, and export AI Call History.

Most importantly, the user should follow this controlled deployment sequence:

Create nonconfidential Knowledge Base
Create Agent as Inactive
Configure prompt, model, voice, and transfer
Assign dedicated test Phone Number
Configure and verify Twilio Webhooks
Complete inbound and outbound test Calls
Review transcript, recording, transfer, and cost
Correct all ownership and security defects
Activate for a limited production audience
Monitor every early Call


Write Your Comment