Predict Churn Before Customers Leave

#telnyx #ai #devrel

Subtitle: Build a Python app with Telnyx AI Inference that turns customer activity signals into churn risk, recommended actions, and retention next steps.

Most customer churn is only surprising because the signals were scattered.

Usage dropped in one place. Support tickets went up somewhere else. A renewal date got closer. A login did not happen for two weeks. Payment issues started showing up. None of those signals alone proves a customer is leaving, but together they usually tell a story.

That is the workflow I wanted to make easier to build: take customer activity data, pass it through an inference model, and return a structured churn assessment that a product or customer success team can actually use.

The example is here:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-customer-churn-predictor-python

It is a small Flask app using Telnyx AI Inference through the chat-completions API.

The App Shape

The app exposes a few routes:

POST /predict for one customer
POST /predict/batch for up to 20 customers
GET /predictions for recent in-memory predictions
GET /health for app health

The current default model is set in .env.example:

AI_MODEL=moonshotai/Kimi-K2.6

Under the hood, the app calls:

POST https://api.telnyx.com/v2/ai/chat/completions

The prompt asks the model to behave like a customer success analyst and return JSON only. That is the important part. This is not a chatbot. It is an application endpoint that produces structured output.

What Goes In

A request can look like this:

curl -X POST http://localhost:5000/predict \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "CUST-123",
    "call_volumes": [120, 105, 80, 55],
    "message_volumes": [450, 420, 300, 190],
    "support_tickets": 6,
    "account_age_months": 18,
    "renewal_days": 21,
    "last_login_days": 14,
    "payment_issues": 1
  }'

Those fields are deliberately simple. The point is to show the pattern, not to pretend this is a full enterprise churn model.

The model gets the trend data, support context, account age, renewal window, login recency, and payment issues. Then it returns risk, probability, risk factors, recommended actions, urgency, and revenue-at-risk context.

That response can feed a dashboard, trigger a customer success task, create a review queue, or become part of a larger retention workflow.

Why I Like This Pattern

A lot of AI product ideas start with a blank chat box.

But many useful AI apps are not blank chat boxes. They are small decision endpoints with clear inputs and clear outputs.

For churn prediction, the output shape matters:

{
  "churn_risk": "high",
  "probability": 0.82,
  "risk_factors": [
    "Usage declined over the last four months",
    "Support tickets increased",
    "Renewal date is approaching"
  ],
  "recommended_actions": [
    "Schedule an account review this week",
    "Investigate open support ticket themes"
  ],
  "urgency": "this_week"
}

That is easier to build with than a paragraph. You can sort it, store it, validate it, route it, or show it in a product.

The Small Detail That Matters

The app asks for JSON, but it still treats model output carefully.

It includes a helper that strips markdown fences and extracts the JSON object before parsing. That is the sort of thing you want in AI apps. Prompts help, but validation still matters.

The sample keeps the implementation readable so developers can inspect the whole flow in one file.

What I Would Add Next

The example uses in-memory storage because it is meant to be easy to run locally. In production, I would add:

Persistent storage for predictions
Auth on the API routes
A real customer data source
Strict schema validation
Batch processing through a queue
Alerting for high-risk accounts
Human review before customer-facing interventions

The repo is also structured to be agent-readable. That means your coding agent can inspect the README, API reference, guide, environment file, and app code, then help you extend it. You can ask it to add persistence, write tests, connect the output to a CRM, or turn the batch endpoint into a scheduled workflow.