phone-calls

# AI Phone Calls with StablePhone Make AI-powered phone calls, buy phone numbers, and get transcripts via x402 payments at `https://stablephone.dev`. ## Setup See [rules/getting-started.md](rules/getting-started.md) for installation and wallet setup. ## Quick Reference | Task | Endpoint | Price | |------|----------|-------| | Make a call | `https://stablephone.dev/api/call` | $0.54 | | Check call status | `GET https://stablephone.dev/api/call/{call_id}` | Free | | Buy phone number | `https://stablephone.dev/api/number` | $20.00 | | Top up number (30d) | `https://stablephone.dev/api/number/topup` | $15.00 | | List your numbers | `GET https://stablephone.dev/api/numbers` | Free | | iMessage/FaceTime lookup | `https://stablephone.dev/api/lookup` | $0.05 | | Lookup status | `GET https://stablephone.dev/api/lookup/status?token=...` | Free | ## Make a Call ```bash npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{ "phone_number": "+14155551234", "task": "Call this person and ask if they are available for a meeting tomorrow at 2pm. Be polite and professional." }' ``` **Required:** - `phone_number` — E.164 format, US/CA `+1` numbers only (e.g. `+14155551234`) - `task` — instructions for the AI agent (what to say, how to behave; max 4000 chars) **Optional:** - `from` — outbound caller ID (must be an active StablePhone number, `+1` format) - `first_sentence` — specific opening line - `voice` — voice preset (see Voice Options below) - `max_duration` — max call length in minutes (1-30, default 5) - `wait_for_greeting` — wait for recipient to speak first (default false) - `record` — record call audio (default true) - `model` — `"base"` (default, best quality) or `"turbo"` (lowest latency) - `transfer_phone_number` — number to transfer to if caller requests a human - `voicemail_action` — `"hangup"` (default), `"leave_message"`, or `"ignore"` - `voicemail_message` — message to leave (required when action is `"leave_message"`) - `metadata` — custom key-value data to attach **Do-Not-Call (DNC):** Returns 403 if the number is on the Do-Not-Call list — do not retry DNC numbers. ## Check Call Status Poll until `completed` is true: ```bash npx agentcash@latest fetch https://stablephone.dev/api/call/{call_id} ``` **Response fields:** - `status` — call status - `completed` — boolean, true when call is done - `answered_by` — `"human"`, `"voicemail"`, or `"no_answer"` - `call_length` — duration in seconds - `summary` — AI-generated call summary - `transcript` — full text transcript - `transcripts` — array of timestamped transcript segments - `recording_url` — URL to call recording - `price` — actual cost Poll every 5-10 seconds. Calls typically complete in 1-5 minutes depending on `max_duration`. ## Voice Options | Voice | Description | |-------|-------------| | `nat` | American female (default) | | `josh` | Articulate American male | | `maya` | Young American female, soft | | `june` | American female | | `paige` | Calm, soft-tone female | | `derek` | Soft and engaging male | | `florian` | German male | ## Buy a Phone Number Buy a number to use as outbound caller ID: ```bash npx agentcash@latest fetch https://stablephone.dev/api/number -m POST -b '{"area_code": "415", "country_code": "US"}' ``` **Optional:** - `area_code` — 3-digit US/CA area code (random if omitted) - `country_code` — `"US"` (default) or `"CA"` Numbers expire after 30 days. Top up to extend. ## Top Up a Number ```bash npx agentcash@latest fetch https://stablephone.dev/api/number/topup -m POST -b '{"phone_number": "+14155551234"}' ``` Extends by 30 days from current expiry. Top-ups stack. Anyone can top up any number. ## List Your Numbers Uses SIWX auth (wallet from auth header): ```bash npx agentcash@latest fetch https://stablephone.dev/api/numbers ``` ## iMessage/FaceTime Lookup Check if a phone number has iMessage or FaceTime. The lookup is async (30-90 seconds). **Step 1: Start the lookup (paid, $0.05)** ```bash npx agentcash@latest fetch https://stablephone.dev/api/lookup -m POST -b '{"phone_number": "+14155551234"}' ``` Returns 202 with `{"token": "jwt..."}`. **Step 2: Poll for results (SIWX, free)** ```bash npx agentcash@latest fetch "https://stablephone.dev/api/lookup/status?token=JWT_TOKEN" ``` Poll every 3-5 seconds until `status` is `"complete"`. **Response when complete:** ```json { "status": "complete", "phone_number": "+1...", "imessage": "available|unavailable|unknown", "facetime": "available|unavailable|unknown|pending", "carrier": {"carrier": "...", "number_type": "..."}, "country": {"name": "...", "iso2": "...", "flag": "..."} } ``` **Notes:** - `"unknown"` means the number exists but status can't be determined (likely landline/VoIP) - Token expires after 60 minutes - Same number within ~1 hour reuses cached result ## Workflows ### Quick Call - [ ] (Optional) Check balance: `npx agentcash@latest balance` - [ ] Make call with task instructions - [ ] Poll status until completed - [ ] Review transcript and summary ```bash npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{ "phone_number": "+14155551234", "task": "Ask if the business is open on weekends and what their hours are." }' ``` ### Leave a Voicemail ```bash npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{ "phone_number": "+14155551234", "task": "Leave a voicemail about the appointment.", "voicemail_action": "leave_message", "voicemail_message": "Hi, this is a reminder about your appointment tomorrow at 3pm. Please call back to confirm." }' ``` For natural voicemail delivery, use `"voicemail_action": "ignore"` which bypasses detection and lets the AI speak naturally into the voicemail system. ### Call with Transfer ```bash npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{ "phone_number": "+14155551234", "task": "Qualify this lead. Ask about their budget and timeline. If they are interested, offer to transfer to a sales rep.", "transfer_phone_number": "+14155559999", "voice": "josh", "max_duration": 10 }' ``` ### Set Up Dedicated Number - [ ] Buy a phone number ($20) - [ ] Use it as caller ID for outbound calls - [ ] Top up before expiry ($15/30 days) ```bash npx agentcash@latest fetch https://stablephone.dev/api/number -m POST -b '{"area_code": "212", "country_code": "US"}' ``` Then use it as `from`: ```bash npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{ "phone_number": "+14155551234", "from": "+12125551234", "task": "Confirm the reservation for Friday at 7pm." }' ``` ## Cost Estimation | Task | Cost | |------|------| | Single call | $0.54 | | Call + dedicated number | $20.54 | | Monthly number maintenance | $15.00 | | 10 calls/month + number | $20.00 + $5.40 = $25.40 first month |