autodial 0.6.1

A self-hosted automated outbound dialer phone bot

📞 Autodial PhoneBot

The Ultimate Self-Hosted AI Dialer & Voice Automator

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

Whether you need a dynamic AI receptionist, a high-volume outbound lead qualifier, or a system to navigate complex IVR menus with DTMF tones, Autodial is the ultimate developer tool. It natively bridges Twilio and Telnyx media streams with zero friction.

---

🚀 Why Autodial?

• Multi-LLM Cloud & Local Support: Power your conversations with OpenAI, Google Gemini, MistralAI, or keep it 100% private and offline using Ollama.
• Bidirectional Calling: Trigger 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 Twilio and Telnyx. Drop in your API keys and go.
• Natural Language CLI: Execute phone calls from your terminal using plain English (autodial call bob and ask...). The CLI automatically extracts parameters using your configured LLM.
• Local Transcription Engine: Powered by Faster-Whisper (STT). Optimized for GPU (RTX series) with automatic CPU fallback for lightning-fast voice transcription.
• Intelligent Call Termination: Built-in intent recognition for phrases like "stop calling me" or "goodbye," ensuring polite and immediate hang-ups.
• Webhooks & Transcripts: Every call generates a detailed JSON transcript. Configure a callback_url to pipe data directly into your CRM.

---

🛠 Quickstart Installation

Core Requirements

1. TTS Engine: The piper binary should be in your system PATH, along with its .onnx models.
2. LLM Provider: An API key for OpenAI/Gemini/Mistral, OR a local Ollama instance serving a chat-ready model (e.g., llama3.2).
3. Telephony: An active Account SID/API Key, Auth Token, and a verified Phone Number from Twilio or Telnyx.

Install via PyPI

pip install autodial

---

⚙️ Configuration (.env)

Autodial consumes configuration via environment variables. Create a .env file in the directory where you run the server:

PORT=8000
TWILIO_ACCOUNT_SID=your_sid_here
TWILIO_AUTH_TOKEN=your_token_here
TWILIO_PHONE_NUMBER=[phone]

# --- LLM Provider Selection ---
# Options: ollama (default), openai, gemini, mistral
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o

# Cloud API Keys (Required if using cloud provider)
OPENAI_API_KEY=sk-your-key
# GEMINI_API_KEY=AIza...
# MISTRAL_API_KEY=...

# Local Ollama URL (used only if provider is ollama)
OLLAMA_CHAT_URL=http://localhost:11434/api/chat

# --- Local TTS Settings ---
PIPER_MODEL=./en_US-lessac-medium.onnx

(Note: If using Telnyx, provide your Telnyx API keys within the Twilio env vars for drop-in compatibility).

---

🖥 1. Start the Server

Launch the Autodial engine. It handles all WebSockets and REST routes.

autodial serve

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

---

🗣 2. Natural Language CLI

You don't even need to write Python code to place intelligent calls. Autodial includes a powerful NLP-driven CLI that translates plain English into API actions!

Ensure your Autodial server is running in the background, then simply type:

autodial call bob at 613-444-0101 and ask how his day is going

The CLI uses your configured LLM to instantly extract the target phone number, the conversation context, and the goals, and then dispatches the call automatically.

---

🐍 3. Full Python Demo (The API Client)

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

demo.py

import time
from autodial import AutodialClient

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

def run_outbound_demo():
    print("📞 Placing intelligent outbound call...")
    
    # Scenario: Appointment Reminder with Guardrails
    response = client.dial(
        target_number="[phone]",
        context="Reminder for Dr. Smith's dental clinic.",
        goals="Confirm the 2:00 PM slot today. Ask if they need directions.",
        system_instructions="Always be polite. If the user is busy, offer to call back later. Keep responses short.",
        callback_url="https://api.yourclinic.com/webhooks/call-results"
    )
    
    print(f"✅ Call Initiated: {response}")

def run_broadcast_demo():
    print("📢 Initiating Mass Broadcast...")
    
    # Scenario: Emergency Alert Broadcast
    response = 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"
    )
    
    print(f"✅ Broadcast Initiated: {response}")

if __name__ == "__main__":
    run_outbound_demo()
    time.sleep(5)
    run_broadcast_demo()

---

📞 4. 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 instructions, and the AI answers immediately using your configured LLM_PROVIDER.

---

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