Skip to main content
This guide will get you from zero to making your first AI-powered phone call. Follow these steps carefully and you’ll have a working voice agent in minutes.

​
Prerequisites

Before starting, make sure you have:
  • Python 3.11 or higher installed
  • A terminal/command line interface
  • 10 minutes of your time
1

Install Agentic AI

Clone the repository and install the package:
git clone https://github.com/IstiqlalBhat/aiagent.git
cd aiagent

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Mac/Linux
# venv\Scripts\activate   # Windows

# Install the package
pip install -e .
Verify the installation:
agenticai --help
You should see the CLI help menu with available commands.
2

Get Your API Keys

You’ll need credentials from these services:

​
Twilio (Required)

  1. Sign up at console.twilio.com
  2. Get a phone number from the Twilio console
  3. Copy your Account SID and Auth Token from the dashboard

​
OpenAI (Required)

  1. Create an API key at platform.openai.com/api-keys
  2. Make sure your account has access to the Realtime API
  3. Copy your API Key (starts with sk-proj-)

​
Gemini (Required)

  1. Get an API key from aistudio.google.com/apikey
  2. Copy your Gemini API Key

​
Telegram (Optional)

  1. Message @BotFather on Telegram
  2. Create a new bot with /newbot and copy the Bot Token
  3. Message your bot (say “hi”)
  4. Visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
  5. Find "chat":{"id":123456789} - that’s your Chat ID
Keep these credentials handy - you’ll need them in the next step.
3

Configure Environment

Run the interactive setup wizard:
agenticai setup
The wizard will guide you through entering all your credentials and create a .env file automatically.Or configure manually:
# Copy the example file
cp .env.example .env

# Edit with your credentials
nano .env  # or use any text editor
Fill in your .env file:
.env
# Twilio credentials
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+1XXXXXXXXXX

# OpenAI API key for Realtime API
OPENAI_API_KEY=sk-proj-your_openai_api_key_here

# Gemini for intent analysis
GEMINI_API_KEY=your_gemini_api_key_here

# Optional: Telegram integration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_CHAT_ID=your_telegram_chat_id_here
Never commit your .env file to version control! It’s already in .gitignore.
4

Test Your Configuration

Verify all your credentials are working:
agenticai test-connection
This will test connections to:
  • Twilio API
  • Gemini configuration
  • OpenClaw Gateway (optional)
You should see green checkmarks for all required services.
5

Start a Tunnel

Twilio needs to reach your local server via a public URL. Start ngrok:
# Install ngrok if you don't have it
brew install ngrok  # macOS
# Or download from https://ngrok.com/download

# Start the tunnel
agenticai tunnel start
# Or directly: ngrok http 8080
Copy the public URL that appears (e.g., https://xxxx-xx-xx-xxx-xxx.ngrok-free.app).
Alternative: Use Cloudflare tunnel (free, no signup required):
agenticai tunnel start --provider cloudflare
Set the webhook URL in your environment:
export NGROK_URL=https://xxxx-xx-xx-xxx-xxx.ngrok-free.app
6

Start the Server

In a new terminal window (keep ngrok running), start the Agentic AI server:
# Activate your virtual environment first
source venv/bin/activate

# Start the server
agenticai server
You should see output like:
Starting server on 0.0.0.0:8080
Webhook path: /twilio/voice
WebSocket path: /twilio/media-stream
INFO:     Uvicorn running on http://0.0.0.0:8080
The server must stay running while making calls. Keep this terminal window open.
7

Make Your First Call

In a third terminal window, trigger your first AI call:
agenticai trigger --to +1YOURNUMBER --webhook-url https://xxxx.ngrok.io
Replace:
  • +1YOURNUMBER with your actual phone number (E.164 format)
  • https://xxxx.ngrok.io with your ngrok URL from Step 5
agenticai trigger --to +15551234567 --webhook-url https://abc123.ngrok.io
Your phone will ring! 🎉Answer it and have a conversation with your AI agent. Try saying:
  • “Hello, who is this?”
  • “What can you help me with?”
  • “Play Zayn Dusk Till Dawn on YouTube” (requires ClawdBot setup)
8

Receive Incoming Calls (Optional)

Configure your Twilio number to answer incoming calls automatically:
  1. Go to Twilio Console
  2. Navigate to Phone Numbers → Manage → Active numbers
  3. Click on your phone number
  4. Scroll to Voice & Fax section
  5. Under “A call comes in”, select Webhook
  6. Enter: https://xxxx.ngrok.io/twilio/voice (your ngrok URL + /twilio/voice)
  7. Set method to HTTP POST
  8. Click Save
Now when anyone calls your Twilio number, the AI will answer!
If you’re using ngrok free tier, your URL changes each time you restart. You’ll need to update the Twilio webhook URL when this happens.

​
What’s Next?

Installation Guide

Deep dive into installation options, service setup, and production deployment

ClawdBot Integration

Enable command execution during calls - play music, send messages, and more

Configuration Reference

Customize voice options, system instructions, and advanced settings

API Reference

Explore all CLI commands and programmatic API usage

​
Troubleshooting

Symptoms: Phone doesn’t ring or call immediately disconnectsSolutions:
  • Verify your Twilio credentials in .env are correct
  • Check that your ngrok tunnel is running: curl https://xxxx.ngrok.io/health
  • Ensure the webhook URL matches your ngrok URL exactly
  • Check that your Twilio number has voice capabilities enabled
  • View server logs for errors: agenticai service logs -f
Symptoms: Call connects but you hear silence, or AI doesn’t respondSolutions:
  • Verify OPENAI_API_KEY is set correctly and has Realtime API access
  • Check the OpenAI model name is correct: gpt-4o-realtime-preview-2024-12-17
  • Look for WebSocket errors in server logs
  • Ensure your OpenAI account has sufficient credits
  • Try a different voice option in config.yaml
Symptoms: Error when running agenticai serverSolutions:
  • Check port 8080 is not already in use: lsof -i :8080
  • Verify all required environment variables are set: agenticai status
  • Ensure Python version is 3.11 or higher: python --version
  • Reinstall dependencies: pip install -e .
Symptoms: AI doesn’t execute commands during callsSolutions:
  • Ensure OpenClaw Gateway is running on port 18789
  • Start ClawdBot agent: clawdbot agent --session-id agent:main:main
  • Verify gateway URL in config.yaml: ws://127.0.0.1:18789
  • Check that the skill you’re using is configured in ClawdBot
Still having issues? Check the full logs with agenticai service logs -f or visit our GitHub issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us