AI Receptionist (Bland)

Turn a Twilio phone number into a 24/7 AI receptionist that picks up on the first ring, qualifies the caller, answers your FAQs and can book a deposit before the call ends.

Step 1: Get your Bland API key

The API key is what lets this CRM tell Bland to answer calls on your behalf.

1. Log in to app.bland.ai.
2. Click the profile menu bottom-left, then Settings.
3. Open the API Keys tab.
4. Click Create new key. Name it crm-production so you can recognise it later.
5. Copy the key. It starts with sk-. Bland only shows this once. Paste it into a password manager immediately.

Step 2: Paste the key into the CRM

1. In the CRM go to Settings > Integrations.
2. Scroll to the Bland.ai - AI Calling card.
3. Paste the key into the API Key field.
4. Optional: fill in the Caller ID (outbound number). This is the number shown when the receptionist itself makes outbound calls (for callbacks). If you leave it blank, outbound calls will use Bland's default pool number, which some carriers flag as spam.
5. Click Save company at the bottom of the tab.

Step 3: Link Twilio to Bland

Bland needs your Twilio credentials so it can answer calls on your Twilio number. The CRM has a one-click bridge for this. It calls POST /api/calls?action=link_twilio and Bland's /v1/accounts endpoint to register your Twilio account under Bland with an encrypted account key.

1. Confirm both the Twilio Account SID and Auth Token are populated in the Twilio card above.
2. Go to Receptionist in the main navigation.
3. Click the Link Twilio to Bland button at the top of the page.
4. Wait for the green tick. If you get Twilio credentials not found, save the Twilio card first and try again. If you get Bland.ai API key not configured, re-check the paste in step 2.

Step 4: Point the Twilio number at Bland

Now the CRM knows about Bland and Bland knows about Twilio. You still need to tell Twilio that this specific number should be answered by Bland.

1. Log in to console.twilio.com.
2. Go to Phone Numbers > Manage > Active numbers and click the number the receptionist should answer on.
3. Scroll to Voice Configuration.
4. Set A call comes in to Webhook.
5. Paste the Bland inbound webhook URL: https://api.bland.ai/v1/inbound/{your_bland_agent_id}. You get the agent ID after step 5.
6. Set HTTP method to POST.
7. Click Save configuration.

Step 5: Build the receptionist agent

In the CRM's Receptionist page, fill in each field carefully. These are the settings that actually shape what your caller hears.

Voice

Pick a voice from the dropdown. Six recommended options:

• maya - warm, female, mid-Atlantic. Good default for consumer.
• ryan - male, British. Good for professional services in the UK.
• june - female, US Southern. Warm, works well for hospitality.
• florian - male, US neutral. Corporate feel.
• mason - male, deeper. Good authority for legal or finance.
• alena - female, Eastern European. Distinctive; not for everyone.

Ring your own number after you save and listen. If it sounds robotic in the first 30 seconds, change the voice. Do not trust the preview in the dashboard, it is smoother than the real call.

Tone

One line, plain English. Bad: professional yet friendly. Good: Confident local expert. Never uses jargon. Laughs politely when the caller makes a joke. Assumes the caller is busy.

Pace

Numeric 0.7 (slow) to 1.3 (fast). Default is 1.0. Rules of thumb:

• Older audience (60+) → 0.85. Elderly callers lose the first three words if you go faster.
• Younger urban audience → 1.1. Sounds less like a bot.
• Complex product where callers take notes → 0.9.

Welcome message

This is the very first thing the caller hears. Keep it under two seconds. Do not say the word "AI" or "assistant". Do not ask "how can I help you" until after you have identified yourself.

Template that works:

Hi, thanks for calling {business name}, this is {receptionist name}. How can I help?

Anti-example: "Welcome to the Acme Corporation, home of premium widgets since 1997. I am the AI virtual assistant. Please state the nature of your call after the tone." No one waits through that.

Knowledge base (7 structured sections)

The knowledge base is split into seven labelled sections. Each section takes up to 8,000 characters, giving you a total working capacity of 56,000 characters. Empty sections are dropped from the prompt entirely, so you only pay for what you actually fill in.

The receptionist reads all sections on every call. Structure matters: the labels give the AI a stronger sense of what belongs where, so it stops confusing a policy with a price and stops inventing services you don't offer.

