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

# Send SMS

> Send SMS messages to one or multiple recipients

## Overview

The SMS API enables AI agents to send text messages. Supports single or bulk sending with automatic carrier routing.

## Authentication

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

## Request Body

<ParamField body="message" type="string" required>
  SMS message body. Maximum 1600 characters.
</ParamField>

<ParamField body="to_number" type="string | string[]" required>
  Phone number(s) in E.164 format (e.g., `+14155551234`). Maximum 10 recipients.
</ParamField>

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

## Quote Response (402)

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

<ResponseField name="context.recipient_count" type="number">
  Number of recipients
</ResponseField>

<ResponseField name="context.segment_count" type="number">
  Number of SMS segments (messages over 160 chars split into segments)
</ResponseField>

<ResponseField name="context.per_message_rate" type="string">
  Rate per segment per recipient
</ResponseField>

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

## Execution Response (202)

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

<ResponseField name="status" type="string">
  `processing` - messages are being sent
</ResponseField>

<ResponseField name="sms.to_numbers" type="string[]">
  Recipient numbers
</ResponseField>

<ResponseField name="sms.segment_count" type="number">
  Number of segments per message
</ResponseField>

## Completed Job Result

<ResponseField name="result.delivered" type="number">
  Number of successfully delivered messages
</ResponseField>

<ResponseField name="result.failed" type="number">
  Number of failed deliveries
</ResponseField>

<ResponseField name="result.total" type="number">
  Total messages sent
</ResponseField>

<ResponseField name="result.status" type="string">
  `all_delivered` or `partial_delivery`
</ResponseField>

<RequestExample>
  ```bash cURL (Get Quote) theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/sms/send \
    -H "Content-Type: application/json" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -d '{
      "message": "Your order has shipped! Track it at example.com/track/123",
      "to_number": "+14155551234"
    }'
  ```

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

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

  // Single recipient
  const result = await agent.sms({
    message: "Your order has shipped!",
    to_number: "+14155551234",
  });

  // Multiple recipients
  const bulkResult = await agent.sms({
    message: "Team meeting moved to 3pm",
    to_number: ["+14155551234", "+14155555678", "+14155559012"],
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Quote Response (402) theme={null}
  {
    "error": "payment_required",
    "payment_request": {
      "chain_id": 8453,
      "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "0.02",
      "recipient": "0x..."
    },
    "context": {
      "tool": "sms",
      "quote_id": "quote_sms_abc123",
      "recipient_count": 1,
      "message_length": 52,
      "segment_count": 1,
      "per_message_rate": "0.0200",
      "messaging_fee": "0.02",
      "phone_registration_fee": "0.00",
      "total": "0.02"
    }
  }
  ```

  ```json Execution Response (202) theme={null}
  {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "tool": "sms",
    "message": "SMS queued for delivery.",
    "sms": {
      "to_numbers": ["+14155551234"],
      "routing": "hybrid",
      "segment_count": 1,
      "total_quoted": "0.02"
    }
  }
  ```

  ```json Completed Result theme={null}
  {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "result": {
      "delivered": 1,
      "failed": 0,
      "total": 1,
      "status": "all_delivered"
    }
  }
  ```
</ResponseExample>

## Message Segments

SMS messages are split into segments:

| Character Set                  | Segment Size   |
| ------------------------------ | -------------- |
| GSM-7 (standard)               | 160 characters |
| Unicode (emoji, special chars) | 70 characters  |

Long messages are automatically split and reassembled by the carrier.

## Error Handling

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

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

<Info>See [Pricing](/pricing) for SMS costs and segment sizing details.</Info>