Module 22 · Voice AI

Leer en español: Módulo 22 · La IA de voz.

Goal: create a voice-AI agent with its mandatory disclosure and its voice, test it without calling anyone, set it live, follow its conversations, take over a call, and stop all AI dialing when you need to. Time: ~9 minutes · You need: an account with the Voice AI add-on turned on by the platform (see the first section), a campaign of type “AI voice agent” (the campaign wizard in Module 3) and, to listen or take over, a checked-in seat (Module 8).

This module is about the AI that calls your consumers. It lives in the side menu under Voice AI, in three screens: the overview (/voice-ai), the AI agents list (/voice-ai/agents) and each agent's builder (/voice-ai/agents/:id).

1. Who turns it on, and on which plans

The console has no switch for the Voice AI add-on, and that is not a missing feature: the platform turns the add-on on per account, behind its administration token. If you want it, write to your Dialer Digital contact. How it is billed (per connected minute, with its monthly minimum and its volume step) is in Module 7, §6.

• Plans: the add-on is not offered on Starter. Growth, Scale and Enterprise are eligible (Module 7, §5).
• Flags: the three screens in this module depend on no flag from the platform's catalog; everything this module describes works with only the add-on turned on.

2. Create an agent

1. In the side menu choose Voice AI. On the overview, the Manage AI agents → link takes you to the AI agents list. The screen reminds you: “Configure disclosure, negotiation bounds and handoff rules per agent. Test in the sandbox before you set one live.”
2. Choose + New agent. Two fields open: Agent name and the Mandated opening disclosure (mini-Miranda), with the reminder that it becomes immutable once the agent goes live.
3. Choose Create. The agent is born as Draft and the console opens its builder. Cancel discards the form.

The list shows, per agent, Name, Status, Voice, Policy and the Edit → action; Refresh reads it again. With no agents it says “No AI agents yet — create the first one.” Two agents in the account cannot share a name: the server rejects the duplicate.

The mandatory disclosure

Every AI call must open by saying the voice is automated. That is why the text is not free-form:

• It must identify the voice as automated. The server checks it on save, in English and Spanish: the text must contain at least one of these markers: “virtual assistant”, “automated”, “automatic”, “artificial”, “robot”, “a.i.”, “asistente virtual”, “automatizado”, “automatizada”, “inteligencia artificial”, or the words “AI” or “IA” with a space on each side (or at the very start or end of the text): next to a punctuation mark, as in “an AI.” or “an AI,”, they do not count. A text that never says it is a machine is rejected and the agent is not created.
• It freezes the first time the agent goes live. From the first time the agent is set live, the text cannot be changed.
• In the console you write it at creation. The builder always shows it in a locked box, with the padlock and the Mandated — locked tag. If you get the text wrong before going live, create another agent with the right text.

And the rule that is not negotiable: without at least one live agent with a valid disclosure, the dialer originates no AI call at all (the compliance gate blocks it as tenant policy and records it in the evidence). A badly written disclosure is not a style detail: it is a stopped campaign.

3. Give it a voice and a policy in the builder

The builder has a breadcrumb (Voice AI › Agents › agent name) and, at the top, the agent's status with its selector: Draft, Live or Paused (Retired appears as a tag but is not chosen here). Whatever you change is saved with the bar at the bottom: it reads Unsaved changes. or All changes saved., and the button is Save changes (“Saving…” while it works).

Voice. Agent voice is a selector over the platform-governed voice catalog, filtered by the agent's Language (English (US), Spanish (US) or Spanish (MX)). A voice the agent already had that has left the catalog shows as “… — not in the catalog” and stays editable, but to pick another it has to be from the catalog. Speaking pace is a slider whose label moves between Slow, Natural and Fast.

Hear the voice before a consumer does. ▷ Preview plays a fixed sample sentence in the saved voice (if you changed the voice, the console says “Save the voice change to hear it.”). You cannot type the sentence: there is one per language. While it prepares it says “Preparing sample…” and you can cut it with ■ Stop. If you ask for too many samples it says “Too many samples requested. Try again in N s.”; an agent with no catalog voice has no sample: “Pick one and save.”

