Skip to main content
Triggers a phone call by calling the running server’s API endpoint. This is the recommended way to initiate calls during development and testing.
The server must be running first (agenticai server or agenticai service start)

​
Usage

agenticai trigger [OPTIONS]

​
Options

​
--to
string
required
Phone number to call in E.164 formatShort form: -tRequired: YesFormat: Must include country code, e.g., +15551234567Example:
agenticai trigger --to +15551234567
​
--prompt
string
default:"System instruction from config"
Custom prompt/instructions for the AIShort form: -pDefault: Uses gemini.system_instruction from config.yaml, or falls back to "You are a helpful AI assistant making a phone call."Example:
agenticai trigger -t +15551234567 -p "Ask about their appointment tomorrow"
​
--webhook-url
string
default:"$NGROK_URL"
Public webhook base URL for Twilio callbacksShort form: -wDefault: Loaded from NGROK_URL environment variableRequired if: NGROK_URL environment variable is not setExample:
agenticai trigger -t +15551234567 -w https://abc123.ngrok.io
​
--server-url
string
default:"http://localhost:8080"
URL of the running Agentic AI serverShort form: -sDefault: http://localhost:8080Example:
agenticai trigger -t +15551234567 -s http://localhost:3000

​
How It Works

  1. Checks if the server is running (via /health endpoint)
  2. Sends a POST request to /api/call with call parameters
  3. Server initiates the call via Twilio
  4. Returns immediately with the call ID
The call happens asynchronously - check server logs for progress.

​
Examples

​
Basic Usage

With NGROK_URL environment variable set: 
export NGROK_URL=https://abc123.ngrok.io
agenticai trigger --to +15551234567
Output: 
┌────────────────────────────────────────┐
│ 📞 Triggering Call                     │
│                                        │
│ To: +15551234567                       │
│ From: +18001234567                     │
│ Webhook: https://abc123.ngrok.io       │
└────────────────────────────────────────┘

✓ Call initiated!
  Call ID: CA1234567890abcdef1234567890abcdef

The call is in progress. Check server logs for details.

​
Custom Prompt

Provide specific instructions for this call: 
agenticai trigger \
  --to +15551234567 \
  --prompt "You are calling to confirm the appointment for tomorrow at 2 PM. Be polite and brief."

​
Explicit Webhook URL

Don’t use environment variable: 
agenticai trigger \
  -t +15551234567 \
  -w https://your-url.ngrok.io

​
Custom Server Port

If server is running on a different port: 
agenticai trigger \
  -t +15551234567 \
  -s http://localhost:3000

​
Workflow

​
Development

# Terminal 1: Start server
agenticai server

# Terminal 2: Start tunnel
agenticai tunnel start
# Copy the URL shown

# Terminal 3: Set env and trigger calls
export NGROK_URL=https://abc123.ngrok.io
agenticai trigger --to +15551234567

​
Production

# Service is already running with permanent webhook URL
agenticai service status

# Just trigger calls (NGROK_URL set in service)
agenticai trigger --to +15551234567

​
Error Handling

​
Server Not Running

Error: 
✗ Server not running at http://localhost:8080
Start the server first: agenticai server
Solution: 
# Start the server
agenticai server

# Or start the service
agenticai service start

​
Missing Webhook URL

Error: 
Error: --webhook-url required or set NGROK_URL environment variable

Example: export NGROK_URL=https://your-subdomain.ngrok.io
Solution: 
# Set environment variable
export NGROK_URL=https://abc123.ngrok.io

# Or provide explicitly
agenticai trigger -t +15551234567 -w https://abc123.ngrok.io

​
Invalid Phone Number

Error: 
✗ Error: Unable to create record: Invalid 'To' Phone Number
Solution: Use E.164 format with country code: 
agenticai trigger --to +15551234567  # ✓ Correct
agenticai trigger --to 5551234567    # ✗ Wrong

​
API Request Format

The trigger command sends: 
POST /api/call HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "to": "+15551234567",
  "prompt": "You are a helpful AI assistant making a phone call.",
  "webhook_url": "https://abc123.ngrok.io"
}
Response: 
{
  "success": true,
  "call_id": "CA1234567890abcdef1234567890abcdef"
}

​
Difference from agenticai call

Featuretriggercall
Server requiredYes, must be runningNo, starts temporary session
SpeedFast (uses existing server)Slower (initializes components)
Use caseDevelopment, testing, productionOne-off calls, scripts
LogsServer logsConsole output
Waits for completionNo (async)Yes (blocks)
Recommendation: Use trigger for most scenarios. Use call only for standalone scripts.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us