SMS

SMS is receive-only. Runtime calls are authenticated with AGNT_KEY.

GET /v1/sms/number

Return the current assigned phone number or null.

{
  "number": "+13156200700",
  "country_iso2": "US",
  "provider": "textverified"
}

GET /v1/sms/messages

List stored SMS history.

Query parameters:

• limit: default 20, max 100
• offset: default 0
• direction: optional inbound or outbound

Behavior:

• before returning history, AgentID syncs the newest 100 provider messages
• messages are ordered newest-first
• provider messages are upserted into Postgres and then paginated from local state
• SMS uses offset pagination because this history is synced into a bounded local list before results are returned

Example response:

[
  {
    "message_id": "uuid",
    "direction": "inbound",
    "from_number": "61476882350",
    "to_number": "3156200700",
    "raw_payload": {
      "source": "textverified",
      "provider_message_id": "01KKR4RYSNNNSBYFS8XF4X6KYE",
      "from_number": "61476882350",
      "to_number": "3156200700",
      "raw_message": "test",
      "parsed_code": null,
      "provider_received_at": "2026-03-15T07:01:10.069868+00:00",
      "service_name": "manual-test"
    },
    "created_at": "2026-03-15T07:01:10.069868+00:00"
  }
]

POST /v1/sms/wait-for-code

Return the newest unseen SMS immediately, or wait for a new one.

Request:

{
  "service_name": "brevo",
  "timeout": 300,
  "request_id": "otp-req-1"
}

Response:

{
  "code": "766136",
  "from_number": "8556428544",
  "raw_message": "Your Brevo activation code is 766136.",
  "received_at": "2026-03-11T11:58:17.554867+00:00",
  "request_id": "otp-req-1"
}

Retry and idempotency:

• if an unseen stored/provider message already exists, it is returned immediately
• otherwise AgentID blocks on the provider until timeout
• reuse a client request_id if you need safe retries for the same waiting request

Errors:

• 400 no phone number provisioned
• 401 invalid AGNT_KEY
• 408 timeout waiting for verification code