Conversation policy. Next to the title is the policy version (policy_version): every change to the voice, disclosure, policy, handoff rules or status raises it by one and keeps an uneditable copy, and transcripts cite the version in force. A name-only change does not raise it. The Negotiation bounds are:

• Max settlement: a percentage of the balance.
• Min payment: in dollars.
• Max plan length: in months.
• Take payments: a selector with No or Yes — card-on-file only. The tenant setting ai_take_payments_enabled (off by default) gates the second option: while it is off, core refuses take_payments: card_on_file with a 422, so the selector offers only No, and the console shows “Charging a card on file is not available. Leave Take payments on No.” if a save is refused anyway. An agent that already stores Yes keeps it in the selector and can be saved with it, but while the setting is off the platform serves that agent to the voice runtime as No. The console cannot read the setting, so it offers Yes only to an agent that already has it. Despite its name, nothing in the platform charges a card: with Yes, when the consumer agrees to pay an amount the AI records a payment commitment (a promise to pay, “PTP”) and says “Thank you, I've noted your promise to pay $X”, never that it processed a payment. The conversation ends as a PTP, not as a payment taken (voice-ai ADR.md #19). The same minimum and handoff limits apply as before.
• Prohibited: the behaviours the agent must not have. Type in “Add a prohibited behaviour…” and choose Add; Remove deletes it.

Handoff rules. Each rule says when the agent hands the call to a person (keywords, negative sentiment, a payment above an amount, or the consumer asking for a person) and the action it runs, with its severity (“hard rule” or “soft rule”). The ones with the padlock are “Compliance-locked — cannot be edited or removed”; the rest are removed with Remove. With no rules it says “No handoff rules configured.”

4. Test it before setting it live

On the right of the builder is the Test conversation, tagged Sandbox — no live calls. It starts with the agent's disclosure as the first line; you type what the debtor would say (“Type a debtor line to start the sandbox.”) in the “Type a test reply…” field and send it with the ➤ button (“Send test message”). The agent answers in the left bubble and the thread continues in the same test session.

The sandbox is fake for real: there is no call, no conversation is created in the history and nobody is dialed. If the AI engine is unavailable, the test fails with a red notice instead of inventing an answer. Use it to try your negotiation bounds and to check that a phrase like “I want to talk to a person” triggers the handoff.

The test has limits, because every turn spends the platform's AI. In practice you will hit them only if something loops:

• A test line is capped at 4,000 bytes (about 4,000 plain letters; accented letters and emoji take more than one byte each). A longer one is refused with a 400 and the message “message is too long (max 4000 bytes)”.
• At most 30 test turns per minute for your whole account, and 12 per minute inside one test session. Over either, the answer is a 429 with a Retry-After: the seconds left until the next minute starts. Wait that long and send again.
• The thread remembers a bounded history. A test session keeps about the last 24,000 bytes of conversation; the oldest turns drop first, so a very long test forgets how it began. The agent's own instructions are never dropped. Idle test sessions are forgotten after 15 minutes: start a new thread instead of reviving an old one.
• A demo account cannot run the test: it answers 403 “synthetic_tenant”.
• If the platform has no AI budget left to spend, the test does not run: the answer is 503 sandbox_budget_unavailable and nothing is sent to the model. This is different from the red notice for “the AI engine is unavailable” (503 sandbox_unavailable).

A refused test is not a call and creates no conversation, exactly like a test that works. Integrators who call the test from code find the same errors in the REST API guide.

When you are happy, change the status to Live and choose Save changes. That save freezes the disclosure. Paused stops counting the agent as a live agent without deleting anything; Retired (through the API only) takes it out of use and keeps its history, because transcripts cite it.

