Build an AI Pre-Visit Clearance Voice Agent with Telnyx

Patients often call before a visit to ask whether a procedure, test, or medication needs insurance clearance. That request is administrative, but it still creates real operational drag: staff need the patient's identity, the procedure, the provider, the insurer, urgency, and a callback trail.

This Telnyx code example shows the current way to build that intake flow with Voice API Call Control, Gather Using AI, AI Inference, and Messaging. The voice layer collects structured spoken information, the app classifies the request, and the patient gets an SMS confirmation.

The canonical code example: https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-pre-visit-clearance-voice-agent-python

What This Example Builds

A Python Flask app that:

• Answers inbound calls and verifies the patient by caller ID or DOB fallback
• Starts Telnyx gather_using_ai to collect the spoken pre-clearance request as structured fields
• Handles call.ai_gather.ended when Telnyx returns the collected result
• Classifies the request with AI Inference: procedure name, urgency, and type flags
• Confirms details with the patient before submitting
• Creates a structured clearance ticket for billing staff
• Posts a Slack alert with urgency and type tags
• Sends the patient an SMS with the ticket ID
• Handles inbound SMS as an alternative intake channel

How Telnyx Handles The Voice Intake

The call flow is built around Telnyx Gather Using AI. After the app answers the inbound call, it asks Telnyx to collect the clearance details it needs from the caller: what the request is for, which provider is involved, what insurance should be used, and whether anything sounds urgent.

That intake comes back to the Flask app as a call.ai_gather.ended webhook. From there, the backend has enough structure to continue the workflow: classify the request with AI Inference, confirm the details with the patient, create a clearance ticket, send an SMS confirmation, and alert billing staff.

The sample also includes the practical pieces you need around that flow. Call Control commands use command_id values so retries are safer, the answer command uses send_silence_when_idle for smoother call handling, and the app can still create a partial ticket if the caller hangs up after providing useful information.

The boundary is intentionally narrow. The agent does not give medical advice, diagnose, approve coverage, or deny coverage. It collects administrative intake data and routes it to the people who handle pre-visit clearance.

Architecture

patient calls
  -> Telnyx Call Control Application
  -> Flask /webhooks/voice
  -> call.initiated
  -> answer call
  -> gather_using_ai collects clearance details
  -> call.ai_gather.ended returns structured intake
  -> AI Inference classifies urgency and request type
  -> app confirms details with patient
  -> ticket created for billing staff
  -> SMS confirmation sent to patient
  -> staff completes ticket
  -> patient receives outcome SMS

How The Call Flow Works

When Telnyx sends call.initiated, the app answers the inbound call. The answer command includes a generated command_id, which makes command retries safer, and enables idle silence handling for a smoother voice experience.

After the call is answered, the app starts Gather Using AI. The app passes the intake fields it needs, such as procedure, provider, insurer, and urgency context. Telnyx manages the spoken collection and returns the result through call.ai_gather.ended.

The app then sends the gathered text and fields to AI Inference for classification. The classifier returns structured JSON: a normalized procedure, urgency, and type flags like imaging, medication, or surgery. The app also keeps a keyword-based urgency override so phrases like "ASAP," "severe pain," or "can't wait" are not missed.

Before anything is submitted, the agent confirms the details with the patient. If the patient says yes, the app creates a clearance ticket, sends an SMS confirmation, and posts a Slack alert for billing staff. If the patient hangs up after meaningful details have been collected, the app can still create a partial ticket so staff can follow up.

Run The Example

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/ai-pre-visit-clearance-voice-agent-python
cp .env.example .env
pip install -r requirements.txt
python app.py
ngrok http 5000

Configure your Call Control Application webhook URL:

https://<your-ngrok-domain>/webhooks/voice

Seed a patient:

curl -X POST http://localhost:5000/patients \
  -H "Content-Type: application/json" \
  -d '{"patient_id":"P001","name":"Jordan Lee","phone":"+15551112233","dob":"03/15/1990","insurance":"Blue Cross","provider":"Dr. Smith"}'

Call the Telnyx number from that phone and say:

I need clearance for an MRI on my lower back.

After the confirmation step, inspect the created ticket:

curl http://localhost:5000/tickets | python3 -m json.tool

Complete the ticket:

curl -X POST http://localhost:5000/tickets/CLR-xxxx/complete \
  -H "Content-Type: application/json" \
  -d '{"outcome":"approved"}'

Production Considerations

• Replace in-memory storage with EHR/PMS and billing system integration
• Add privacy review and HIPAA-ready operational controls before production use
• Wire ticket completion into real prior authorization submission APIs
• Queue side effects for webhook response speed
• Expand the confirmation step for payer-specific required fields
• Keep the agent inside the non-clinical boundary: intake and routing only