Keep Outbound Numbers Healthy with AI

#telnyx #ai #devrel

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:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/number-reputation-monitor-auto-rotate-python

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 /scan to analyze up to 20 numbers
GET /health-report to inspect tracked number health and rotation recommendations
GET /health for 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.