AI Agents¶

Overview¶

AI Agents are virtual voice assistants that answer and place phone calls on behalf of a business. Each agent is configured as a Persona, which defines:

its identity and greeting;
how it listens and speaks;
its voice and personality;
what it knows;
which actions (tools) it can take during a call;
what it records in the CRM afterwards.

A persona can be specialised for any role: receptionist, sales qualifier, appointment booker, first-level support, and so on.

Where to Find It¶

AI → AI Agents → Personas

The list shows every persona with its Routing (AI callflow or queue), Name, Job, Extension, DID and Description. Click Add Persona to start from scratch or from a template, for example Medical Receptionist.

Functionality¶

Profile¶

Field	Description
Name	Required. The persona's name.
Job	Required, up to 35 characters. Shown as caller ID to users who receive transfers.
Description	Required. The persona's purpose.
Agent name (voice)	The name of the person or team the assistant works for. Available in greetings and prompts as `{persona_agent_name}`.
Company display name	Available as `{company_name}`. Falls back to the account name.
Service area / Market region	Context used in conversation flows.

Telephony¶

Field	Description
Extension / DID	The internal extension and the phone number that reach the persona. Saving the persona creates the call routing automatically.
Show inbound callflow in SmartPBX	Makes the persona's callflow visible in SmartPBX, so it can be used from other callflows.
Warm transfer destination	A user or queue to hand the call to, or None (ask caller).
Fast-track mode	Off, Bypass LLM or Assist then route: controls how quickly a recognised caller is routed to a human.
Qualified recent lookback	How many days back (default 30) a previous qualification of the caller is taken into account.

Dispositions¶

Choose which dispositions the persona can assign to a call, for example HOT, WARM or COLD. If the persona serves a queue, the queue's dispositions are used instead. The disposition is recorded on the CRM case.

Warning

When Save calls in CRM is on and no disposition is available, the AI cannot classify calls. The form shows a warning in this case.

CRM¶

Setting	Effect
Save calls in CRM	After each call, the conversation is analysed and saved to the CRM as a contact, a lead and a case. The analysis covers intent, summary, disposition with justification, classification (lead / customer / spam / other), tags, and caller sentiment with evidence.
CRM auto follow-up	Enables outbound follow-up calls on cases (the Follow-up tab in Case Details).

Memory¶

When Memory is enabled, the persona remembers previous conversations with the same caller.

Speech Engine¶

A persona uses one of two modes.

1. Single real-time model. One model listens, reasons and speaks. This gives the lowest latency and the most natural dialogue.

Provider	Models
OpenAI	`gpt-realtime` (default for new personas), `gpt-realtime-2.1`, `gpt-realtime-2.1-mini`, `gpt-realtime-2025-08-28`, `gpt-4o-realtime-preview`
Google	`gemini-3.1-flash-live-preview`

2. Modular pipeline. Separate speech-to-text, language model and text-to-speech stages:

