Skip to main content
POST
/
v1
/
tools
/
voice
/
call
curl -X POST https://win.oneshotagent.com/v1/tools/voice/call \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "objective": "Call the restaurant to make a dinner reservation for 2 people at 7pm tonight",
    "target_number": "+14155551234",
    "caller_persona": "A polite assistant making a reservation",
    "context": "Italian restaurant, prefer outdoor seating"
  }'

{
  "error": "payment_required",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1.25",
    "recipient": "0x..."
  },
  "context": {
    "tool": "voice",
    "quote_id": "quote_abc123",
    "target_numbers": ["+14155551234"],
    "conference_mode": false,
    "objective_summary": "Make a dinner reservation for 2 at 7pm",
    "talking_points": [
      "Request table for 2 at 7pm tonight",
      "Ask about outdoor seating availability",
      "Confirm reservation details"
    ],
    "success_criteria": [
      "Reservation confirmed",
      "Time slot secured"
    ],
    "estimated_duration_minutes": 3,
    "total": "1.25"
  }
}

​
Overview

The Voice Call API enables AI agents to make autonomous phone calls. The OneShot Agent analyzes your objective, generates talking points, and conducts the call on your behalf.

​
Authentication

Requires x402 payment. First call returns a quote (402), second call with payment executes.

​
Request Body

​
objective
string
required
What the call should accomplish. Minimum 10 characters. The OneShot Agent will analyze this to generate talking points and success criteria.
​
target_number
string | string[]
required
Phone number(s) in E.164 format (e.g., +14155551234). Multiple numbers triggers conference mode analysis.
​
caller_persona
string
Personality and style for the OneShot Agent caller (e.g., “A polite assistant making a reservation”)
​
context
string
Additional context about the call situation
​
max_duration_minutes
number
Maximum call duration (1-30 minutes). Default: 5

​
Quote Response (402)

The first request returns pricing and analysis:
​
context.quote_id
string
Quote ID to include in payment request
​
context.objective_summary
string
AI-generated summary of the call objective
​
context.talking_points
string[]
Key points the OneShot Agent will cover during the call
​
context.success_criteria
string[]
How success will be evaluated
​
context.conference_mode
boolean
Whether this will be a conference call
​
context.total
string
Total cost in USD

​
Execution Response (202)

After payment, the call is initiated:
​
request_id
string
Job ID for tracking call status
​
status
string
processing - call is in progress
​
call.from_number
string
The phone number making the call
​
call.target_numbers
string[]
Numbers being called
​
call.conference_mode
boolean
Whether this is a conference call

​
Completed Job Result

Poll /v1/requests/{request_id} for the result:
​
result.transcript
string
Full call transcript
​
result.summary
string
AI-generated call summary
​
result.success_evaluation
string
pass or fail based on success criteria
​
result.duration_seconds
number
Actual call duration
​
result.cost
number
Actual cost charged
curl -X POST https://win.oneshotagent.com/v1/tools/voice/call \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "objective": "Call the restaurant to make a dinner reservation for 2 people at 7pm tonight",
    "target_number": "+14155551234",
    "caller_persona": "A polite assistant making a reservation",
    "context": "Italian restaurant, prefer outdoor seating"
  }'

{
  "error": "payment_required",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1.25",
    "recipient": "0x..."
  },
  "context": {
    "tool": "voice",
    "quote_id": "quote_abc123",
    "target_numbers": ["+14155551234"],
    "conference_mode": false,
    "objective_summary": "Make a dinner reservation for 2 at 7pm",
    "talking_points": [
      "Request table for 2 at 7pm tonight",
      "Ask about outdoor seating availability",
      "Confirm reservation details"
    ],
    "success_criteria": [
      "Reservation confirmed",
      "Time slot secured"
    ],
    "estimated_duration_minutes": 3,
    "total": "1.25"
  }
}

​
Conference Calls

When multiple phone numbers are provided AND the objective suggests a multi-party call, conference mode is activated: 
const result = await agent.voice({
  objective:
    "Connect the buyer and seller to negotiate the final price. Facilitate the discussion.",
  target_number: ["+14155551234", "+14155555678"],
  caller_persona: "A professional meeting facilitator",
});
In conference mode:
  • All parties are connected to a shared call
  • The OneShot Agent moderates and facilitates the conversation
  • A shared OneShot number is used (no phone registration fee)

​
Error Handling

​
error
string
Error code: content_blocked, emergency_number_blocked, invalid_request
Content Blocked
{
  "error": "content_blocked",
  "message": "Content violates safety guidelines",
  "categories": ["harassment"]
}
Emergency Number Blocked
{
  "error": "emergency_number_blocked",
  "message": "Calls to emergency services are not permitted",
  "blocked_number": "+1911"
}
See Pricing for voice call costs. If a call fails (success_evaluation = “fail”), you’re charged at cost and credited the margin.