autodial 0.4.0

A self-hosted automated outbound dialer phone bot

📞 Autodial PhoneBot: Self-Hosted AI Dialer

Autodial is a production-grade, self-hosted outbound and inbound phone automation engine. It leverages state-of-the-art Local Speech-to-Text (STT), Large Language Models (LLM), and Local Text-to-Speech (TTS) to create intelligent, human-like phone interactions.

Built for high-performance automation, Autodial can handle inbound calls gracefully, navigate IVR menus, handle complex DTMF interactions, execute mass broadcasts, and notify your external systems via webhooks upon call conclusion. It natively supports both Twilio and Telnyx.

---

🚀 Key Features

• Bidirectional Calling: Make automated outbound calls via Python or handle inbound calls instantly by pointing your Twilio/Telnyx webhook to the /incoming endpoint.
• Provider Agnostic: Native auto-detection and WebSocket formatting for both Twilio and Telnyx media streams. Fixes all edge-case payload validation errors out of the box.
• Multi-Concurrent Interaction: Built on FastAPI and Python's asyncio, handling dozens of simultaneous Media Streams with low overhead.
• Local Transcription Engine: Powered by Faster-Whisper (STT). Optimized for GPU (RTX series) with automatic CPU fallback.
• Dynamic AI Personalities: Inject per-call context, goals, and keywords. The AI intelligently adapts its persona and strategy for every unique target.
• Developer-Defined Guardrails: Set strict system_instructions to keep calls on track and ensure brand-safe communication.
• Intelligent Call Termination: Built-in intent recognition for phrases like "stop calling me" or "goodbye," ensuring polite and immediate hang-ups.
• Broadcast & Direct Messaging: Need to send a simple notification? Use Broadcast Mode to play a direct message and disconnect immediately.
• Automated Call Logs & Webhooks: Every call generates a detailed JSON transcript. Configure a callback_url to receive data as soon as the session ends.

---

🛠 Prerequisites & Installation

Core Requirements

1. Ollama: Serving a chat-ready model (e.g., llama3.2) at a reachable URL.
2. Piper TTS: The piper binary should be in your system PATH, along with its .onnx models.
3. Twilio or Telnyx: An active Account SID/API Key, Auth Token, and a verified Phone Number.

System Install

pip install autodial

---

⚙️ Configuration

Autodial consumes configuration via environment variables. Create a .env file in your execution directory:

PORT=8000
OLLAMA_CHAT_URL=http://localhost:11434/api/chat
LLM_MODEL=llama3.2:3b
PIPER_MODEL=./en_US-lessac-medium.onnx

TWILIO_ACCOUNT_SID=your_sid_here
TWILIO_AUTH_TOKEN=your_token_here
TWILIO_PHONE_NUMBER=[phone]

# (If using Telnyx, provide Telnyx API keys but use the Twilio env vars for drop-in compatibility)

---

🖥 Start the Server

Launch the Autodial engine with a single command:

autodial

Note: The server will initialize Whisper on your GPU if available (CUDA), otherwise it fallbacks to CPU.

---

🐍 Python Client Usage

The library includes a professional AutodialClient to make programmatic orchestration seamless.

from autodial import AutodialClient

# Connect to your Autodial instance
client = AutodialClient("http://localhost:8000")

# Scenario: Appointment Reminder with Guardrails
client.dial(
    target_number="[phone]",
    context="Reminder for Dr. Smith's clinic",
    goals="Confirm the 2:00 PM slot today",
    system_instructions="Always be polite. If the user is busy, offer to call back later.",
    callback_url="https://api.yourclinic.com/webhooks/call-results"
)

# Scenario: Emergency Alert Broadcast
client.broadcast(
    numbers=["[phone]", "[phone]", "[phone]"],
    message="This is an automated alert from the city. Please evacuate immediately.",
    callback_url="https://api.city.gov/logs"
)

---

📞 Handling Inbound Calls (Bidirectional)

Autodial isn't just for outbound dialing. It exposes an /incoming REST endpoint that automatically generates the required TwiML/TeXML to connect callers to your AI bot.

Setup Instructions:

1. Log in to your Twilio or Telnyx Console.
2. Navigate to your active Phone Number settings.
3. Find the Webhook URL for incoming calls.
4. Set it to POST https://your-autodial-server.com/incoming

When a user dials your number, the provider hits the endpoint, receives the Media Stream instruction, and the AI connects automatically using the base SYSTEM_PROMPT.

---

📡 API Reference

POST /dial

Initiates a single interactive AI session.

Parameter	Type	Description
to_number	string	Required. The target phone number in E.164 format.
context	string	Detailed background info for the AI to understand the call's nature.
goals	string	Specific outcomes or data points the AI should strive to achieve.
keywords	string	Focus phrases for the transcription engine to prioritize.
system_instructions	string	High-priority guardrails and behavioral rules for the session.
callback_url	string	POST endpoint to receive the final JSON transcript and status.

POST /incoming

A webhook endpoint for Twilio/Telnyx. Do not call this manually. It automatically returns <Connect><Stream .../> XML to start a bidirectional session.

---

🛡 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ by the Autodial Maintainers.