Before you go Live, fill in the guards. A live agent should carry explicit limits, otherwise the voice engine falls back to permissive defaults. When you save with Live, the platform checks that the policy has Max settlement, Min payment, Max plan length and at least one Prohibited behaviour; if you chose Yes — card-on-file only for Take payments, it also wants a handoff rule for a payment above an amount. What happens when something is missing depends on a platform setting you do not control (ai_agent_live_requires_guards, which takes off, observe or enforce):

• observe (the default): the save goes through and the agent is live, but the answer carries a policy_incomplete warning that lists the missing keys (max_settlement_pct, min_payment_cents, max_plan_months, prohibited, payment_over). Fill them in and save again.
• enforce: the save is refused with 422 policy_incomplete, naming the keys that are missing, and the agent does not go live. An agent that is already live and has no guards is not cut off, but it keeps getting the warning, and an edit that would open a new gap is refused.
• off: nothing is checked and no warning is sent.

The console shows both answers when you save: with observe, «Saved, but the agent is live without explicit limits for: …. It runs with permissive defaults until you set them.»; with enforce, «The agent cannot go live without explicit limits. Missing: …. Set them and save again.» Integrators find the same answers in the REST API guide.

5. Follow the live conversations

The Voice AI overview refreshes by itself. At the top are five indicators: AI-handled today, Containment rate, Avg AI handle time, Handoffs to human and AI minutes today (with “billed today”). Below, Today via AI: PTPs secured, Payments taken (the AI does not produce payments: what it agrees to pay counts as a PTP, see §3), Voicemail drops and Compliance violations. They are for the current UTC day.

Two notes to read them right:

• The Containment rate is computed “of conversations closed with a person”: failed ones, disputes and handoffs do not count as contained, and voicemails are left out. If none is closed yet it says “no conversations closed with a person yet”; the ones still in progress are flagged apart and stay outside the rate.
• If the metrics do not load, the console says “Metrics unavailable —” with the reason: it is a read failure, not a zero.

The FCC 24-17 strip summarizes eligibility: “Voice AI dials only lists with artificial/prerecorded-voice consent.” It lists the Eligible and Not eligible campaigns. If it does not answer, it says “eligibility unavailable” and reminds you that the consent gate still enforces server-side on every dial.

The Live AI conversations table (with its “N active” counter) shows, per call, Account, State, Phase (labels as shown: Disclosure, Verification, Negotiation, Payment setup, Wrap-up), Duration, Sentiment and Actions. With no calls it says “No live AI conversations right now — active calls appear here in real time.”

6. Listen and take over

Each row has two actions, with their rules:

• Listen reuses the supervision mechanic of Module 8: it rings your own seat. If the agent flags the conversation as handoff suggested (the model thinks a person should step in), the row offers only Take over, in bold.
• Take over moves the consumer from the AI to your extension and cuts the AI leg. It does not appear during the disclosure: you cannot hand a call off in the middle of the mandatory disclosure. Every takeover leaves an audit row before the call is moved.

You need to be on a checked-in seat: the console says “Listen / Take over rings YOUR seat — check in first (My Workspace → pick your seat), then come back.” Your extension must hold the supervisor or administrator role; if the server refuses, the console shows “Take over failed — …” with the reason.

7. Pause and resume all AI dialing

On the overview, Pause all AI dialing is the account's handbrake. Before acting it asks “Pause all AI dialing?”: “This stops the AI dialer account-wide. Calls already in progress finish; no new AI calls start until you resume.” Confirm with Pause all AI dialing (or Cancel).

While paused, the overview says AI dialing paused, who paused it and at what time, and “New AI calls are held. Calls already in progress finish normally.” You lift it with Resume AI dialing (or Resume). Pause and resume are idempotent: repeating them does no harm. AI calls the dialer tries in the meantime are blocked as tenant policy and stay in the evidence.

Pausing and resuming takes an administrator. A member login gets 403 role_forbidden on either button; the overview that shows the state is still readable.

Tell the three brakes apart: Paused on an agent takes that agent out; Pause all AI dialing stops every agent in the account; and the add-on (§1) is handled by the platform.

8. If the consumer asks for a person

