autodial 0.3.1

A self-hosted automated outbound dialer phone bot

📞 Autodial PhoneBot: Self-Hosted AI Dialer

Autodial is a production-grade, self-hosted outbound 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 navigate IVR menus, handle complex DTMF interactions, execute mass broadcasts, and notify your external systems via webhooks upon call conclusion.

---

🚀 Key Features

• Multi-Concurrent Interaction: Built on FastAPI and Python's asyncio, handling dozens of simultaneous Twilio 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: An active Account SID, Auth Token, and a verified outbound 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]

---

🖥 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"
)

---

📡 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.

---

🛡 License

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

---

Built with ❤️ by the Autodial Maintainers.