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

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:

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:

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

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):

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)

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)

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:

{
  "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

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

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

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)

npx agentcash@latest fetch https://stablephone.dev/api/number -m POST -b '{"area_code": "212", "country_code": "US"}'

Then use it as from:

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