Every agent carries a handoff rule that cannot be removed or edited: when the consumer asks to talk to a person, the call is transferred to a seat, with hard severity. If it is missing, the server injects it when the agent is created.

The handoff leaves its evidence before moving anything and passes the compliance gate again, because the consumer ends up on live audio with a new party. What decides whether there is anyone to hand the call to is your floor: if a seat is free, the call is transferred to it; if none is, the consumer hears an apology and the call ends (unless the AI engine decides to keep talking to them). Keep seats available while you have live AI agents (Module 5).

9. Personal data in the conversations

Two protections keep card, social security and bank account numbers out of the AI's conversations. Neither has a setting in the console.

• What the consumer says aloud is masked on the spot. If during a call the consumer reads out a card number, a social security number, a bank account (or routing number) or a PIN/security code, the platform masks it before it reaches the AI model's history and before the conversation records it. The AI does not repeat it or ask for it again: it answers with a fixed sentence, “For your security, please don't read out card, account or social security numbers on this call.” (in Spanish for Spanish agents), and offers to connect the consumer with a person when a handoff is available. A request for a person or to stop calling made in the same turn is still honored first. A phone number or an amount of money said aloud is not personal data of this kind and goes through untouched.
• What you read afterwards comes redacted. When you read a conversation through the API, the text of each transcript line has those same data masked (a card shows only its last four digits). The original can be requested only by a dd_ key or an account_admin login, and each request leaves an audit trail. The details are in the developer guide.

Know the limits: the detection is a fixed set of rules, not a judgment. It covers cards, social security numbers, bank accounts and PIN/security codes, and nothing else. Digits the speech recognizer writes out in words may go undetected, and a long run of digits that happens to look like a card may be masked even if it was not one. Because the spoken data is masked before the conversation is stored, the original of what was said aloud is not recoverable later, not even with the original-text request.

10. What the AI will never say

Beyond the policy you write, the platform keeps a floor of conduct that no account setting can lower. It is a list owned by the platform: you cannot edit or remove it, and it adds to your Prohibited list instead of replacing it (voice-ai src/voiceai/platform_guard.py, ADR.md #20).

• It never says it is a person. In English and Spanish, the AI is stopped from saying it is a person, a human or a live agent (in Spanish also “de carne y hueso”), and from denying it is a robot, an AI or a recording (“I'm not a robot”). A negation that is itself the honest answer, in Spanish, such as “no soy una persona”, goes through.
• It never threatens arrest or jail. Phrases such as “you will be arrested”, “you'll go to jail” or “warrant for your arrest” (and their Spanish equivalents) are stopped.
• What the consumer hears instead. The vetoed sentence is not spoken: a claim of being human is replaced by “I am an automated assistant.” (“Soy un asistente automatizado.” in Spanish), and an arrest threat by “I want to help you resolve this in the best way possible.” Each replacement is counted as a prohibited-behaviour violation, with the source marked as the platform (prohibited_violation, source: platform).
• “Are you a robot? Am I talking to a person?” The AI does not hand this question to the model: it answers with a fixed line, “I am an automated assistant, an AI, not a person.” (“Soy un asistente automatizado, una inteligencia artificial, no una persona.” in Spanish) and the conversation records machine_question_answered. Questions about the debt, such as “Is this a real debt?”, are not mistaken for it and reach the model.
• The test sandbox applies the same floor.
• Switch. The floor is on by default. The platform can turn it off with the VOICEAI_PLATFORM_GUARD setting (0), as a rollback if it misfires; there is no switch in the console.

Know the limits, which the platform itself writes down: it covers only English and Spanish; a claim phrased with words that are not on the list (“yes, flesh and blood” without “I am”) is not caught; and a phrase that the speech chunker splits across two sentences is caught only from its second half, because the first one has already been spoken.

What next

• How each minute is billed: Module 7.
• Supervising your human agents with the same listen and takeover mechanic: Module 8.
• The reference for the agents and conversations API is in the REST guide.