What goes in each section

About the business

Two or three paragraphs the AI can use to introduce you. What you do, who you serve, what makes you different, how long you've been trading. This is the section the AI reaches for when a caller asks "what actually is this place".

Services and offerings

Every service, treatment, product, tour, or offering you sell. Include names and one-line descriptions. Keep to one item per line where you can, it's easier for the AI to quote back accurately.

Pricing

Prices, packages, deposits, discounts, VAT policy. If you charge differently for weekends, peak season, or emergency call-outs, say so here. If a price is "on request", write "POA" so the AI doesn't invent a number.

Frequently asked questions

The questions callers actually ask, formatted as Q: ... and A: .... Start with your top ten. Add more as calls surface new ones.

Policies

Cancellations, refunds, deposits, no-shows, late arrivals, dress code, minimum age, health restrictions. Anything a caller might argue about after the fact belongs here so the AI can quote you back.

Team and staff

Who works there, their roles, their specialisms. This is what lets the AI say "let me get you Sarah, she handles new patient consults" instead of "I'll pass you to someone".

Directions and parking

Full address, nearest transport, parking notes, accessibility, opening hours. Every call that ends with "and where are you again" is a call where this section was left blank.

Worked example 1: tour operator

== ABOUT THE BUSINESS ==
Rave Tours runs curated small-group city breaks to Ibiza, Berlin
and Amsterdam, aimed at 25-40s who want the nightlife without the
hostel chaos. Founded 2019, based in Manchester. Groups of 8-12
with a resident guide. ATOL protected (ATOL 12345).

== SERVICES AND OFFERINGS ==
Ibiza Weekender (3 nights): return flights, boutique hotel, guided
club nights at DC-10, Amnesia and Hi.
Berlin Techno Long Weekend (4 nights): return flights, apartment
stay in Kreuzberg, guest-list entry to Berghain queue-skip nights.
Amsterdam Canals and Clubs (3 nights): Eurostar plus canal-side
hotel, day trips and two nights at Shelter and De School.
Private group bookings (10+): bespoke itineraries, quotes on request.

== PRICING ==
Ibiza Weekender: from £549 per person, £150 deposit, balance
due 8 weeks before departure.
Berlin Techno Long Weekend: from £629 per person, £150 deposit.
Amsterdam Canals and Clubs: from £489 per person, £150 deposit.
Peak dates (Aug bank holiday, NYE): +£120 per person.
No hidden fees, no fuel surcharges. ATOL protection included.

== FREQUENTLY ASKED QUESTIONS ==
Q: Do I need to book flights separately?
A: No, flights are included in the price. We book them once
your deposit is paid.

Q: Can I share a room with a friend?
A: Yes, we ask when you book. Solo travellers get matched with
a same-gender room-mate or can pay a single supplement (£80-£140
depending on the trip).

Q: What if a club is closed on my date?
A: We swap in an equivalent venue and let you know at least 4
weeks before departure.

== POLICIES ==
Deposit: £150 per person, non-refundable after 14 days.
Balance: due 8 weeks before departure.
Cancellation: within 14 days of booking, full refund (minus £25
admin). After that, deposit lost. Under 8 weeks, no refund but
we'll try to transfer your place to a friend.
Minimum age: 21 for all trips. Photo ID required at hotel.

== TEAM AND STAFF ==
Josh Bevan (Founder, Manchester office): main point of contact
for bookings and pre-trip questions. Weekdays 10-6.
Marta Silva (Ibiza resident guide): meets Ibiza groups at the
airport, on WhatsApp throughout the trip.
Jonas Weber (Berlin resident guide): same, based in Kreuzberg.

== DIRECTIONS AND PARKING ==
Office: 42 Deansgate, Manchester M3 2FN.
By train: 4 min walk from Manchester Deansgate station.
Parking: NCP Great Northern (5 min walk), £4/hour.
Open Mon-Fri 10am-6pm, Sat by appointment.

Worked example 2: physiotherapy clinic

== ABOUT THE BUSINESS ==
Bridge End Physio is a family-run clinic in central Leeds,
established 2011. We treat sports injuries, chronic back pain
and post-op rehab for patients of all ages. Our team of four
HCPC-registered physiotherapists sees around 60 patients a week.
Known locally for hands-on manual therapy and for taking time
to explain what's happening, rather than rushing you through
in 15 minutes.

