curl -X GET "https://win.oneshotagent.com/v1/tools/sms/inbox?limit=10" \
-H "X-Agent-ID: 0xYourWalletAddress"
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
// List recent messages
const inbox = await agent.smsInboxList({ limit: 10 });
for (const msg of inbox.messages) {
console.log(`From ${msg.from}: ${msg.body}`);
}
// Filter by sender
const fromCustomer = await agent.smsInboxList({
from: "+14155551234",
limit: 20,
});
// Get messages since a timestamp
const recent = await agent.smsInboxList({
since: "2024-01-01T00:00:00Z",
});
{
"messages": [
{
"id": "msg_abc123",
"from": "+14155551234",
"to": "+14151234567",
"body": "Yes, I'd like to confirm my appointment",
"num_media": 0,
"media_urls": null,
"thread_id": "msg_outbound_xyz",
"related_outbound_id": "msg_outbound_xyz",
"received_at": "2024-01-15T10:30:00Z",
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "msg_def456",
"from": "+14155559876",
"to": "+14151234567",
"body": "Thanks for the update!",
"num_media": 1,
"media_urls": ["https://media.oneshotagent.com/..."],
"thread_id": null,
"related_outbound_id": null,
"received_at": "2024-01-15T09:15:00Z",
"created_at": "2024-01-15T09:15:00Z"
}
],
"count": 2
}
SMS
SMS Inbox
List inbound SMS messages received by your agent
GET
/
v1
/
tools
/
sms
/
inbox
curl -X GET "https://win.oneshotagent.com/v1/tools/sms/inbox?limit=10" \
-H "X-Agent-ID: 0xYourWalletAddress"
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
// List recent messages
const inbox = await agent.smsInboxList({ limit: 10 });
for (const msg of inbox.messages) {
console.log(`From ${msg.from}: ${msg.body}`);
}
// Filter by sender
const fromCustomer = await agent.smsInboxList({
from: "+14155551234",
limit: 20,
});
// Get messages since a timestamp
const recent = await agent.smsInboxList({
since: "2024-01-01T00:00:00Z",
});
{
"messages": [
{
"id": "msg_abc123",
"from": "+14155551234",
"to": "+14151234567",
"body": "Yes, I'd like to confirm my appointment",
"num_media": 0,
"media_urls": null,
"thread_id": "msg_outbound_xyz",
"related_outbound_id": "msg_outbound_xyz",
"received_at": "2024-01-15T10:30:00Z",
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "msg_def456",
"from": "+14155559876",
"to": "+14151234567",
"body": "Thanks for the update!",
"num_media": 1,
"media_urls": ["https://media.oneshotagent.com/..."],
"thread_id": null,
"related_outbound_id": null,
"received_at": "2024-01-15T09:15:00Z",
"created_at": "2024-01-15T09:15:00Z"
}
],
"count": 2
}
Overview
Returns SMS messages sent to your agent’s phone number, threaded with related outbound messages.Authentication
Requires theX-Agent-ID header with your wallet address.
Reads require a signed read proof (x-agent-proof header) showing you control that wallet.
Query Parameters
string
ISO timestamp. Returns messages received after it
number
Maximum messages to return (default: 50, max: 100)
string
Filter by sender phone number
Response
array
Inbound SMS messages
string
Message ID
string
Sender phone number
string
Your agent’s phone number
string
Message content
number
Number of media attachments (MMS)
string[]
URLs to media attachments
string
ID of the related outbound message
string
ISO receive timestamp
number
Number of messages returned
curl -X GET "https://win.oneshotagent.com/v1/tools/sms/inbox?limit=10" \
-H "X-Agent-ID: 0xYourWalletAddress"
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
// List recent messages
const inbox = await agent.smsInboxList({ limit: 10 });
for (const msg of inbox.messages) {
console.log(`From ${msg.from}: ${msg.body}`);
}
// Filter by sender
const fromCustomer = await agent.smsInboxList({
from: "+14155551234",
limit: 20,
});
// Get messages since a timestamp
const recent = await agent.smsInboxList({
since: "2024-01-01T00:00:00Z",
});
{
"messages": [
{
"id": "msg_abc123",
"from": "+14155551234",
"to": "+14151234567",
"body": "Yes, I'd like to confirm my appointment",
"num_media": 0,
"media_urls": null,
"thread_id": "msg_outbound_xyz",
"related_outbound_id": "msg_outbound_xyz",
"received_at": "2024-01-15T10:30:00Z",
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "msg_def456",
"from": "+14155559876",
"to": "+14151234567",
"body": "Thanks for the update!",
"num_media": 1,
"media_urls": ["https://media.oneshotagent.com/..."],
"thread_id": null,
"related_outbound_id": null,
"received_at": "2024-01-15T09:15:00Z",
"created_at": "2024-01-15T09:15:00Z"
}
],
"count": 2
}
Threading
Replies thread to what you sent. An inbound message is linked to an outbound message when:- The sender matches a recent recipient (within 24 hours)
- The phone numbers match
thread_id to follow a conversation.
Notes
- Free (no payment required)
- Messages are retained for 30 days
- MMS media URLs expire after 7 days