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.0035",
"recipient": "0x..."
},
"context": {
"tool": "sms",
"quote_id": "quote_sms_abc123",
"recipient_count": 1,
"message_length": 52,
"segment_count": 1,
"per_message_rate": "0.0035",
"messaging_fee": "0.0035",
"phone_registration_fee": "0.00",
"total": "0.0035"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"tool": "sms",
"message": "SMS queued for delivery.",
"sms": {
"to_numbers": ["+14155551234"],
"segment_count": 1,
"total_quoted": "0.0035"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"delivered": 1,
"failed": 0,
"total": 1,
"status": "all_delivered"
}
}
SMS
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.0035",
"recipient": "0x..."
},
"context": {
"tool": "sms",
"quote_id": "quote_sms_abc123",
"recipient_count": 1,
"message_length": 52,
"segment_count": 1,
"per_message_rate": "0.0035",
"messaging_fee": "0.0035",
"phone_registration_fee": "0.00",
"total": "0.0035"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"tool": "sms",
"message": "SMS queued for delivery.",
"sms": {
"to_numbers": ["+14155551234"],
"segment_count": 1,
"total_quoted": "0.0035"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"delivered": 1,
"failed": 0,
"total": 1,
"status": "all_delivered"
}
}
Overview
Sends one text to one or more recipients (up to 10 per call), with automatic carrier routing. You pay per segment per recipient.Authentication
Requires x402 payment. The first call returns a quote (402). The second call, with payment, sends.Headers
Opt-in replay safety for the paid send (the request carrying
X-Quote-ID).
Pass any string up to 255 characters ([A-Za-z0-9_.:-]). Retrying the
same key with the same to_number and message returns the original
response without sending or charging again. The same key with a
different to_number or message returns 422 idempotency_key_reuse,
and a retry while the first request is still running returns
409 request_in_flight. The key is checked before the quote, so a retry
that reuses the key replays even if it carries a new X-Quote-ID.Without a key, a quote still pays for one send: retrying with the same
X-Quote-ID is rejected with 400 invalid_quote (quote already used),
so you cannot tell from that retry whether the first send went out.
Requesting a new quote and paying again sends the text again and
charges again. Send an Idempotency-Key whenever you might retry.Request Body
Phone number(s) in E.164 format (e.g.,
+14155551234). Maximum 10 recipients.The recipient’s IANA time zone, such as
America/Los_Angeles. Texts wait outside 21:00 to 08:00 there. Without it the zone comes from the number; see refusals.Quote Response (402)
Execution Response (202)
Completed Job Result
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.0035",
"recipient": "0x..."
},
"context": {
"tool": "sms",
"quote_id": "quote_sms_abc123",
"recipient_count": 1,
"message_length": 52,
"segment_count": 1,
"per_message_rate": "0.0035",
"messaging_fee": "0.0035",
"phone_registration_fee": "0.00",
"total": "0.0035"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"tool": "sms",
"message": "SMS queued for delivery.",
"sms": {
"to_numbers": ["+14155551234"],
"segment_count": 1,
"total_quoted": "0.0035"
}
}
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"delivered": 1,
"failed": 0,
"total": 1,
"status": "all_delivered"
}
}
Message Segments
The character set decides how a message is 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"]
}
Moderation Unavailable (503)
{
"error": "moderation_unavailable",
"message": "Content moderation is temporarily unavailable, so this message was not sent. Retry shortly.",
"retryable": true
}
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.