Monitor Number Reputation with Telnyx AI Inference

Outbound communication only works when the numbers behind it stay healthy.

If a number starts getting poor answer rates, complaints, carrier filtering, or suspicious engagement patterns, teams need to know before the number damages a campaign or customer workflow. The challenge is that number reputation is not one field. It is a mix of operational metrics, historical behavior, and routing decisions.

The number-reputation-monitor-auto-rotate-python example shows one way to build a lightweight number-health monitoring workflow with Telnyx number management and Telnyx AI Inference.

It is a small Flask app that lists Telnyx phone numbers, evaluates each number with a Telnyx-hosted model, and records structured recommendations like keep, rotate, or retire.

What the Example Builds

The app exposes three routes:

• POST /scan - scan up to 20 Telnyx phone numbers and analyze their health
• GET /health-report - return tracked number health and recent rotation recommendations
• GET /health - check app health

It uses two Telnyx APIs:

GET /v2/phone_numbers
POST /v2/ai/chat/completions

The current default model in .env.example is:

AI_MODEL=MiniMaxAI/MiniMax-M3-MXFP8

The sample does not perform live number replacement. Instead, it records rotation recommendations in a rotation_log. That is the right level for a demo because production number rotation should usually include policy checks, routing rules, campaign state, and human review.

Why Number Reputation Monitoring Matters

Outbound number pools can degrade over time.

A number may start healthy, then gradually become less effective because of low engagement, complaints, traffic mix, or repeated campaign patterns. When that happens, the team needs a workflow that can answer:

• Which numbers look healthy?
• Which numbers are in a warning state?
• Which numbers should be rotated or retired?
• Why did the system make that recommendation?
• What should happen before the number is used again?

That is a good AI app pattern because the model is not being asked to make something up. It is asked to reason over structured operational signals and return a constrained recommendation.

Running the Example

Clone the examples repo and enter the project folder:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/number-reputation-monitor-auto-rotate-python

Create your environment file:

cp .env.example .env

Set your Telnyx API key and optional alert number:

TELNYX_API_KEY=your_telnyx_api_key
AI_MODEL=MiniMaxAI/MiniMax-M3-MXFP8
ALERT_NUMBER=+1xxxxxxxxxx
HOST=127.0.0.1

Install dependencies and run the app:

pip install -r requirements.txt
python app.py

The app starts locally on http://localhost:5000.

Scan Your Number Pool

Trigger a scan:

curl -X POST http://localhost:5000/scan \
  -H "Content-Type: application/json" \
  -d '{}'

The app calls Telnyx to list phone numbers:

GET https://api.telnyx.com/v2/phone_numbers

Then it analyzes up to the first 20 numbers. For each number, the app creates a health payload with fields like calls, complaints, answer rate, and the number itself. In the demo, those health metrics come from in-memory defaults unless you extend the app with real campaign data.

The inference prompt asks for JSON with this shape:

{
  "risk_level": "warning",
  "recommendation": "rotate",
  "reasoning": "Answer rate is low and complaint activity is elevated"
}

The response from /scan includes the number and analysis:

{
  "scanned": 1,
  "results": [
    {
      "number": "+12125551234",
      "analysis": {
        "risk_level": "warning",
        "recommendation": "rotate",
        "reasoning": "Answer rate is low and complaint activity is elevated"
      }
    }
  ]
}

Inspect the Health Report

Use /health-report to 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"
      },
      "last_scan": 1782840000
    }
  },
  "rotations": [
    {
      "number": "+12125551234",
      "reason": "Example reason",
      "timestamp": "2026-06-30T22:00:00Z"
    }
  ]
}

That structure is useful because it separates analysis from action. A production system could show these recommendations in a dashboard, queue them for review, or feed them into outbound routing logic.

The Inference Step

The model prompt is constrained:

Analyze phone number health metrics. Return only JSON, no prose, no markdown fences: risk_level (healthy/warning/critical), recommendation (keep/rotate/retire), reasoning (string).

That gives the application a stable contract. The app can treat the output as data, not free-form copy.

The sample also includes a JSON extraction helper that strips markdown fences and parses the JSON object. Even with a strict prompt, production AI apps should validate model output before using it in workflow state.

Making It Production-Ready

This sample keeps health state in memory so the full workflow is easy to inspect. For production, you would likely add:

• Real call, answer-rate, complaint, opt-out, and filtering signals
• Persistent storage for number health history
• Authentication on the API routes
• Scheduled scans instead of manual POST /scan
• Alerting when a number becomes critical
• Human approval before rotation or retirement
• Routing rules that remove risky numbers from active campaigns
• Warmup and cooldown policies for new or recovered numbers
• Audit logs for reputation decisions

The repo is intentionally agent-readable. The README, API reference, guide, environment template, and app code are structured so coding agents can inspect the project and help extend it. You can ask an agent to add scheduled scans, persistent metrics, dashboard views, tests, or real routing integration.