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"
}'
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"],
});
{
"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"
}
}
{
"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"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"delivered": 1,
"failed": 0,
"total": 1,
"status": "all_delivered"
}
}
SMS
Send SMS
Send SMS messages to one or multiple recipients
POST
/
v1
/
tools
/
sms
/
send
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"
}'
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"],
});
{
"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"
}
}
{
"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"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"delivered": 1,
"failed": 0,
"total": 1,
"status": "all_delivered"
}
}
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
string
required
SMS message body. Maximum 1600 characters.
string | string[]
required
Phone number(s) in E.164 format (e.g.,
+14155551234). Maximum 10 recipients.Quote Response (402)
string
Quote ID to include in payment request
number
Number of recipients
number
Number of SMS segments (messages over 160 chars split into segments)
string
Rate per segment per recipient
string
Total cost in USD
Execution Response (202)
string
Job ID for tracking delivery status
string
processing - messages are being sentstring[]
Recipient numbers
number
Number of segments per message
Completed Job Result
number
Number of successfully delivered messages
number
Number of failed deliveries
number
Total messages sent
string
all_delivered or partial_deliverycurl -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"
}'
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"],
});
{
"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"
}
}
{
"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"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"delivered": 1,
"failed": 0,
"total": 1,
"status": "all_delivered"
}
}
Message Segments
SMS messages are split into segments:| Character Set | Segment Size |
|---|---|
| GSM-7 (standard) | 160 characters |
| Unicode (emoji, special chars) | 70 characters |
Error Handling
Content Blocked
{
"error": "content_blocked",
"message": "Content violates safety guidelines",
"categories": ["spam"]
}
Emergency Number Blocked
{
"error": "emergency_number_blocked",
"message": "SMS to emergency services is not permitted",
"blocked_number": "+1911"
}
See Pricing for SMS costs and segment sizing details.