# Voice Booking Agent — Implementation Guide Version 0.3 This offline guide mirrors the ten-tab Implementation Manual on the demo website. Follow the chapters in order for a new installation. # What this system does This starter is an inbound AI receptionist for a service business. It answers only approved questions, checks live consultation availability, books after explicit confirmation, helps with an existing booking, and creates a human follow-up when it cannot complete the request safely. ## How the parts divide responsibility - **Retell AI** manages the real-time conversation, voice, intent routing, and approved tool calls. - **Cal.com** is the only booking authority. Its Google Calendar connection owns availability and conflict checking. - **n8n** handles authenticated booking changes, post-call processing, deduplication, owner alerts, and weekly reporting. - **Google Sheets** stores the operational Call Log and Exception Queue. - **Telegram and SMTP** notify the business owner without exposing full transcripts. ## What this starter includes - A native Retell import template plus a local preparation script. - Four inactive n8n workflows with visible `SET_*` placeholders. - A two-sheet operations workbook with fictional sample rows. - A signed-webhook verifier for the Retell-to-n8n boundary. - Twenty conversation simulations and a business-knowledge template. - This detailed implementation guide both online and inside the ZIP. ## Prerequisites You need a Retell AI account, a Cal.com account with an event type, a connected Google Calendar, n8n, a Google account for Sheets, and Node.js 18 or newer. Telegram and SMTP are required only if you want both owner notification channels. ## Honest status This is a documented prototype. The package structure, import preparation, payload contracts, and simulation cases are reviewed. A successful paid phone acceptance call is not claimed; complete the Testing chapter before describing your own installation as production-ready. --- # Download map ## Start with the complete bundle Download `voice-booking-agent-v0.3.zip` if you are installing the system. It contains every required workflow, template, script, workbook, guide, verifier, and manifest. The individual downloads are provided for inspection or replacing one file without downloading the full bundle again. ## Files you can import - `retell-native-import-ready.json` is the private file you generate locally and import into Retell. It is not shipped because it contains your Cal.com API key. - `00-voice-operations-error-handler.json` through `03-voice-exception-dispatcher.json` import into n8n. - `voice-booking-operations.xlsx` imports into Google Sheets. ## Files you do not import directly - `retell-native-import-template.json` contains placeholders. Run the preparation script first. - `retell-conversation-flow-blueprint.json` is a human-readable architecture reference, not a Retell import. - `retell-simulation-test-suite.json` is a test-case library, not an agent. - `retell-webhook-verifier-worker.js` is deployed to a Worker runtime; it is not imported into n8n. - `business-knowledge-template.md` is completed by the business owner and then used to update approved agent knowledge. ## Verify a download Open `release-manifest.json` to see the expected SHA-256 checksum and byte size for every bundled file. A changed checksum means the file is not identical to this release. ## Critical secret warning The preparation script creates `retell-native-import-ready.json` on your own computer. That generated file contains your Cal.com API key in plain text because Retell includes tool credentials in its native export shape. Import it, confirm Retell accepted it, then delete it. Never upload that private ready file to a website, Git repository, LinkedIn post, or shared drive. --- # Installation: start to finish Follow these steps in order. Keep every n8n workflow inactive until the test chapter tells you to activate it. ## 1. Prepare the accounts 1. In Google Calendar, choose or create the calendar that will hold consultations. 2. In Cal.com, connect that Google account and create one event type for the service. 3. In Retell AI, create an account with enough credit for dashboard audio testing. 4. Confirm n8n is reachable and that you can create Google Sheets, Telegram, and SMTP credentials. 5. Install Node.js 18 or newer and confirm `node --version` works. ## 2. Download and unzip Download the complete starter bundle. Extract it to a private folder. Do not work from a public cloud-synced or Git-tracked folder because the temporary Retell import will contain a secret. ## 3. Generate the private Retell import On macOS or Linux, open Terminal in the extracted folder and run: `CAL_API_KEY='your-cal-key' CAL_EVENT_TYPE_ID='123456' node prepare-retell-import.mjs` On Windows PowerShell, run these three commands: `$env:CAL_API_KEY='your-cal-key'` `$env:CAL_EVENT_TYPE_ID='123456'` `node .\prepare-retell-import.mjs` The script validates the two values and writes `retell-native-import-ready.json`. If it reports a missing placeholder, do not edit around the validation; correct the input and rerun it. ## 4. Import and personalize Retell 1. In Retell, create or open a Conversation Flow agent and choose Import. 2. Select `retell-native-import-ready.json`, not the template or architecture reference. 3. Save the imported agent immediately. 4. Replace every `[BUSINESS NAME]` reference. 5. Review the opening message, service scope, business hours, timezone, and human-handoff language. 6. Verify the two Cal.com tools described in the Retell chapter. 7. Delete `retell-native-import-ready.json` from your computer after the import succeeds. ## 5. Build the operations sheet 1. Upload `voice-booking-operations.xlsx` to Google Drive. 2. Open it with Google Sheets and save it as a Google Sheet. 3. Keep the tab names exactly `Call Log` and `Exception Queue`. 4. Copy the spreadsheet ID from the URL between `/d/` and `/edit`. 5. Remove the fictional sample rows only after confirming the column headers remain intact. ## 6. Import n8n and connect credentials 1. Import all four numbered workflow JSON files. 2. Create or select Google Sheets OAuth, Telegram, SMTP, and Cal.com HTTP Header Auth credentials. 3. Search each workflow for `SET_` and replace every placeholder. 4. Set workflow 00 as the Error Workflow for workflows 01, 02, and 03. 5. Save each workflow but keep it inactive. ## 7. Deploy the webhook verifier Deploy `retell-webhook-verifier-worker.js` to a supported edge Worker. Configure `RETELL_API_KEY`, `N8N_INGRESS_URL`, and `N8N_INGRESS_SECRET` in the platform secret store. Never paste those values into the JavaScript file. ## 8. Test before activation Run Retell Test LLM, Test Audio, the twenty simulations, and the n8n webhook tests in the Testing chapter. Activate workflow 00 first, then 01, 02, and 03. Attach a phone number only after the dashboard and webhook tests pass. --- # Retell AI setup ## Import the correct file Run `prepare-retell-import.mjs` and import the generated `retell-native-import-ready.json`. The shipped template is intentionally incomplete, and the architecture blueprint is intentionally non-importable. This separation keeps live credentials out of the public download. If an import opens with only a title or an empty canvas, do not continue. Confirm you used the generated ready file, rerun the preparation script, and inspect the import error before manually recreating nodes. ## Verify the conversation flow Open the imported agent and check that the major stages exist: greeting and disclosure, intent routing, FAQ handling, live availability and booking, existing-booking help, human handoff, and closing. Open each stage and confirm its transitions point to a valid next stage. ## Verify the Cal.com tools In the Live Availability and Booking stage, confirm both `check_availability_cal` and `book_appointment_cal` are attached. Check that: - Both tools use the intended numeric event type ID. - The API key field is populated but never displayed in screenshots or exports. - Availability is checked before a slot is offered. - The booking tool is called only after the caller repeats or confirms the selected time. - Success is spoken only when the tool returns a successful result. ## Personalize the agent Replace `[BUSINESS NAME]`, then use `business-knowledge-template.md` to add only verified services, opening hours, locations, prices you are permitted to quote, and escalation rules. Do not give the model permission to invent pricing, policies, availability, or booking success. For the starter configuration, keep English (US), an eight-minute maximum call, basic-attributes-only storage, and recording off. Select a voice that clearly handles names, email addresses, and dates in your audience's accent. ## Configure post-call analysis The post-call workflow expects fields for caller name, caller email, intent, outcome, booking UID, appointment start, appointment timezone, transfer status, success, follow-up need, and failure reason. Keep the field names aligned with the architecture reference. Do not add a full transcript field to Google Sheets. ## Save and publish safely Save after every material edit and reopen the agent once before testing; this confirms the dashboard persisted the flow. Duplicate the agent before major prompt changes so you can roll back. Never share a native Retell export after credentials have been added. ## First dashboard test Start with Test LLM. Ask for a known available day, select one returned slot, and explicitly confirm it. Then run Test Audio and repeat the path aloud. A Retell phone number is not required for these two tests. --- # Cal.com and Google Calendar Cal.com is the single source of booking truth. Google Calendar supplies the busy events, but Retell and n8n should not create a second calendar event independently. ## Connect Google Calendar 1. In Cal.com, open calendar settings and connect the Google account that owns the target calendar. 2. Choose which calendar receives new bookings. 3. Select every calendar that should be checked for conflicts. 4. Create or open the consultation event type. 5. Copy its numeric event type ID for the preparation script. ## Define the booking policy Set the event duration, available hours, business timezone, minimum notice, maximum booking window, buffer before and after meetings, attendee questions, and cancellation/rescheduling policy. Keep these rules in Cal.com so the voice agent cannot override them. ## Configure the event form Require the caller name and email address. Ask for a phone number only when the business needs it and has a clear retention policy. Avoid custom questions that the voice agent cannot reliably collect or that expose sensitive information. ## Calendar acceptance tests - Block one period in Google Calendar and confirm Retell does not offer it. - Test a time near midnight in the business timezone and in the caller's timezone. - Attempt two bookings for the same slot and confirm only one succeeds. - Confirm the event appears once in Google Calendar and once in Cal.com. - Cancel a test booking and confirm the calendar event is removed or updated according to policy. If availability differs between Cal.com and Google Calendar, fix the calendar connection, conflict calendars, timezone, and event policy before changing the agent prompt. --- # n8n workflows and credentials Import all four workflows, but configure and test them one at a time. ## Workflow 00: Operations Error Handler This receives n8n workflow failures and sends a sanitized Telegram alert. Select the Telegram credential and replace `SET_OWNER_CHAT_ID`. In workflows 01–03, open Settings and choose workflow 00 as the Error Workflow. ## Workflow 01: Booking Management Tool Gateway This authenticated webhook finds a booking and handles confirmed cancellation or reschedule requests. Replace `SET_VOICE_TOOL_SECRET`, select the Cal.com HTTP Header Auth credential, and expose the production webhook through HTTPS. Configure the matching Retell custom function to send the same secret in `X-Voice-Tool-Secret`. ## Workflow 02: Post-Call Processor This accepts only verifier-forwarded `call_analyzed` events, deduplicates them, masks the caller number, appends the Call Log, and creates an exception when follow-up is needed. Replace `SET_N8N_INGRESS_SECRET`, `SET_GOOGLE_SHEET_ID`, and the business timezone. Select Google Sheets credentials on both sheet nodes. ## Workflow 03: Exception Dispatcher and Weekly Summary This checks the Exception Queue every ten minutes and sends new exceptions to Telegram and owner email. It also sends a Monday summary. Replace `SET_GOOGLE_SHEET_ID`, `SET_OWNER_CHAT_ID`, `SET_OWNER_EMAIL`, and `SET_FROM_EMAIL`. Select Google Sheets, Telegram, and SMTP credentials. ## Credential checklist - Google Sheets OAuth can read and write the selected spreadsheet. - Telegram credential points to the intended bot, and the owner has sent `/start`. - SMTP can send from the configured From address to the owner address. - Cal.com HTTP Header Auth sends `Authorization: Bearer YOUR_KEY`. - The two random ingress/tool secrets are different and at least 32 bytes. ## Placeholder audit Use n8n search or inspect exported JSON and confirm no unresolved `SET_` value remains. Also confirm that no test webhook URL is saved in Retell; production integrations must use the production webhook URL. ## Activation order Activate workflow 00 first. Activate 01 and copy its production webhook to Retell. Deploy and test the verifier before activating 02. Activate 03 last, after one fictional exception row produces both owner notifications. --- # Security and privacy ## Secrets Generate two unrelated random secrets of at least 32 bytes: one for Retell booking-management functions and one between the verifier and n8n. Store API keys and secrets only in Retell credential fields, n8n credentials, or the Worker platform's secret store. The generated `retell-native-import-ready.json` contains your Cal.com key in plain text. Delete it after import. Never publish a configured Retell export, an n8n credential export, a Docker volume, or a screenshot showing credential values. ## Webhook boundary Retell sends the signed event to the verifier. The verifier validates the raw-body signature and forwards an authentic event to n8n with the private ingress secret. Do not point Retell directly at workflow 02 or remove this verification layer. ## Data minimization Recording is off by default. Do not write full transcripts to Google Sheets. Store masked caller identifiers and the minimum operational outcome needed for follow-up. Restrict the sheet to named operators and remove public link sharing. ## Retention The starter recommendation is 30 days for operational rows, unless the business has a documented legal or operational reason for a different period. Archive or delete old rows before the workbook exceeds roughly 2,000 active rows. ## Booking privacy The management gateway requires attendee email plus booking UID before a mutation. Never reveal another attendee's booking details. Transfer identity disputes, payment issues, health information, legal advice, and other sensitive requests to a person. ## Incident response If a key or generated import file is exposed, revoke and rotate the affected credential immediately, update every dependent integration, test again, and inspect Retell, n8n, Cal.com, and Worker logs for unexpected activity. --- # Test protocol Use fictional names, emails, and phone numbers throughout testing. ## Stage 1: Retell without phone spend 1. Run Test LLM for a normal booking, unavailable date, ambiguous date, FAQ, cancellation without confirmation, and human handoff. 2. Confirm the agent never invents availability, price, or booking success. 3. Confirm the booking tool runs only after explicit confirmation. 4. Run Test Audio and verify names, email addresses, dates, and timezones are understood. 5. Reopen the agent after saving to confirm the flow persisted. ## Stage 2: Calendar and n8n integration 1. Create one fictional booking in an available slot and verify it appears once. 2. Repeat the same post-call event and confirm workflow 02 writes only one Call Log row. 3. Send an invalid ingress secret and confirm workflow 02 performs no processing. 4. Create a fictional exception and confirm workflow 03 sends both Telegram and owner email. 5. Trigger a controlled n8n failure and confirm workflow 00 sends a sanitized alert. 6. Test find, reschedule request, and confirmed cancellation through workflow 01. ## Stage 3: Simulation suite Run all twenty cases in `retell-simulation-test-suite.json`. Record the actual result for each case. Any failure involving false availability, an unconfirmed booking change, leaked private data, or a missing human handoff blocks release. ## Optional paid acceptance call Only after Stages 1–3 pass should you attach a Retell phone number and place one controlled call using your free credit. Call from a number you control, book a test slot, verify the calendar and sheet, then cancel the booking. ## Release pass criteria - All conversation transitions persist after reopening Retell. - Availability and booking results match Cal.com. - No calendar event is duplicated. - Invalid webhook secrets are rejected. - Duplicate call events create one row. - Telegram and owner email arrive with masked data. - No unresolved `SET_*` placeholder remains. - No credential appears in the public package or screenshots. --- # Operate and troubleshoot ## Daily and weekly routine Review the Exception Queue each business day. Resolve each `OPEN` item with a short resolution note and updated status. Review the Call Log weekly for repeated failure categories. Compare the automated Monday summary with the sheet before using it in business reporting. ## When Retell appears empty after reopening Confirm the agent was saved, verify you imported `retell-native-import-ready.json`, and inspect Retell's import error. Do not assume a visible agent title means the flow imported. Reimport into a new draft if the node canvas is incomplete. ## When calendar tools fail Check the Cal.com API key, event type ID, event status, connected Google Calendar, conflict calendars, and timezone. Retry no more than once during a call; then apologize and create a human follow-up. ## When post-call rows do not appear Check Retell webhook delivery, verifier logs, signature validation, the n8n production webhook URL, ingress-secret equality, workflow activation, Google Sheets credentials, spreadsheet ID, and exact tab names. ## When notifications fail For Telegram, confirm the owner sent `/start`, the chat ID is correct, and the selected credential uses the intended bot. For email, verify SMTP host, port, encryption mode, sender authorization, and spam/quarantine folders. ## Safe replay and recovery Replay only the failed Retell webhook event. Workflow 02 uses `retell:CALL_ID:call_analyzed` as its event key, so an identical replay should not create a second row. Do not manually duplicate sheet rows to compensate for a failed notification. ## Maintenance Rotate credentials after suspected exposure, review provider changes before upgrading nodes, export sanitized backups after major edits, and rerun the acceptance checklist after any prompt, tool, event-policy, or workflow change. --- # Customize safely ## Business identity and knowledge Complete `business-knowledge-template.md` with verified services, hours, locations, pricing rules, FAQs, escalation contacts, and prohibited topics. Replace the sample consultation wording and every `[BUSINESS NAME]` token. ## Calendar policy Change duration, notice, buffers, timezone, and availability in Cal.com—not in multiple prompts or workflows. If you add a second event type, build an explicit event router and test every route. Do not let the model choose an arbitrary calendar or event type. ## Conversation changes Add a new intent only when it has a defined entry condition, allowed tools, successful outcome, failure outcome, human fallback, and simulation case. Keep spoken confirmations short and repeat the date, time, timezone, name, and email before a booking write. ## Notifications You can replace Telegram or SMTP with another provider, but keep owner alerts separate from caller-facing messages and preserve masked identifiers. If you remove one notification channel, disconnect its node cleanly and update the test checklist. ## Custom form fields If your Cal.com event requires additional attendee answers, add matching variables to the Retell booking tool and test how the agent collects, confirms, and sends each value. Optional business questions should have a safe default; required fields must never be silently omitted. ## Production readiness review After customization, rerun all twenty simulations, the calendar conflict tests, webhook authentication tests, duplicate-event test, notification test, and one controlled end-to-end call. Update the version number and release manifest before distributing your customized package.