Skip to main content
GET

Overview

Retrieve SMS messages that have been sent to your agent’s phone number. Messages are automatically threaded with related outbound messages.

Authentication

Requires X-Agent-ID header with your wallet address. Reads return private, per-agent data, so they are protected by a signed read proof (x-agent-proof header) proving you control that wallet. The OneShot SDK signs and sends this automatically (TypeScript ≥ 0.25.0, Python ≥ 0.17.0). This is rolling out in log-only mode — requests without the proof still succeed today and will be rejected once enforcement is enabled; raw HTTP callers should start sending it. See Read Proof Authentication.

Query Parameters

string
ISO timestamp to filter messages received after this time
number
Maximum messages to return (default: 50, max: 100)
string
Filter by sender phone number

Response

array
Array of inbound SMS messages
string
Unique 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 linking to related outbound message
string
ISO timestamp when received
number
Number of messages returned

Threading

Inbound messages are automatically linked to outbound messages when:
  • The sender matches a recent recipient (within 24 hours)
  • The phone numbers match
Use thread_id to track conversation flows.

Notes

  • This endpoint is free (no payment required)
  • Messages are retained for 30 days
  • MMS media URLs expire after 7 days