> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Call

> Make an autonomous voice call with automatic objective analysis

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

<ParamField body="objective" type="string" required>
  What the call should accomplish. Minimum 10 characters. The OneShot Agent will analyze this to generate talking points and success criteria.
</ParamField>

<ParamField body="target_number" type="string | string[]" required>
  Phone number(s) in E.164 format (e.g., `+14155551234`). Multiple numbers triggers conference mode analysis.
</ParamField>

<ParamField body="caller_persona" type="string" optional>
  Personality and style for the OneShot Agent caller (e.g., "A polite assistant making a reservation")
</ParamField>

<ParamField body="context" type="string" optional>
  Additional context about the call situation
</ParamField>

<ParamField body="max_duration_minutes" type="number" optional>
  Maximum call duration (1-30 minutes). Default: 5
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Quote Response (402)

The first request returns pricing and analysis:

<ResponseField name="context.quote_id" type="string">
  Quote ID to include in payment request
</ResponseField>

<ResponseField name="context.objective_summary" type="string">
  AI-generated summary of the call objective
</ResponseField>

<ResponseField name="context.talking_points" type="string[]">
  Key points the OneShot Agent will cover during the call
</ResponseField>

<ResponseField name="context.success_criteria" type="string[]">
  How success will be evaluated
</ResponseField>

<ResponseField name="context.conference_mode" type="boolean">
  Whether this will be a conference call
</ResponseField>

<ResponseField name="context.total" type="string">
  Total cost in USD
</ResponseField>

## Execution Response (202)

After payment, the call is initiated:

<ResponseField name="request_id" type="string">
  Job ID for tracking call status
</ResponseField>

<ResponseField name="status" type="string">
  `processing` - call is in progress
</ResponseField>

<ResponseField name="call.from_number" type="string">
  The phone number making the call
</ResponseField>

<ResponseField name="call.target_numbers" type="string[]">
  Numbers being called
</ResponseField>

<ResponseField name="call.conference_mode" type="boolean">
  Whether this is a conference call
</ResponseField>

## Completed Job Result

Poll `/v1/requests/{request_id}` for the result:

<ResponseField name="result.transcript" type="string">
  Full call transcript
</ResponseField>

<ResponseField name="result.summary" type="string">
  AI-generated call summary
</ResponseField>

<ResponseField name="result.success_evaluation" type="string">
  `pass` or `fail` based on success criteria
</ResponseField>

<ResponseField name="result.duration_seconds" type="number">
  Actual call duration
</ResponseField>

<ResponseField name="result.cost" type="number">
  Actual cost charged
</ResponseField>

<RequestExample>
  ```bash cURL (Get Quote) theme={null}
  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"
    }'
  ```

  ```typescript SDK theme={null}
  import { OneShot } from "@oneshot-agent/sdk";

  const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

  const result = await agent.voice({
    objective: "Call the restaurant to make a dinner reservation for 2 at 7pm",
    target_number: "+14155551234",
    caller_persona: "A polite assistant making a reservation",
    context: "Italian restaurant, prefer outdoor seating",
    maxCost: 5,
  });

  console.log("Transcript:", result.transcript);
  console.log("Summary:", result.summary);
  console.log("Success:", result.success_evaluation);
  ```
</RequestExample>

<ResponseExample>
  ```json Quote Response (402) theme={null}
  {
    "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"
    }
  }
  ```

  ```json Execution Response (202) theme={null}
  {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "tool": "voice",
    "message": "Call initiated. Results available at /v1/requests/{id}.",
    "call": {
      "target_numbers": ["+14155551234"],
      "from_number": "+14151234567",
      "conference_mode": false,
      "estimated_duration_minutes": 3,
      "total_quoted": "1.25"
    }
  }
  ```

  ```json Completed Result theme={null}
  {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "result": {
      "status": "ended",
      "ended_reason": "customer-ended-call",
      "duration_seconds": 147,
      "transcript": "Agent: Hi, I'm calling to make a dinner reservation...",
      "summary": "Successfully made a reservation for 2 at 7pm. Outdoor seating confirmed.",
      "success_evaluation": "pass",
      "cost": 0.86,
      "credit_issued": 0.39
    }
  }
  ```
</ResponseExample>

## Conference Calls

When multiple phone numbers are provided AND the objective suggests a multi-party call, conference mode is activated:

```typescript theme={null}
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

<ResponseField name="error" type="string">
  Error code: `content_blocked`, `emergency_number_blocked`, `invalid_request`
</ResponseField>

```json Content Blocked theme={null}
{
  "error": "content_blocked",
  "message": "Content violates safety guidelines",
  "categories": ["harassment"]
}
```

```json Emergency Number Blocked theme={null}
{
  "error": "emergency_number_blocked",
  "message": "Calls to emergency services are not permitted",
  "blocked_number": "+1911"
}
```

<Info>See [Pricing](/pricing) for voice call costs. If a call fails (success\_evaluation = "fail"), you're charged at cost and credited the margin.</Info>