---
name: otp-sessions
description: AgentSIM OTP sessions and delivery diagnostics for browser agents, MCP clients, Playwright/Cypress tests, and controlled auth workflows. Use this skill whenever an agent needs a temporary phone number for SMS OTP, phone verification, wait_for_otp, no_sms debugging, Supabase/Auth0/Firebase/Clerk phone auth, or browser-agent QA. Trigger on phrases like "OTP session", "phone OTP", "SMS verification", "no SMS arrived", "Playwright OTP", "MCP phone number", or "AgentSIM".
---

# AgentSIM OTP Sessions

Use AgentSIM to provision a temporary programmable US number for one OTP attempt, wait for SMS, parse the OTP, inspect delivery failures, and release the session.

AgentSIM is **not** a universal phone-verification bypass. Treat destination support as empirical.

## When to use

Use this skill when the task involves:

- browser agents that need to enter a phone number and OTP
- Playwright, Cypress, Selenium, Browserbase, Stagehand, or browser-use tests
- MCP clients such as Claude Code, Cursor, Windsurf, or Claude Desktop
- controlled auth flows such as Supabase Auth, Auth0 Passwordless SMS, Firebase Phone Auth, Clerk, or custom OTP systems
- debugging `otp_timeout`, `no_sms`, `sms_no_otp`, `phone_rejected`, or anti-bot gates

Do **not** use this skill to promise that AgentSIM works on every consumer platform. Check evidence first for strict targets.

## Core workflow

1. Check whether the target service/workflow is known to work with AgentSIM.
   - Support evidence: https://agentsim.dev/use-cases/browser-agent-otp-qa#delivery-truth
   - Concepts: https://docs.agentsim.dev/concepts
2. Provision a session.
3. Enter the returned number into the target workflow.
4. Wait for OTP.
5. If timeout occurs, inspect raw messages and classify outcome.
6. Release the session in a `finally` path.

## MCP tool sequence

Use these tools when available:

- `provision_number` — lease a temporary number
- `wait_for_otp` — wait for a parsed OTP
- `get_messages` — inspect raw SMS after timeout or parser uncertainty
- `release_number` — close the session and return the number
- `list_numbers` — inspect active sessions

Recommended sequence:

```text
provision_number -> enter number in browser/control flow -> wait_for_otp -> get_messages if needed -> release_number
```

## SDK shape

TypeScript:

```typescript
import { provision, OtpTimeoutError } from "@agentsim/sdk";

await using session = await provision({
  agentId: "browser-agent-otp",
  country: "US",
  serviceUrl: "https://staging.example.com/login",
  ttlSeconds: 900,
});

try {
  const otp = await session.waitForOtp({ timeout: 120 });
  return { outcome: "otp_received", code: otp.otpCode };
} catch (error) {
  if (error instanceof OtpTimeoutError) {
    const messages = await session.getMessages();
    return { outcome: messages.length ? "sms_no_otp" : "no_sms", messages };
  }
  throw error;
}
```

Python:

```python
import agentsim

async with agentsim.provision(
    agent_id="browser-agent-otp",
    country="US",
    service_url="https://staging.example.com/login",
    ttl_seconds=900,
) as session:
    try:
        otp = await session.wait_for_otp(timeout=120)
        return {"outcome": "otp_received", "code": otp.otp_code}
    except agentsim.OtpTimeoutError:
        messages = await session.messages()
        return {"outcome": "sms_no_otp" if messages else "no_sms", "messages": messages}
```

## Outcome taxonomy

Always preserve delivery truth:

| Outcome | Meaning |
|---|---|
| `otp_received` | SMS arrived and OTP parsed |
| `sms_no_otp` | SMS arrived, but no OTP was parseable |
| `no_sms` | Target appeared to send SMS, but AgentSIM received nothing in the wait window |
| `phone_rejected` | Target rejected the number before SMS |
| `anti_bot_gate` | CAPTCHA, hCaptcha, Arkose, visual puzzle, or bot gate blocked the flow before phone verdict |
| `email_only_flow` | Reachable flow did not use phone/SMS |
| `pre_form_failure` | Browser could not reach a stable form |

## Safety rules

- Never claim AgentSIM is real-SIM, physical-SIM, carrier-grade mobile, or works everywhere.
- For Google, Meta, Stripe, WhatsApp, banks, crypto, and other strict platforms, check evidence before attempting.
- If the target rejects the number, do not keep burning sessions blindly.
- If no SMS arrives, inspect raw messages and provider logs before retrying.
- Always release sessions.
- Billing is tied to provisioned sessions after the free tier; do not tell users timeouts are automatically free.

## Best-fit use cases

- owned/staging auth flows
- QA automation
- browser-agent test harnesses
- controlled auth provider audits
- known-compatible OTP destinations
- delivery diagnostics when SMS does not arrive

## Docs

- Quickstart: https://docs.agentsim.dev/quickstart
- Concepts: https://docs.agentsim.dev/concepts
- Authentication: https://docs.agentsim.dev/authentication
- API reference: https://docs.agentsim.dev/api-reference/overview
- MCP setup: https://docs.agentsim.dev/mcp/connect
- MCP tools: https://docs.agentsim.dev/mcp/tools
- Support evidence: https://agentsim.dev/use-cases/browser-agent-otp-qa#delivery-truth