== SERVICES AND OFFERINGS ==
Initial physio assessment (60 min): full history, examination,
diagnosis and treatment plan.
Follow-up physio session (30 min): hands-on treatment plus home
exercise updates.
Sports massage (60 min): deep tissue work for runners and gym-goers.
Acupuncture add-on (15 min): can be added to any session for
chronic pain.
Post-op rehab programme: 6 or 12 session packages for knee,
hip or shoulder recovery.

== PRICING ==
Initial assessment: £65 (60 min).
Follow-up session: £45 (30 min).
Sports massage: £55 (60 min).
Acupuncture add-on: £15.
6-session rehab package: £240 (saves £30), paid up front.
12-session rehab package: £450 (saves £90), paid up front or
in two instalments.
No VAT (healthcare exempt). Card, cash or bank transfer accepted.

== FREQUENTLY ASKED QUESTIONS ==
Q: Do I need a GP referral?
A: No, you can book directly. Bring any scans or reports if
you have them.

Q: Do you take BUPA or AXA?
A: We're recognised by BUPA, AXA, Vitality and Aviva. You'll
need your authorisation code before your first visit.

Q: How soon can I be seen?
A: Usually within 48 hours for a first appointment. Same-day
sometimes possible.

== POLICIES ==
Cancellation: 24 hours notice required. Under 24 hours is
charged at 50% of the session fee.
No-show: full session fee charged.
Late arrival: your session ends at the scheduled time (we
can't run over).
Minimum age: 16 for solo appointments. Under 16s must be
accompanied by a parent or guardian.
Refunds on packages: pro-rata refund on unused sessions within
90 days of purchase.

== TEAM AND STAFF ==
Sarah Patel (Clinic Director, MCSP): 15 years, specialises in
chronic back pain and post-op knee rehab. New patients Mon-Wed.
James Okoro (Senior Physio): sports injuries, runners, cyclists.
Wed-Sat.
Hannah Liu (Physio): women's health, pre and post-natal. Tue and Thu.
Dan Wright (Sports Massage Therapist): 60 and 90 min appointments.
Weekends only.

== DIRECTIONS AND PARKING ==
Address: 14 Bridge End, Leeds LS1 4DJ.
Nearest station: Leeds City, 8 min walk.
Buses: 4, 16, 28, 51 all stop on Bridge End.
Parking: two-hour free bays on Bridge End (metered after 6pm).
Q-Park Criterion Place is 3 min walk, £3/hour.
Accessibility: step-free access from the street, accessible
loo, treatment rooms on ground floor.
Opening hours: Mon-Fri 8am-8pm, Sat 9am-2pm, closed Sunday.

Escalation notes

If you had escalation logic in the old single textarea (e.g. "if caller mentions injury, transfer to..."), keep that in Policies under a heading like "Escalation and transfers". The prompt-builder reads all sections on every call so it's picked up either way, but Policies keeps it near the cancellation and refund rules where it belongs.

Deposit config

If you want the receptionist to take a deposit before ending the call, fill in the deposit amount (e.g. 20), currency (e.g. GBP) and Stripe payment link URL. The receptionist will send the caller an SMS with the payment link when they agree to book. Do not enable this until you have already tested the flow end to end without a deposit for at least a week, callers being asked for money by an AI before they have met you converts poorly.

Step 6: Activate

1. Click Save agent. The CRM POSTs the config to Bland and returns the new agent ID.
2. Copy the agent ID from the confirmation banner. It is a UUID like a1b2c3d4-e5f6-7890-abcd-ef1234567890.
3. Go back to the Twilio number webhook you configured in step 4 and paste https://api.bland.ai/v1/inbound/<that_uuid> into the voice URL.
4. Click Save configuration in Twilio.
5. Toggle the Active switch in the Receptionist page to green.

How to test it works

1. Call the Twilio number from your own mobile. The receptionist should pick up in under two rings.
2. Ask a question that is in your knowledge base ("what are your hours?"). Verify the answer matches.
3. Ask a question that is not in your knowledge base ("do you offer wedding photography?"). Verify it says it will have someone call you back, does not hallucinate a service you do not offer.
4. Say the escalation trigger phrase ("I want to speak to a manager"). Verify the call transfers to your escalation number.
5. Go to Calls in the main nav. The call should appear as an inbound call within 30 seconds of hanging up, with a transcript.

Common problems

Caller hears a Twilio error message ("An application error has occurred")

The Twilio voice webhook URL is wrong or the Bland agent has been deleted. Re-copy the URL from step 6.3 and confirm you have not accidentally added a trailing space in Twilio.

Receptionist picks up but says nothing for 5-10 seconds

Welcome message is too long or you have selected a voice that has a slow warm-up (florian is the worst offender). Shorten the welcome to under 12 words and switch to maya or ryan to compare.

Receptionist repeats itself or misunderstands the caller

Pace is too fast for the caller's audio quality. Drop the pace to 0.9. If it still repeats, the caller is on speakerphone in a noisy environment and there is little you can do, the transcript will show it heard fragments and asked for clarification, which is the correct behaviour.

Caller gets asked for a deposit before the receptionist has even quoted a price

You enabled deposit config before running your knowledge base through a test call. Disable deposit, re-tune the knowledge base so the price is stated first, then re-enable.

Bland shows "no active phone number linked" error

The Twilio link step (step 3) failed silently. Go back to Receptionist and click Link Twilio to Bland again. Check the browser console for the actual error from /api/calls?action=link_twilio.

Calls hang up mid-sentence

Bland account has run out of credit. Add a card, top up 20 dollars. This happens more often than you would think.

What happens after the call: the follow-up sequence

Every call that ends without a booking now triggers a configurable four-step follow-up. If the caller books later on any channel the whole sequence auto-cancels. Owners see per-call status on the Calls page and can pause any contact in one click.

Default cadence out of the box:

• Step 1 (2 minutes after the call) - short SMS acknowledging you missed each other and inviting a reply or self-serve booking.
• Step 2 (2 hours later) - light nudge SMS.
• Step 3 (24 hours later) - email with a full recap, the booking link and an unsubscribe footer.
• Step 4 (3 days later) - final SMS. Reply YES to re-engage or STOP to opt out.

Configure everything on the Receptionist page under the new Follow-up sequence tab. You can:

• Toggle the whole sequence on or off.
• Set business hours and days so nothing sends at 3am. Anything scheduled outside your hours is deferred to the next available window.
• Edit each step's delay, template and (for emails) subject line.
• Insert placeholders like {name}, {issue}, {book_link}, {business_name}, {owner_name}. Missing values fall back to safe defaults (there for name, your enquiry for issue).
• Preview and test-send each step to a phone number or email you nominate.

Cron setup

The follow-up worker is a lightweight endpoint at /api/cron_followup.php that processes any queue rows that are due. You need to pick a shared secret and configure your host's scheduled task system to hit it every 5 minutes.

1. Open config/bootstrap.php and add a line like define('CRON_SECRET', 'pick-a-long-random-string'); (or set the CRON_SECRET environment variable in cPanel).
2. In BitHoarders / cPanel > Cron Jobs add a job that runs every 5 minutes: curl -s "https://yourdomain.com/api/cron_followup.php?key=YOUR_SECRET" > /dev/null
3. Confirm it runs by inserting a test row into receptionist_followup_queue with next_action_at = NOW(), then hitting the endpoint manually in your browser with the ?key= query set. You should see a JSON summary.

How to test end-to-end

1. Call the Twilio number from a mobile number that is not already a contact. Do not book anything, hang up.
2. Within about 30 seconds a new row appears in Calls with a follow-up pill reading Step 1 of 4.
3. Two minutes later (or on the next cron run inside business hours) you receive the step 1 SMS.
4. Reply STOP. Within moments the pill flips to Opted out and no further steps send.
5. Or, book yourself in via the booking portal instead. The pill flips to Cancelled (booked) and the sequence stops.

What this unlocks in the CRM

Every call now becomes structured data: a contact record with a full transcript, the phone number, the intent detected, and if a deposit was taken, a linked payment. The Calls page in the main nav lets you filter by disposition (booked, no answer, escalated, needs callback). The Pipeline module can auto-move contacts into a "hot lead" stage when the receptionist tags a call with ready_to_buy. And you get your evenings back.