Skip to main content
GET
/
v1
/
tools
/
sms
/
inbox
curl -X GET "https://win.oneshotagent.com/v1/tools/sms/inbox?limit=10" \
  -H "X-Agent-ID: 0xYourWalletAddress"

{
  "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

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.

​
Query Parameters

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

​
Response

​
messages
array
Array of inbound SMS messages
​
messages[].id
string
Unique message ID
​
messages[].from
string
Sender phone number
​
messages[].to
string
Your agent’s phone number
​
messages[].body
string
Message content
​
messages[].num_media
number
Number of media attachments (MMS)
​
messages[].media_urls
string[]
URLs to media attachments
​
messages[].thread_id
string
ID linking to related outbound message
​
messages[].received_at
string
ISO timestamp when received
​
count
number
Number of messages returned
curl -X GET "https://win.oneshotagent.com/v1/tools/sms/inbox?limit=10" \
  -H "X-Agent-ID: 0xYourWalletAddress"

{
  "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

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