README.md•4.01 kB
# AI Call System
A Node.js application that enables AI-powered phone calls using Twilio and OpenAI's Realtime API.
## Features
- 🤖 AI-powered phone calls with natural conversation
- 📞 Real-time voice interaction using OpenAI's Realtime API
- 🔄 Interruption handling for natural conversation flow
- 📊 Call status tracking and logging
- 🚀 Easy-to-use functions and CLI interface
## Setup
1. **Install dependencies:**
```bash
npm install
```
2. **Create a `.env` file with your credentials:**
```env
# Twilio credentials
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=your_twilio_phone_number
TO_PHONE_NUMBER=number_to_call
# OpenAI credentials
OPENAI_API_KEY=your_openai_api_key
# Server configuration (optional)
PORT=5050
```
3. **Make sure your Twilio phone number is configured for voice calls and webhooks.**
## Usage
### Method 1: Using the Functions Directly
```typescript
import { makeAICall, startAIServer } from "./src/make_call";
// Start the server
await startAIServer();
// Make an AI call
const callResult = await makeAICall();
console.log("Call SID:", callResult.sid);
```
### Method 2: Using the CLI
**Start the server:**
```bash
npx tsx src/cli.ts server
```
**Make a call:**
```bash
npx tsx src/cli.ts call
```
**Make a call to a specific number:**
```bash
npx tsx src/cli.ts call +1234567890
```
### Method 3: Using the Example
```bash
npx tsx src/example.ts
```
## API Functions
### `makeAICall(toNumber?, fromNumber?, serverUrl?)`
Initiates an AI call using Twilio.
**Parameters:**
- `toNumber` (optional): Phone number to call (defaults to `TO_PHONE_NUMBER` from env)
- `fromNumber` (optional): Twilio phone number to call from (defaults to `TWILIO_PHONE_NUMBER` from env)
- `serverUrl` (optional): URL of your server (defaults to `http://localhost:5050`)
**Returns:** Promise with call details including SID, status, etc.
### `startAIServer(port?)`
Starts the server that handles AI calls and webhooks.
**Parameters:**
- `port` (optional): Port to run the server on (defaults to 5050)
## How It Works
1. **Call Initiation:** The `makeAICall` function creates a Twilio call to the specified number
2. **Webhook Handling:** When the call connects, Twilio sends a webhook to `/incoming-call`
3. **Media Stream:** The call connects to a WebSocket stream for real-time audio
4. **AI Processing:** Audio is sent to OpenAI's Realtime API for processing
5. **Response:** AI responses are converted to speech and sent back through the call
## Environment Variables
| Variable | Description | Required |
| --------------------- | --------------------------- | -------- |
| `TWILIO_ACCOUNT_SID` | Your Twilio Account SID | Yes |
| `TWILIO_AUTH_TOKEN` | Your Twilio Auth Token | Yes |
| `TWILIO_PHONE_NUMBER` | Your Twilio phone number | Yes |
| `TO_PHONE_NUMBER` | Default number to call | Yes |
| `OPENAI_API_KEY` | Your OpenAI API key | Yes |
| `PORT` | Server port (default: 5050) | No |
## Development
**Type checking:**
```bash
npm run type-check
```
**Formatting:**
```bash
npm run format
```
**Linting:**
```bash
npm run lint:fix
```
## Troubleshooting
1. **"Missing Twilio credentials"**: Make sure all required environment variables are set in your `.env` file
2. **"Call failed"**: Check that your Twilio phone number is configured for voice calls
3. **"Server not accessible"**: Ensure your server is publicly accessible for Twilio webhooks (use ngrok for local development)
## Local Development with ngrok
For local development, you'll need to expose your local server to the internet:
```bash
# Install ngrok
npm install -g ngrok
# Start your server
npx ts-node src/cli.ts server
# In another terminal, expose your server
ngrok http 5050
# Use the ngrok URL in your .env file or when calling makeAICall
```