curl -X POST https://win.oneshotagent.com/v1/tools/voice/call \
-H "Content-Type: application/json" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-d '{
"objective": "Book a dinner table for 2 at 7pm tonight",
"target_number": "+14155551234",
"caller_name": "Sam Lee",
"context": "Italian restaurant, prefer outdoor seating"
}'
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const result = await agent.voice({
objective: "Book a dinner table for 2 at 7pm tonight",
target_number: "+14155551234",
caller_name: "Sam Lee",
context: "Italian restaurant, prefer outdoor seating",
maxCost: 5,
});
console.log(result.outcome, result.success_evaluation);
console.log(result.transcript);
{
"error": "payment_required",
"context": {
"tool": "voice",
"quote_id": "quote_abc123",
"target_numbers": ["+14155551234"],
"conference_mode": false,
"success_criteria": ["Table booked for 2 at 7pm"],
"estimated_duration_minutes": 3,
"total": "1.25"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"status": "ended",
"ended_reason": "customer-ended-call",
"outcome": "reached_person",
"success_evaluation": "pass",
"duration_seconds": 147,
"transcript": "Hi, this is Sam Lee. I'd like a table for two at 7pm...",
"summary": "Booked a table for 2 at 7pm, outdoor seating.",
"structured_data": {
"outcome": "reached_person",
"objective_met": true,
"next_steps": "",
"callback_requested": false
},
"recording_url": "https://storage.example.com/recording.wav",
"cost": 0.86,
"credit_issued": 0.39
}
}
Voice
Voice Call
Place a phone call toward an objective and get the transcript and outcome
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": "Book a dinner table for 2 at 7pm tonight",
"target_number": "+14155551234",
"caller_name": "Sam Lee",
"context": "Italian restaurant, prefer outdoor seating"
}'
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const result = await agent.voice({
objective: "Book a dinner table for 2 at 7pm tonight",
target_number: "+14155551234",
caller_name: "Sam Lee",
context: "Italian restaurant, prefer outdoor seating",
maxCost: 5,
});
console.log(result.outcome, result.success_evaluation);
console.log(result.transcript);
{
"error": "payment_required",
"context": {
"tool": "voice",
"quote_id": "quote_abc123",
"target_numbers": ["+14155551234"],
"conference_mode": false,
"success_criteria": ["Table booked for 2 at 7pm"],
"estimated_duration_minutes": 3,
"total": "1.25"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"status": "ended",
"ended_reason": "customer-ended-call",
"outcome": "reached_person",
"success_evaluation": "pass",
"duration_seconds": 147,
"transcript": "Hi, this is Sam Lee. I'd like a table for two at 7pm...",
"summary": "Booked a table for 2 at 7pm, outdoor seating.",
"structured_data": {
"outcome": "reached_person",
"objective_met": true,
"next_steps": "",
"callback_requested": false
},
"recording_url": "https://storage.example.com/recording.wav",
"cost": 0.86,
"credit_issued": 0.39
}
}
Overview
Places a phone call toward your objective. The result has the transcript, a summary, theoutcome and a recording link.
On a call it:
- Leaves a short message when it reaches voicemail.
- Presses keys at a phone menu, or asks for a person.
- Waits quietly on hold. A long silence ends the call.
Authentication
Requires x402 payment. The first call returns a quote (402). The second call, with payment, places the call.Request Body
string
What the call should accomplish. 10 to 5,000 characters.
string
Alias for
objective. 10 to 5,000 characters.objective or raw_objective.
Paid retries may omit both; they use the stored quote’s objective.
Aliases resolve before validation, staging allowance reservation, and moderation.
If both are supplied, they must be identical strings. Non-string or conflicting
aliases return 400 before reservation or calling, including on paid retries.
The resolved objective is moderated before quote preparation.
string | string[]
required
Number(s) in E.164 format, such as
+14155551234. Up to 5 numbers for a conference call.string
The name the caller gives: the person or business the call is for.
string
Who the caller is and how they speak.
string
Background the caller needs.
number
Longest the call may run, 1 to 30. Default: the quote’s
estimated_duration_minutes.Who the caller says it is
The caller usescaller_name. Without it, the name in caller_persona. Without either, your agent’s name if it reads like a person’s. Otherwise “Janine, an assistant”.
Quote Response (402)
Returnscontext.quote_id, context.success_criteria, context.estimated_duration_minutes, context.conference_mode and context.total.
Completed Job Result
After payment the call starts (202). Poll/v1/requests/{request_id} for the result. The SDKs wait for it: max_duration_minutes (10 if unset) plus two minutes.
string | null
reached_person, voicemail_left, no_answer, refused, phone_menu_dead_end or wrong_number.string
pass or fail. A voicemail passes only when the objective allows a message.string | null
Link to the call recording.
string
The transcript.
string
Short summary.
number
Call length.
curl -X POST https://win.oneshotagent.com/v1/tools/voice/call \
-H "Content-Type: application/json" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-d '{
"objective": "Book a dinner table for 2 at 7pm tonight",
"target_number": "+14155551234",
"caller_name": "Sam Lee",
"context": "Italian restaurant, prefer outdoor seating"
}'
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const result = await agent.voice({
objective: "Book a dinner table for 2 at 7pm tonight",
target_number: "+14155551234",
caller_name: "Sam Lee",
context: "Italian restaurant, prefer outdoor seating",
maxCost: 5,
});
console.log(result.outcome, result.success_evaluation);
console.log(result.transcript);
{
"error": "payment_required",
"context": {
"tool": "voice",
"quote_id": "quote_abc123",
"target_numbers": ["+14155551234"],
"conference_mode": false,
"success_criteria": ["Table booked for 2 at 7pm"],
"estimated_duration_minutes": 3,
"total": "1.25"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"status": "ended",
"ended_reason": "customer-ended-call",
"outcome": "reached_person",
"success_evaluation": "pass",
"duration_seconds": 147,
"transcript": "Hi, this is Sam Lee. I'd like a table for two at 7pm...",
"summary": "Booked a table for 2 at 7pm, outdoor seating.",
"structured_data": {
"outcome": "reached_person",
"objective_met": true,
"next_steps": "",
"callback_requested": false
},
"recording_url": "https://storage.example.com/recording.wav",
"cost": 0.86,
"credit_issued": 0.39
}
}
Conference Calls
Pass several numbers and an objective about connecting them. Everyone joins one call, which the caller moderates. It uses a shared number, with no phone registration fee.Errors
content_blocked: the objective breaks the content rules. moderation_unavailable (503): the content moderation provider could not be reached, so no call was placed and a settled payment is returned as credit; retry after Retry-After. emergency_number_blocked: emergency numbers cannot be called. invalid_request: fix the field it names.
See Pricing for costs. When
success_evaluation is fail, part of the charge is credited back. credit_issued shows the amount.