AI Language Tutor That Answers a Phone Call

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 5

Star 146

Copy path

More options

More options

More options

More options

Latest commit

History

History

History

Copy path

Folders and files

NameName

Last commit message

Last commit date

parent directory

..

.env.example

.env.example

API.md

API.md

GUIDE.md

GUIDE.md

README.md

README.md

app.py

app.py

requirements.txt

requirements.txt

AI Inference

channel

voice

AI Language Learning Phone Tutor

AI Language Learning Phone Tutor - call a number, practice a foreign language with AI.

Telnyx API Endpoints Used

AI Inference: POST /v2/ai/chat/completions - API reference

Telnyx Webhook Events

This app handles these webhook events (Call Control docs) (Messaging docs):

call.answered - Call connected - app begins interaction

call.gather.ended - Caller input received (speech transcription or DTMF digits)

call.hangup - Call ended - app cleans up session, triggers post-call processing

call.initiated - New inbound or outbound call detected

call.speak.ended - TTS playback finished - app transitions to next action (gather, transfer, etc.)

message.received - Inbound SMS/MMS received

Architecture

Inbound Phone Call │ ▼ ┌──────────────────┐ │ Answer + Greet │ ── TTS welcome message └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Gather DTMF │ ── caller presses keys └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ AI Inference │ │ • Translation │ └────────┬─────────┘ │ ◄──── conversation loop │ ▼ JSON response

Environment Variables

Copy .env.example to .env and fill in:

Variable Type Example Required Description Where to get it

TELNYX_API_KEY string KEY0123456789ABCDEF yes Telnyx API v2 key Portal

AI_MODEL string moonshotai/Kimi-K2.6 no Telnyx AI Inference model name Portal

TUTOR_NUMBER string your_value yes Tutor number -

PORT integer 5000 no HTTP server port -

Setup

git clone https://github.com/team-telnyx/telnyx-code-examples.git cd telnyx-code-examples/ai-language-learning-phone-tutor-python cp .env.example .env # ← fill in your credentials pip install -r requirements.txt python app.py # starts on http://localhost:5000

Webhook Configuration

Expose your local server:

ngrok http 5000

Copy the HTTPS URL and configure in Telnyx Portal:

Call Control Application → Webhook URL → https://.ngrok.io/webhooks/voice

API Reference

GET /sessions

Returns sessions

curl http://localhost:5000/sessions

Response:

{ "sessions": [ { "id": "sess-1750280400", "status": "active", "duration_seconds": 240, "turns": 8 } ] }

GET /health

Returns health

curl http://localhost:5000/health

Response:

{ "status": "ok", "uptime_seconds": 3842, "active_sessions": 2, "version": "1.0.0" }

Webhook Endpoints

POST /webhooks/voice

Receives Telnyx Call Control webhook events.

Events handled: call.answered, call.gather.ended, call.hangup, call.initiated, call.speak.ended

Example payload:

{ "data": { "event_type": "call.gather.ended", "id": "a1b2c3d4-5678-9abc-def0-123456789abc", "occurred_at": "2026-07-15T14:30:15.000Z", "payload": { "call_control_id": "v3:uMi2qMWHT-mLFGkEm4t9tA", "connection_id": "1494404757140276705", "client_state": "eyJzdGVwIjoibWFpbl9tZW51In0=", "digits": "1", "from": "+12125551234", "to": "+13105559876", "speech": { "result": "I need help with my account billing", "confidence": 0.94 }, "status": "valid" }, "record_type": "event" } }

Troubleshooting

Issue Cause Fix

401 Unauthorized Invalid or missing API key Verify TELNYX_API_KEY in .env matches your key in the Portal

Webhook not received Local server not publicly reachable Expose it with a tunnel (e.g. ngrok) and set the webhook URL in the Telnyx Portal

422 Unprocessable Entity Missing or malformed request fields Check the request body against the API Reference above

Related Examples

AI After Hours Emergency Triage (Python)

AI Assistant Knowledge Base (Python)

AI Assistant Multi Tool (Python)

AI Assistant Phone Setup (Python)

AI Audiobook Narrator (Python)

Resources

Call Control Guide

AI Inference Guide

Telnyx Developer Docs

Telnyx Portal

Why Telnyx

Telnyx is an AI Communications Infrastructure platform - voice, messaging, SIP, AI, and IoT on one private, global network.