Voice Booking Agent

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.