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 exposes three routes:
POST /scan
to analyze up to 20 numbersGET /health-report
to inspect tracked number health and rotation recommendationsGET /health
for app healthIt 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.
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.
Number reputation is not a single flag.
It is usually a collection of signals:
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.
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 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.
For production, I would add:
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.
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: