Brackstone Voice AI — Client Onboarding Playbook

End-to-end process for taking a new client from signed contract to live voice AI receptionist.

Follow in order. Every step has a pass/fail check before you move on. Time to complete: 2–4 hours the first time, 45–60 minutes after practice.

1. Prerequisites

From the client — collect before you touch the dashboard

Paste this into a DM or email and wait for all answers before starting.

On your side

• Dashboard admin login (admin or platform_admin role)
• Retell dashboard access, API key in ~/.zshrc
• Twilio console (only if buying a new UK number)
• Stripe dashboard (for creating the subscription)

2. Pick the vertical

This controls which AI prompt analyses their calls and which columns render on the dashboard. Get it right or you'll be re-onboarding.

3. Build the Retell agent

3a. Start from the wiki prompt

Never write a prompt from scratch. Use the relevant template as a base:

3b. Fill the variables

Every template has {{variables}} at the top. Fill with the client's answers from §1:

• {{business_name}} — trading name
• {{agent_name}} — receptionist persona (default: Sophie)
• {{opening_hours}} — from intake form
• {{escalation_number}} — manager or owner mobile (NOT a client-supplied number mid-call)
• {{booking_url}} / {{menu_url}} / {{price_list_url}} — where applicable
• Vertical-specific extras ({{delivery_radius}}, {{minimum_order}}, etc.)

3c. Voice + first message

• Voice: female, warm, UK accent by default. Use /voice-ai-demo to pick a tone-matched voice.
• First message: "Thank you for calling {{business_name}}, this is {{agent_name}} — how can I help you today?"
• Keyboard-click ambient sound ON (masks latency, signals note-taking).

3d. Test in Retell playground

Before connecting to the dashboard, hit the Retell Test button and run three calls covering the client's top intents. The agent should:

• Greet correctly
• Capture name + phone accurately (caller reads phone back)
• Branch to the right flow (booking vs order vs emergency)
• Log any allergy or emergency verbatim

4. Create the project in the dashboard

1. Log in as admin. Go to /admin/projects.
2. Click Create Project.
3. Fill the form:

Click Create. You're redirected to the project detail page. Note the firm_id in the URL — you'll need it for webhooks and Stripe.

Custom industry fields (only if Industry = other)

Paste a JSON block like:

{
  "label": "Plumbing",
  "fields": [
    { "label": "Job Type", "type": "text" },
    { "label": "Postcode", "type": "text" },
    { "label": "Emergency", "type": "select", "options": ["Yes", "No"] }
  ]
}

Keep it to 3–5 fields. More than that and the dashboard table gets unreadable.

5. Wire the Retell webhook

1. Open the project detail page in the dashboard. Copy the Retell Webhook URL and Webhook Secret.
2. Go to the Retell agent you built in §3. Under Webhooks, paste:
   • URL: the one from the dashboard
   • Signing secret: the one from the dashboard
   • Events: tick call_ended and call_analyzed
3. Save.

Verify

Click Send test webhook in Retell. Within 10 seconds, a test row should appear at /calls for this project. If it doesn't:

• Check webhook secret matches.
• Check the Retell agent ID is bound to this firm in the DB.
• Tail Railway logs for webhook-retell signature mismatch or firm not found.

6. Assign a phone number

Option A — give them a fresh Brackstone number

1. Buy a UK local number in Twilio (match their area code).
2. Point the number's Voice webhook at the Retell inbound URL for this agent.
3. Give the client the number. They advertise / forward calls to it.

Option B — forward their existing number

1. Client sets up conditional forwarding (no-answer / busy) to a Brackstone Twilio number.
2. Twilio number → Retell agent binding as above.
3. Tell the client to keep their own number; calls route to AI only when they can't answer.

7. Billing setup

1. In Stripe, create a subscription for the firm using the agreed price ID.
2. On the dashboard, go to /admin/billing → Attach subscription to firm.
3. Confirm included minutes, overage rate, trial length match the contract.

Trial expiry: automated email + dashboard lockout. Document the trial end date in your CRM.

8. Smoke test before handover

Do not hand over until all of these pass.

Call the number yourself and run three scenarios from the client's vertical:

For each call, verify on /calls

• Call row appears within 30 seconds of hangup
• ai_analysis_status reaches done within 2 minutes
• Caller name + phone captured (or explicit null if not given)
• Correct ai_category for the scenario
• Vertical-specific fields populated (plumber: postcode + is_emergency; restaurant: party_size + dietary_requirements; etc.)
• Urgency score matches scenario (5 for emergencies, 1-2 for routine)
• Allergies or emergencies surface as red badges

9. Client handover

Send the client:

1. Dashboard login — email + temporary password. Link to /login.
2. 1-page cheat sheet — how to read the dashboard, where to find missed calls, how to mark a callback complete. Keep it under 10 bullet points.
3. Recording of one smoke-test call so they know what the AI sounds like.
4. WhatsApp/email channel for week-1 questions.

15-minute training call agenda

• Walk through the dashboard tabs (Calls, Queue, Clients).
• Show how urgency badges and red flags work.
• Show how to listen to a recording and read the transcript.
• Show where to update opening hours or the transfer number (if they can).
• Agree a weekly review cadence for the first month.

10. Week 1–2 refinement

Watch the live calls data. Expect to refine, not to be done.

Daily for the first week, weekly after.

• Columns always null → AI isn't capturing that field. Tweak the prompt or drop the column.
• Columns always wrong → prompt is mis-grounded. Read 5 transcripts and update the template.
• Wrong intents → add examples to the prompt's "Common Intents" section.
• Missed emergencies → tighten the urgency rubric in the prompt.

When to tweak vs leave alone

• Tweak if ≥20% of calls in a given intent show the same gap.
• Leave alone if it's a one-off. One weird caller isn't a pattern.

11. Troubleshooting — top failure modes

12. Reference

• Dashboard routes: /admin/projects (create), /calls (per-firm call log), /queue (callback queue), /admin/billing.
• Key files in this repo: lib/ai-worker.js, lib/verticals/*.js, routes/admin-onboarding.js, views/calls.ejs.
• AI prompt templates: wikis/domains/voice-ai/pages/prompts/.
• Vertical research: wikis/domains/voice-ai/pages/ (e.g. uk-trades-plumbers-electricians.md).
• Billing model: wikis/domains/voice-ai/pages/voice-ai-pricing-models.md.