Subtitle: Build a Python app that monitors Telnyx phone numbers, analyzes reputation risk with Telnyx AI Inference, and recommends when to keep, rotate, or retire a number.
Outbound workflows depend on number health more than most teams want to admit.
A number can look fine in inventory and still perform badly in the real world. Answer rates drop. Complaints increase. Campaign patterns get stale. A number that worked last month might need a cooldown, a review, or a replacement today.
That is the workflow behind this example:
It is a small Python Flask app that lists your Telnyx phone numbers, sends number-health context to Telnyx AI Inference, and records a recommendation: keep, rotate, or retire.
The App Shape
The app exposes three routes:
POST /scanto analyze up to 20 numbers
GET /health-reportto inspect tracked number health and rotation recommendations
GET /healthfor app health
It uses two Telnyx APIs:
GET /v2/phone_numbers
POST /v2/ai/chat/completions
The current default model is set in .env.example:
AI_MODEL=MiniMaxAI/MiniMax-M3-MXFP8
The pattern is simple: pull number inventory, attach health metrics, ask the model for a constrained recommendation, and store the result.
What Happens During a Scan
You start the scan like this:
curl -X POST http://localhost:5000/scan \
-H "Content-Type: application/json" \
-d '{}'
The app calls Telnyx to list phone numbers, then analyzes up to the first 20 numbers.
For each number, it builds a small health payload. In the sample, the default metrics are intentionally simple:
{
"calls": 0,
"complaints": 0,
"answer_rate": 0.5,
"number": "+12125551234"
}
Then the app asks the model to return JSON like this:
{
"risk_level": "warning",
"recommendation": "rotate",
"reasoning": "Answer rate is low and complaint activity is elevated"
}
If the recommendation is rotate, the app records it in a rotation log.
That is important: this sample does not automatically swap live numbers. It logs the recommendation. In a real outbound system, rotation should usually include policy checks, campaign state, routing rules, and human approval.
Why This Is Useful
Number reputation is not a single flag.
It is usually a collection of signals:
- answer rates
- complaints
- opt-outs
- call volume
- campaign history
- carrier filtering signals
- recent routing behavior
A model is useful here when it is not asked to invent a decision from nothing. It is useful when it gets structured operational context and returns a constrained recommendation.
That makes the output easier to route into a dashboard, review queue, or outbound routing system.
Inspect the Health Report
After a scan, you can inspect current state:
curl http://localhost:5000/health-report
The response includes tracked numbers and recent rotation recommendations:
{
"numbers": {
"+12125551234": {
"calls": 0,
"complaints": 0,
"answer_rate": 0.5,
"analysis": {
"risk_level": "warning",
"recommendation": "rotate",
"reasoning": "Example reason"
}
}
},
"rotations": []
}
That structure gives you a starting point for a real number-health dashboard.
The Small Detail That Matters
The prompt asks the model to return only JSON, with no prose and no markdown fences.
The app still includes a helper to strip markdown fences and parse the JSON object. I like that pattern because AI app code should be defensive. Prompts help, but validation is what keeps the output usable as application state.
What I Would Add Next
For production, I would add:
- Real metrics from calls, messages, opt-outs, complaints, and campaign outcomes
- Persistent storage for number history
- Scheduled scans instead of manual scans
- Alerts for critical numbers
- Human approval before rotation or retirement
- Routing rules that remove risky numbers from active campaigns
- Warmup and cooldown policies
- Audit logs for every recommendation and action
The repo is also structured to be agent-readable. Your coding agent can inspect the README, API reference, guide, environment file, and app code, then help extend it. You can ask it to add scheduled scans, persistent metrics, tests, dashboards, or real routing integration.
Try It
Telnyx AI skills and toolkits:
https://github.com/team-telnyx/ai
List Phone Numbers API:
https://developers.telnyx.com/api/numbers/list-phone-numbers
Telnyx AI Inference docs:
https://developers.telnyx.com/docs/inference
Chat Completions API:
https://developers.telnyx.com/api/inference/chat-completions
Telnyx Portal:
https://portal.telnyx.com/