Bland AI Phone Agent

The Bland AI page at /admin/bland manages AI-powered outbound phone calls. Unlike the Twilio module (which speaks pre-written text), Bland AI conducts full bidirectional conversations — you give it instructions like “book a table for 2 at 7pm” and it handles the entire call autonomously.

Architecture

Admin UI → /api/admin/bland-manage → Bland AI REST API
                                      ├── POST /v1/calls (create call)
                                      ├── GET /v1/calls (list calls)
                                      └── GET /v1/calls/:id (call detail + transcript)

All requests proxy through a single API route using Bearer token authentication.

Page Layout

Stats Row

Four stat cards:

API Status — connection health (OK/Error)
Total Calls — number of calls made
Completed — calls that finished successfully
Avg Duration — average call length in seconds

Make Call Tab

Form card with:

Phone Number — E.164 format (+15551234567)
Task / Instructions — what the AI should do on the call (up to 2000 chars). This is the core instruction — describe the goal, context, and any information the AI needs.
First Sentence — optional opening line the AI speaks immediately
Voice — dropdown of 6 preset voices: Josh, Florian, Derek (male), June, Nat, Paige (female)
Model — base (full features, recommended) or turbo (lowest latency, limited capabilities)
Max Duration — call timeout in minutes (default 5)
Record — checkbox to record the call audio (default on)
Call button with spinner feedback

Call History Tab

Table of recent calls showing Phone Number, Status (badge), Created date, Duration, and a View button.

Call Detail Tab

Full call information:

Phone number, status, duration, timestamps
Recording link (opens in new tab)
Full conversation transcript

API Route

Route: /api/admin/bland-manage

Auth: Admin-only (CF Access JWT validation)

GET

Health check — verifies Bland AI API connectivity.

POST Actions

Action	Parameters	Returns
`get-status`	none	`{ status }`
`make-call`	`phoneNumber`, `task`, `voice`, `model`, `firstSentence`, `maxDuration`, `record`	`{ success, callId, status }`
`list-calls`	`limit` (max 100, default 50)	`{ calls[], total }`
`get-call`	`callId`	`{ call }` (includes transcript, recording URL)

Environment Variables

Variable	Required	Description
`BLAND_API_KEY`	Yes	Bland AI API key (from app.bland.ai dashboard)

Voice Reference

Voice	Gender	Style
Josh	Male	Default, natural
Florian	Male	Professional
Derek	Male	Friendly
June	Female	Professional
Nat	Female	Conversational
Paige	Female	Friendly

Model Reference

Model	Latency	Features	Best For
`base`	Normal	Full tool use, knowledge bases, guard rails	Most calls
`turbo`	Fastest	Limited feature set	Quick simple calls

Setup

Create an account at app.bland.ai
Navigate to Settings → API Keys and generate a key
Set the environment variable:
- Local: add BLAND_API_KEY=sk-... to .env
- Production: npx wrangler pages secret put BLAND_API_KEY
Restart the dev server or redeploy

Bland offers 100 free calls/day on the developer plan. No credit card required to start.

Troubleshooting

API Status shows Error

Symptom: Stats row shows “Error”, calls fail with 401.

Fix: The BLAND_API_KEY is missing or invalid. Check .env (local) or CF Pages secrets (production). Get a fresh key from app.bland.ai → Settings → API Keys.

Call initiated but never connects

Symptom: Call ID is returned but phone never rings or drops immediately.

Fix: Verify E.164 format (+1XXXXXXXXXX). Try a known mobile number first. Free tier may restrict certain destinations. Check Bland dashboard for detailed call logs. If using turbo model, switch to base.

Transcript shows empty or partial

Symptom: Call completed but transcript in Call Detail is blank.

Fix: Bland AI generates transcripts asynchronously. Wait 30-60 seconds after the call ends, then click View again. Very short calls (under 5 seconds) may not generate transcripts.

Twilio Dashboard (/admin/twilio) — manual SMS and voice calls with pre-written text
Vapi Voice Agent (/admin/vapi) — programmable voice AI with pluggable LLM/voice providers
ElevenLabs (/admin/elevenlabs) — voice library and TTS playground