Skip to content

Latest commit

 

History

History

ai-cold-caller-objection-trainer-python

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 

README.md

name ai-cold-caller-objection-trainer
title AI Cold Caller Objection Trainer
description AI Cold Caller Objection Trainer - practice handling sales objections with AI-generated scenarios.
language python
framework flask
telnyx_products
Voice
AI Inference
channel
voice

AI Cold Caller Objection Trainer

AI Cold Caller Objection Trainer - practice handling sales objections with AI-generated scenarios.

Telnyx API Endpoints Used

Telnyx Webhook Events

This app handles these webhook events (Call Control docs):

  • call.answered - Call connected - app begins interaction
  • call.gather.ended - Caller input received (speech transcription or DTMF digits)
  • call.hangup - Call ended - app cleans up session, triggers post-call processing
  • call.speak.ended - TTS playback finished - app transitions to next action (gather, transfer, etc.)

Architecture

  POST /train (rep_number, persona)
        │
        ▼
  ┌──────────────────┐
  │ Outbound Call     │ ── Telnyx Call Control dials the rep
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │ AI Persona opens  │ ── TTS in-character greeting
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │ Gather Speech     │ ── STT captures rep's pitch
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │ AI Inference      │
  │ • Stay in persona │
  │   (Busy VP, Gate- │
  │    keeper, etc.)  │
  │ • Push objections │
  └────────┬─────────┘
           │ ◄──── roleplay loop (5-8 exchanges)
           │
           ▼
  ┌──────────────────┐
  │ Call hangup       │ ── AI scores performance
  │ • objection score │
  │ • rapport score   │
  │ • feedback list   │
  └──────────────────┘

Environment Variables

Copy .env.example to .env and fill in:

Variable Type Example Required Description Where to get it
TELNYX_API_KEY string KEY0123456789ABCDEF yes Telnyx API v2 key Portal · CLI: telnyx auth
AI_MODEL string moonshotai/Kimi-K2.6 no Telnyx AI Inference model name Portal
TRAINER_NUMBER string your_value yes Trainer number -
CONNECTION_ID string 1494404757140276705 yes Call Control connection/app ID Portal · CLI: telnyx call-control-applications
PORT integer 5000 no HTTP server port -

Setup

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/ai-cold-caller-objection-trainer-python
cp .env.example .env    # ← fill in your credentials
pip install -r requirements.txt
python app.py           # starts on http://localhost:5000
Programmatic / CLI setup
# Install CLI — https://developers.telnyx.com/development/cli
go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest
telnyx auth login

# Provision resources
telnyx available-phone-numbers list --country US --features sms
telnyx number-orders create --phone-number +15551234567

For full API discovery, point your agent at llms-full.txt.

Webhook Configuration

  1. Expose your local server:

    ngrok http 5000
  2. Copy the HTTPS URL and configure in Telnyx Portal:

    • Call Control Application → Webhook URL → https://<id>.ngrok.io/webhooks/voice

API Reference

POST /train

Triggers train

curl -X POST http://localhost:5000/train \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "angry_billing",
    "trainees": ["+12125551234", "+13105559876"]
  }'

Response:

{
  "session_id": "train-1750280400",
  "scenario": "angry_billing",
  "trainees": 3
}

GET /results

Returns results

curl http://localhost:5000/results

Response:

{
  "results": [
    {
      "id": "eval-001",
      "score": 8.5,
      "feedback": "Strong opening, good discovery questions. Improve: handle pricing objection earlier.",
      "completed_at": "2026-07-15T14:45:00Z"
    }
  ]
}

GET /personas

Returns personas

curl http://localhost:5000/personas

Response:

{
  "items": [
    {
      "id": "item-001",
      "status": "active",
      "created_at": "2026-07-15T14:30:00Z"
    }
  ]
}

GET /health

Returns health

curl http://localhost:5000/health

Response:

{
  "status": "ok",
  "uptime_seconds": 3842,
  "active_sessions": 2,
  "version": "1.0.0"
}

Webhook Endpoints

POST /webhooks/voice

Receives Telnyx Call Control webhook events.

Events handled: call.answered, call.gather.ended, call.hangup, call.speak.ended

Example payload:

{
  "data": {
    "event_type": "call.gather.ended",
    "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    "occurred_at": "2026-07-15T14:30:15.000Z",
    "payload": {
      "call_control_id": "v3:uMi2qMWHT-mLFGkEm4t9tA",
      "connection_id": "1494404757140276705",
      "client_state": "eyJzdGVwIjoibWFpbl9tZW51In0=",
      "digits": "1",
      "from": "+12125551234",
      "to": "+13105559876",
      "speech": {
        "result": "I need help with my account billing",
        "confidence": 0.94
      },
      "status": "valid"
    },
    "record_type": "event"
  }
}

Troubleshooting

Issue Cause Fix
401 Unauthorized Invalid or missing API key Verify TELNYX_API_KEY in .env matches your key in the Portal
Webhook not received Local server not publicly reachable Expose it with a tunnel (e.g. ngrok) and set the webhook URL in the Telnyx Portal
422 Unprocessable Entity Missing or malformed request fields Check the request body against the API Reference above

Agent / CLI access — provision resources programmatically with the Telnyx CLI:

telnyx auth login
telnyx call-control-applications list

Full API discovery: llms-full.txt · CLI docs

Related Examples

Agent Discovery

This example is part of the Telnyx Code Examples catalog.

Resources

Why Telnyx

Telnyx is an AI Communications Infrastructure platform - voice, messaging, SIP, AI, and IoT on one private, global network.