> For the complete documentation index, see [llms.txt](https://help.ringtonic.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.ringtonic.app/guides/ai-call-answering.md). # AI Call Answering ### What is AI Call Answering? AI Call Answering adds an **AI Agent** node to the Call Flow Builder. The agent picks up the call, greets the caller in a natural voice, answers questions from your business knowledge, qualifies the lead, captures details like name and budget — and then routes the call back into your flow: book an appointment, transfer to a human, send an SMS, or end politely. Unlike standalone AI receptionists, the agent is **one node among many**. It composes with everything else in your flow — Business Hours, Menu, Dial, Round Robin, Voicemail — and every AI outcome is a real branch on the canvas that you wire yourself.

An AI Agent node on the canvas with its outcome ports wired to downstream nodes

{% hint style="info" %} **Use cases at a glance:** A 24/7 receptionist that qualifies leads before your team picks up, after-hours booking on your real calendar, spam screening that never creates junk contacts, and qualified-lead conversions reported straight to Google Ads. {% endhint %} {% hint style="success" %} **Available on all plans — bring your own keys.** The AI Agent runs on your own Twilio account and your own OpenAI API key (plus an optional ElevenLabs key for premium voices). Ring Tonic doesn't meter or mark up AI minutes; usage bills directly to your provider accounts. {% endhint %} *** ### Before You Start The agent needs a few workspace-level credentials before it can take a call. {% stepper %} {% step %} #### Twilio credentials Your workspace must already be receiving calls through Twilio. Check **Settings > Workspaces > Twilio Credentials** — if your tracking numbers work today, you're set. See [Setup Workspace](https://help.ringtonic.app/guides/pages/crg7tMxXMDacQLAiSpgl#1.-set-up-twilio-for-tracking-calls). {% endstep %} {% step %} #### OpenAI API key The agent's brain. Add your key under **Settings > Workspaces >** your workspace **> AI Automation**. See [Set up AI Automation with OpenAI](https://help.ringtonic.app/guides/pages/crg7tMxXMDacQLAiSpgl#4.-set-up-ai-automation-with-openai) for how to create a key. {% endstep %} {% step %} #### ElevenLabs API key (recommended) Powers the agent's natural-sounding voice and lets you pick from your own ElevenLabs voices. Add it under the **Voice & Audio** section of the same workspace settings page. Without it, the Voice tab of the AI node shows: *"No ElevenLabs voices found. Add an ElevenLabs API key in Settings → Integrations to load your voices."* {% endstep %} {% step %} #### Google Calendar (only for appointment booking) If you want the agent to book real appointments, connect your calendar first under **Settings > Integrations > Google Calendar**. See [Appointment Booking](#appointment-booking) below. {% endstep %} {% step %} #### Live speech-to-text engine (optional) Under the workspace **Transcription** tab, the **AI call transcription (live)** section controls which speech-to-text engine transcribes the caller during live AI calls. It runs on your Twilio account — no separate API key. Leave it on **Automatic — let Twilio pick the default (recommended)** unless you have a reason to force Google or Deepgram. {% endstep %} {% endstepper %} *** ### Adding the AI Agent Node {% stepper %} {% step %} #### Drag the node onto the canvas Open your flow in the Call Flow Builder and drag **AI Agent** ("AI answers, qualifies, and routes the caller") from the node palette. Connect your **Start** node (or any upstream node) into it. {% endstep %} {% step %} #### Configure the agent Click the node to open its panel. It's organized into six tabs — **Persona, Goals, Knowledge, Voice, Actions, Safety** — covered section by section below. {% endstep %} {% step %} #### Wire the outcome ports Every conversation ends on exactly one outcome port. Wire each port you use to a downstream node — see [Output Ports](#output-ports-and-how-to-wire-them) for recommendations. {% endstep %} {% step %} #### Test, then publish Run a real **Test call** from the toolbar before publishing — see [Testing with a Real AI Call](#testing-with-a-real-ai-call). {% endstep %} {% endstepper %} *** ### Configuring the Agent

The AI Agent configuration panel with its six tabs: Persona, Goals, Knowledge, Voice, Actions, Safety

#### Persona Who the agent is and how it behaves. | Field | What it does | | ----------------- | ------------------------------------------------------------------------------- | | **Agent name** | The name the agent uses for itself (e.g., "Riley"). | | **Business name** | Your business, referenced naturally during the conversation. | | **Tone** | A short style hint, e.g., "warm, professional". | | **System prompt** | The core instructions for how the agent should behave. **Required to publish.** | #### Goals What the agent is trying to accomplish on every call. * **Objectives** — ordered sub-goals the agent works through, e.g., *"Get the caller's name and reason for calling."* Each objective can list the capture-field keys it must collect (comma-separated). * **Capture fields** — the structured data the agent extracts: a key (e.g., `budget`), a display label, a type (Text, Number, Yes/No, Date), and a **Required** toggle. {% hint style="warning" %} **Every required capture field must be referenced by an objective.** If you mark a field required but no objective asks for it, publishing fails with a clear error — the agent would never know to collect it. {% endhint %} #### Knowledge What the agent is allowed to know and say. * **Business info** — free-text background: service area, pricing approach, anything the agent should reference. * **Services** — a short list of what you offer. * **FAQs** — question/answer pairs the agent answers verbatim from. * **Answer from knowledge only** — keep this on. The agent escalates ("let me connect you") instead of inventing answers it doesn't have. #### Voice How the agent sounds. | Field | What it does | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Language** | A curated list — each language uses a hand-picked, natural-sounding voice. | | **AI model** | The brain behind the agent. Leave it on **Use account default** unless a flow needs something specific — see **Choosing a model** below. | | **Voice** | The ElevenLabs voice the agent speaks in (defaults to the language's curated voice). Loads from your own key. | | **Barge-in sensitivity** | How easily the caller can interrupt the agent mid-sentence (Low / Medium / High). | | **Welcome greeting** | The agent's opening line. The AI disclosure is automatically spoken **before** this greeting. | {% hint style="info" %} **Choosing a model.** Leave it on **Use account default** unless a flow needs something specific. Otherwise pick by use case — faster models start speaking sooner, smarter ones handle complexity better: * **Fast & Cheap** — simple, scripted calls: FAQs, basic reception, high volume. * **Balanced** *(Recommended)* — the everyday all-rounder: booking, qualifying, and most support calls. * **Smart & Snappy** — objections and light troubleshooting, while staying responsive. * **Smartest** — complex or regulated calls where accuracy matters most (a touch slower to respond). {% endhint %} #### Actions What the agent is allowed to do. Branch-producing actions add their output port on the canvas automatically. | Action | What it does | Port it adds | | --------------------- | -------------------------------------------------------------------- | -------------------------------- | | **Set outcome** | Lets the agent qualify or disqualify the lead, or flag spam. | Qualified / Not Qualified / Spam | | **Book appointment** | Books a real slot on your connected calendar. | Booked | | **Transfer to human** | Hands the call to your team with a spoken context summary. | Wants Human | | **Capture field** | Saves extracted details (name, budget, …) onto the call and contact. | — | | **Add tag** | Tags the call, visible in Call History, webhooks, and reports. | — | | **Send SMS** | Fires a text mid-call (e.g., a booking link). | — | | **End call** | Ends the conversation politely. | — | Two related sections live on this tab: * **Transfer** — choose **Connected node (wire the Wants Human port)** to route transfers through your flow (recommended), or **Specific number** to dial a fixed number. Turn on **Speak context summary to the agent** so your team hears a short AI-generated whisper ("Caller wants a roof estimate, budget $8k") before being connected. * **Attribution context** — inject the campaign, ad source, and keyword into the agent's awareness so it can acknowledge what the caller responded to ("Thanks for calling about the summer promo"). #### Safety Guardrails and compliance. | Setting | What it does | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Confidence threshold** | If the agent qualifies a lead with confidence **below** this number, the call routes to the **Low Confidence** port instead — and no conversion fires. | | **Max turns** | Hard cap on conversation length. | | **Wants-human phrases** | Comma-separated phrases ("talk to a person, human") that immediately trigger a transfer. | | **Spam screening** | Detects robocallers and routes them to the **Spam** port — without ever creating a contact. | | **AI disclosure** | The legally-important opener telling callers they're speaking with AI. **Always on — cannot be disabled.** The wording is editable. | | **Recording** | **Inherit from flow** (default) or **Off**. | {% hint style="danger" %} **The AI disclosure is mandatory.** The FCC treats AI voices as "artificial or prerecorded", so every AI call opens with your disclosure text, spoken in the agent's own voice as the first sentence of the greeting. You can edit the wording, but you can't remove it — publishing enforces it. {% endhint %} *** ### Output Ports — and How to Wire Them Every AI conversation ends on exactly one port. Three are **required** before you can publish; the rest are recommended. | Port | When it fires | Wire it to… | Required? | | ------------------ | ------------------------------------------------------------------- | ----------------------------------- | ------------------------- | | **Qualified** | The agent qualified the lead at or above your confidence threshold. | Hangup with a farewell, or a Dial | ✅ Required | | **Wants Human** | The caller asked for a person, or the agent decided to transfer. | Dial, Round Robin, or Agent Queue | ✅ Required | | **Error** | Something went wrong mid-conversation. | Dial or Voicemail (a safe fallback) | ✅ Required | | **Booked** | An appointment was actually created on your calendar. | Hangup with a confirmation message | ✅ When booking is enabled | | **Not Qualified** | The agent determined the lead isn't a fit. | Hangup | Recommended | | **Spam** | Spam screening caught a robocaller. | Hangup | Recommended | | **Low Confidence** | Qualified, but below your confidence threshold. | Dial or Voicemail for human review | Recommended | | **No Input** | The caller never spoke. | Voicemail or Hangup | Recommended | {% hint style="info" %} **Errors block publishing; recommendations don't.** Leaving a required port unwired shows a red **"AI Agent is incomplete"** toast and blocks the publish. Leaving a recommended port unwired publishes fine, but you'll see a **"Published — AI Agent has recommendations"** notice — an unwired recommended port ends the call with a plain hangup, which usually isn't what you want. {% endhint %} *** ### Appointment Booking The agent can book real appointments during the call — and it only ever confirms a time **after** the event is actually created on your calendar, so it can't promise slots that don't exist. {% hint style="info" %} **How booking works on a call.** The agent reads the date and time back to the caller and waits for a clear "yes" before it books anything — so a misheard time never lands on your calendar. If the requested slot is already taken, it says so and offers another time. Appointments are created in your **workspace's timezone**, so make sure that's set to your local zone for times to land correctly. {% endhint %} #### Connect Google Calendar {% stepper %} {% step %} #### Open the Integrations hub Go to **Settings > Integrations**. Find the **Google Calendar** card — *"Let the AI agent book real appointments on your calendar during a call."* {% endstep %} {% step %} #### Connect with Google Click **Connect with Google** and approve calendar access. Once connected, the page shows **"Connection is healthy"** with the Google account and calendar in use (your **primary** calendar by default). {% endstep %} {% endstepper %}

The Google Calendar card in Settings → Integrations, connected and healthy

#### Enable booking on the node {% stepper %} {% step %} #### Turn on the action In the AI node's **Actions** tab, enable **Book appointment**. This adds the **Booked** port to the node. {% endstep %} {% step %} #### Configure the Booking section * **Provider** — Google Calendar * **Calendar ID** — leave blank for your primary calendar, or paste a specific calendar's ID * **Duration (minutes)** — the slot length the agent offers * **Confirm via SMS** — text the caller a confirmation after booking {% endstep %} {% step %} #### Wire the Booked port Booking enabled = **Booked port required**. Wire it to a Hangup with a confirmation farewell. Publishing fails until both the calendar is connected and the port is wired. {% endstep %} {% endstepper %} {% hint style="warning" %} **Calendly appears in the provider list but isn't available yet.** Selecting it currently blocks publishing — use Google Calendar. {% endhint %} {% hint style="success" %} **Booked appointments count as conversions.** A successful booking records a conversion the same way a qualified lead does — including the Google Ads upload when your [Google Ads integration](/guides/google-ads-integration.md) is connected. {% endhint %} *** ### Testing with a Real AI Call Simulation mode covers flow logic, but an AI conversation needs a **real call**. The **Test call** button on the toolbar places one — from your browser, no phone needed. {% stepper %} {% step %} #### Start the test Click **Test call** (next to Simulate). The **AI test call** panel opens — *"Placing the test call — allow microphone access if prompted…"*. Allow the microphone and wait for the status badge to switch to **Live**. {% endstep %} {% step %} #### Talk to your agent Speak normally through your browser. The panel shows the **live transcript** (Agent / Caller turns, with the agent's per-reply response time), and the canvas highlights the AI node while the conversation runs. {% endstep %} {% step %} #### Review the result When the call ends, the chosen outcome port lights up on the canvas and the panel shows the full result: **Outcome** (with confidence), **Captured** fields, and the **Tool calls** the agent made. {% endstep %} {% step %} #### Save it as your passing scenario Click **Save as scenario** to record this run as the flow's "last green" test. The editor badge flips from **Not test-verified** to **Test-verified** — and to **Edited since last test** if you change the flow afterwards, reminding you to re-test. {% endstep %} {% endstepper %}

The AI test call panel with a live transcript and the post-test outcome summary

{% hint style="info" %} **Test calls are invisible to your data.** They never create contacts, never fire conversions, and are excluded from every analytics surface and the public status page. They do use real Twilio/OpenAI minutes on your own accounts (a few cents per test). {% endhint %}
Strict mode — require a passing test before every publish For regulated teams (or during your rollout), workspace admins can turn on strict mode so AI flows can't be published without a saved passing test: 1. With strict mode on, publishing an AI flow without a fresh saved scenario fails with: *"Strict mode is on for this workspace: run a passing test call and save it before publishing this AI flow."* 2. "Fresh" means the saved test matches the current draft — any edit after the test puts the badge into **Edited since last test** and re-blocks publishing until you re-test and re-save. 3. The publish check never places a call by itself; it only reads your last saved scenario, so provider hiccups can't block a publish on their own.
*** ### What Happens on a Live Call 1. **The agent answers** — disclosure first, then your welcome greeting, in your chosen voice. 2. **The conversation runs** — the agent works through your objectives, answers from your knowledge, and captures fields as the caller volunteers them. Callers can interrupt mid-sentence. 3. **Spam never pollutes your CRM** — a screened robocall routes to the Spam port and **no contact is created**. 4. **Real callers become contacts** — once the conversation ends on a real outcome, the contact is created (or matched) and the AI-captured details are saved on it, kept separate from fields your team entered by hand. 5. **Qualified means conversions** — a qualified outcome (at or above your confidence threshold) marks the call qualified and feeds the same conversion pipeline as manual qualification, including [Google Ads conversion uploads](/guides/google-ads-integration.md). 6. **The flow continues** — whatever node you wired to the outcome port takes over: dial your team with a context whisper, send the SMS, or hang up politely. *** ### Where AI Shows Up in Your Data #### Call History On **Analytics > Call Activity**, every AI-handled call gets an **AI Agent** badge column showing its outcome (Qualified, Wants human, Spam, …). Two filters slice the list: * **AI Handled** — yes/no: only AI calls, or only human-handled calls. * **AI Outcome** — pick one or more specific outcomes (e.g., just Spam and Error).

Call Activity filtered to AI-handled calls, with the AI Agent outcome column

Open any call's details: * The **Details** tab gains an **AI Agent** section — the outcome with its confidence, every captured field (name, budget, reason…), and the agent's one-line call summary. * The **Recording** tab shows the full **AI Conversation** — every Agent/Caller turn with the agent's response time — even when no audio was recorded.

The AI Agent section in a call's details: outcome, captured fields, and summary

#### Flow Analytics (per flow) The **Flow Analytics** panel in the editor gains an **AI Agent** section with a card per AI node: | Metric | What it tells you | | ---------------------- | -------------------------------------------------------------------------------------- | | **Resolution** | Share of conversations the agent fully handled without a human or an error | | **Qualified / Booked** | Qualification and booking rates | | **Transfer** | How often callers were handed to a human | | **Spam blocked** | Robocalls screened out | | **Outcome bar** | Every outcome with its count — including escalations (Low confidence, No input, Error) | | **Avg turns** | Average conversation length in agent replies | | **Avg / P95 latency** | How fast the agent responds; flagged amber above 1s and red above 1.4s | | **Confidence** | Average qualification confidence with a distribution chart |

The AI Agent section of the Flow Analytics panel: rates, outcome distribution, turns, latency, and confidence per node

#### Analytics → AI Agent (whole workspace) The **AI Agent** page under Analytics rolls the same metrics up across **every flow**: summary cards (with period-over-period change when comparison is on), then a table with one row per flow — click a row to expand its per-node cards. Flows with an AI node that received no AI calls in the range still appear with a *"No AI sessions in this range"* note, so a freshly published flow is never invisible. Date, campaign, source, and medium filters work like every other analytics page.

The Analytics → AI Agent page: summary cards and the per-flow breakdown table

*** ### Monitoring & Alerts Ring Tonic watches your agent's response speed continuously. If the 95th-percentile response gap degrades past \~1.4 seconds over the recent window, workspace admins receive an email — **"AI Agent Response Time Degraded"** — with the measured latency and what to check: * Your OpenAI account status and rate limits * The model selected on the AI node (a faster model improves latency) * Very large knowledge/FAQ blocks, which slow every reply Alerts are throttled to at most one per hour per workspace. *** ### Troubleshooting | Problem | Fix | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "No ElevenLabs voices found" on the Voice tab | Add your ElevenLabs API key in the workspace's **Voice & Audio** settings, then reopen the panel. | | **"AI Agent is incomplete"** when publishing | A required port (Qualified, Wants Human, Error — plus Booked if booking is on) is unwired, or the system prompt / disclosure text is empty. The toast lists exactly what's missing; click **Open** to jump to the node. | | Publish blocked mentioning a calendar | **Book appointment** is enabled but no Google Calendar is connected — connect it under **Settings > Integrations**, or disable the action. | | Publish blocked by strict mode | Run a **Test call**, get a passing result, click **Save as scenario**, then publish. | | Test call stuck on "Connecting…" | Allow microphone access in your browser, and confirm your Twilio credentials are valid in workspace settings. | | Every call routes to the Error port | Usually a missing or invalid OpenAI API key — verify it under **AI Automation** in workspace settings, then place a test call. | | "AI Agent Response Time Degraded" email | See [Monitoring & Alerts](#monitoring-and-alerts) above. | *** ### Best Practices * **Write the system prompt like a job description** — who the agent is, what success looks like, what it must never do. * **Keep the knowledge tight.** Short, factual business info and FAQs beat long pasted pages — both for accuracy and response speed. * **Wire every recommended port.** Spam → Hangup and Low Confidence → a human reviewer turn "lost" calls into handled ones. * **Test after every meaningful edit.** The **Edited since last test** badge exists for a reason — conversations are sensitive to prompt changes. * **Start with transfer generous, tighten later.** Early on, let borderline calls reach your team; raise the confidence threshold once you trust the agent's judgment. * **Watch the AI Agent analytics weekly.** A rising transfer rate or falling resolution rate is your earliest signal that the prompt or knowledge needs attention. *** ### Related Guides {% content-ref url="/pages/nn3YnO9ibI1GirGOq05c" %} [Call Flow Builder](/guides/call-flow-builder.md) {% endcontent-ref %} {% content-ref url="/pages/crg7tMxXMDacQLAiSpgl" %} [Setup Workspace](/guides/setup-workspace.md) {% endcontent-ref %} {% content-ref url="/pages/tr9a9To8aNSbRTTJ3u8R" %} [Google Ads Integration](/guides/google-ads-integration.md) {% endcontent-ref %} {% content-ref url="/pages/FqrMOC4HeyPH7W0Eqtdm" %} [Analytics](/guides/analytics.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.ringtonic.app/guides/ai-call-answering.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.