STT: Deepgram Nova 3
LLM: OpenAI GPT-4o Mini
TTS: OpenAI gpt-4o-mini-tts, Deepgram Aura-2, or ElevenLabs (ElevenLabs uses the platform's ElevenLabs credentials; there is no portal field for an account-level ElevenLabs key)

Note

Which pipeline options are applied at runtime depends on the AI worker pool that serves the persona. Confirm with QVOICE support before relying on a TTS other than OpenAI.

Caller Language: Auto, English, Spanish, Portuguese, French, German or Italian.

Voice¶

Voice: 10 OpenAI voices, or 30 Gemini voices when the provider is Google.
Vibe: the speaking style. Choose Professional, Friendly, Business, Warm & Empathetic, Energetic, Calm, Casual, Authoritative, Supportive, or Custom (free text).
Generate Voice: plays a preview of the selected voice and vibe. Available for OpenAI voices.

Office Hours¶

Opening hours per day (open/close time, closed, or 24 h). The assistant uses them to answer "are you open?" and to decide whether to hand the call to a human (see Limitations).

Greeting¶

Field	Description
Initial Greeting	Required. What the assistant says when it answers, e.g. "Welcome to {company_name}, this is {persona_agent_name}'s AI Assistant…".
Outbound greeting	Used when the persona places the call.
Personalise from Contacts	Greets known callers by name.
Allow interrupt	Lets the caller talk over the greeting.
Handoff and callback lines	What the assistant says while reaching a human, and when it closes with a callback promise.

Tools and Integrations¶

Tools are actions the assistant can take during a call. The prompt explains when to use them; the tool performs the action or returns real data; the assistant turns the result into natural speech.

Built-in tools, available to every persona:

Tool	What it does
`transfer_call`	Transfers the caller to an extension, number or queue. For safety, it does not transfer to numbers the caller dictates unless the instructions explicitly allow it. See the Office Hours note under Limitations.
`is_office_open`	Checks the persona's Office Hours.
`lookup_contact`	Looks up the caller in the CRM contacts and the directory.
`check_user_availability`	Checks whether a user is available (not on Do Not Disturb).
`hangup_call`	Ends the call, after the caller confirms there is nothing else.
`save_contact`	Creates or updates the caller's CRM contact during the call.
`set_runtime_tier`	Records the call's disposition.

Note

save_contact can write to the CRM even when Save calls in CRM is off. That setting controls the post-call contact, lead and case records, and the prompt guidance that tells the assistant to use the CRM tools. Do not rely on it alone to keep a persona out of the CRM.

Tools that depend on the persona's integrations or the platform:

Tool	Available when
`notify_agent_whatsapp`	Sends a WhatsApp notification to a human agent. It works only when the persona's WhatsApp integration is linked and connected.
`notify_agent_email`	Sends an email notification to a human agent when the Gmail integration is linked.
`send_lead_to_agent`	Hands the captured lead to a human agent. Enabled per platform.
`calendly_list_event_types`	Lists the event types of the linked Calendly account, with the URI each Calendly tool needs. Needs the Calendly integration linked.
`calendly_list_availability`	Lists the free slots of one event type, for a window of up to seven days. Slots come back in UTC. Needs Calendly linked.
`calendly_schedule_meeting`	Books a slot for the caller. It needs the caller's email and time zone, and a name. Needs Calendly linked and a paid Calendly plan.
`calendly_cancel_meeting`	Cancels a booked meeting. Needs Calendly linked.
`calendly_reschedule_meeting`	Moves a booked meeting to a new time: it cancels the meeting and books a new one for the same invitee. Needs Calendly linked and a paid Calendly plan.

Note

The persona editor lists the Calendly tools by label (List event types, List availability, …). When the prompt names a tool, use the exact name in the table above, with its calendly_ prefix. The assistant cannot call a tool by a name that does not exist, such as list_event_types. The call fails and the assistant tells the caller it could not check.

A Calendly scheduling link (https://calendly.com/<user>/<event>) is not the identifier the tools use. Have the assistant call calendly_list_event_types first and pick the matching event type from the list.

Custom tools, added with Add tool:

Type	What it does
Transfer Call to User	Transfers the call to a specific user.
Transfer Call to Queue	Transfers the call to a specific queue.
API Request	Calls an external HTTP API. You define the method, URL, headers and typed variables (string, number, enum) that the AI fills in from the conversation.
WhatsApp link	Sends the caller a WhatsApp link. Only personas that use conversation flows (Gate runtime) support it; it is not available to Legacy prompt-based personas.

The tool name the AI sees is the configured name in lowercase, with spaces replaced by underscores.

Integrations:

Integration	What it adds
WhatsApp	Links a WhatsApp number (by QR code) for notifications and links.
Calendly	Tools to list event types, check availability, and schedule, cancel or reschedule meetings. Needs a Personal Access Token.
Gmail	The persona processes an inbox: inbound emails become CRM contacts, leads and cases. Adds `notify_agent_email`, and optionally adds inbound leads to a campaign.

Prompt and conversation flow¶

The AI worker pool setting decides how the conversation is scripted:

Legacy: a single Prompt that describes the role, tone and rules. It keeps a history of the last 20 versions, has an AI chat that helps write the prompt, and can generate a Flow Diagram of the conversation.
Gate runtime: structured inbound and outbound conversation flows, edited in a visual builder and validated on save.

Knowledge¶

Structured data the persona can answer from, such as a price list, product catalogue or branch list. See Knowledge.

Writing a Prompt: Example¶

Prompt:

You are the phone assistant for Acme Dental.

Always greet the caller politely.

If the caller asks whether the office is open, call is_office_open and tell them the result.

If the caller wants an appointment, call calendly_list_event_types to find the "Cleaning" event, call calendly_list_availability to offer the next two available slots, and book the one they choose with calendly_schedule_meeting.

If the caller has an emergency, call transfer_call to the clinic's front desk.

Before ending, confirm the caller has nothing else, then call hangup_call.

Never invent information. Use only the tools and the knowledge provided.

Flow:

Caller	Assistant
"Are you open today?"	Calls `is_office_open` → `{ "open": true }` → "Yes, we're open until 6 pm today."
"Can I book a cleaning next week?"	Calls `calendly_list_availability` → offers two slots → books the chosen one with `calendly_schedule_meeting` → "You're booked for Tuesday at 10 am."
"I have a broken tooth and I'm in pain."	Calls `transfer_call` to the front desk → "I'm putting you through to our team right now."

Tip

Use snake_case names for your custom tools (for example check_order_status). That is how the assistant refers to them.

How It Works¶

sequenceDiagram
    participant C as Caller
    participant PBX as QVOICE Platform voice platform
    participant W as AI agent worker
    participant M as AI model (OpenAI / Google)
    participant T as QVOICE Platform tools & CRM
    C->>PBX: Calls the persona's DID / extension
    PBX->>W: Routes the call to an available AI worker
    W->>M: Streams audio (real-time) or text (pipeline)
    M-->>W: Response / tool call
    W->>T: Execute tool (transfer, lookup, calendar, API…)
    T-->>W: Result
    W-->>C: Spoken response
    alt Transfer
        W->>PBX: Transfer to user / queue / number
    end
    C-->>W: Hang up
    W->>T: Save call in CRM (if enabled)

Saving a persona with an Extension or DID creates its call routing automatically. The persona can also be reached from another callflow, via the AI Voice Agent node in the callflow editor.
Calls are distributed across a pool of AI agent workers. If no worker is available, the call follows the callflow's fallback branch when one is configured.
The model provider is called with the account's own keys from GenAI Integrations, or with the platform's default keys.
Handing over to a human is a transfer to a user, queue or number. When nobody can take the call, the assistant can notify an agent by WhatsApp or email, and close with a callback promise.

Configuration¶

Requirement	Who	Details
AI Agents enabled on the platform	Platform operator	AI agent workers must be deployed for the platform. Contact QVOICE support to confirm availability.
Model provider keys	Platform or reseller	OpenAI / Gemini keys, either the platform's or the account's own in GenAI Integrations. The modular pipeline also uses Deepgram, configured in AI Transcription.
Role permission	Account admin	AI → Personas (and Knowledge). Only administrators can manage personas.
Phone number	Account admin	A free DID, and optionally an extension, to assign to the persona.
Dispositions	Account admin	Needed for CRM classification. Defined in the campaign / queue disposition settings.

Setting up a new persona:

AI → AI Agents → Personas → Add Persona.
Fill in Profile and Greeting. Choose the Speech Engine and Voice, and test with Generate Voice.
Set Office Hours and the Warm transfer destination.
Write the Prompt (or conversation flow) and add the Tools it needs.
For CRM output, turn on Save calls in CRM and select Dispositions.
Optionally upload Knowledge.
Assign a DID or Extension and save. Call the number to test.

Use Cases¶

24/7 receptionist. A clinic routes its main number to a persona with Office Hours and the clinic's services uploaded as Knowledge. After hours, the assistant answers questions and books appointments through Calendly. During hours, it transfers urgent calls to the front desk. Every call lands in the CRM with a summary.

Inbound sales qualification. A car dealership's ad campaign number goes to a persona that asks qualifying questions and sets a HOT / WARM / COLD disposition. HOT callers are warm-transferred to the sales queue immediately. The others are saved as leads for the sales team's call-back list in CRM Cases.

Order status line. An e-commerce company adds an API Request tool, check_order_status, that calls its order system with the order number. The assistant answers "where is my order?" calls fully. It transfers to a human only for complaints.

Outbound follow-up. With CRM auto follow-up enabled, the persona calls back customers on open cases using the Outbound greeting. It records the outcome on the same case.

Limitations¶

Voice preview (Generate Voice) is available for OpenAI voices only.
Office Hours and transfers: for personas on conversation flows (Gate runtime), the transfer tool is withheld while the office is closed. For Legacy prompt-based personas, after-hours behaviour is guided by the prompt only. State it explicitly in the prompt, for example "do not transfer when the office is closed".
Calls with no conversation (for example, an immediate hang-up) are not saved to the CRM.
If the OpenAI account the persona runs on is out of credit, the agent cannot speak and the call is hung up. The platform does not show the provider's remaining balance; see GenAI Integrations.
Knowledge is added to the persona's instructions in full, so large files increase cost and latency. See Knowledge.