SMS API for chatbots and AI agents

Your AI agent needs a phone number that can receive SMS verification codes from Cash App, Coinbase, Tinder, banking apps, or any 2FA flow. Twilio rejects most of them as VoIP. Here's how to wire up a chatbot or agent to receive real SMS through MeiSIM's webhook API.

The flow at a glance

1. Your agent calls POST /v1/numbers/provision with a webhook URL.
2. ~60s later, your agent has a real US phone number (eSIM QR + ICCID + LPA returned in the response).
3. Agent uses the number to sign up on Cash App / Coinbase / etc.
4. The signup service sends a verification SMS to the number.
5. MeiSIM receives the SMS via the carrier's network (~1s).
6. MeiSIM POSTs the message to your webhook URL (~1-2s more).
7. Your agent reads the body, extracts the code, completes the signup.

Webhook contract

We POST a JSON body to your URL. You return HTTP 200 within 10 seconds to acknowledge. If you fail or time out, we retry with backoff (immediate, +15s, +60s, +300s — total 4 attempts over 6 min). Messages are also queryable via the messages endpoint for 30 days.

Polling fallback

If you'd rather poll than maintain a webhook endpoint (common for stateless agents), call:

Most agents poll every 2-3 seconds while waiting for a verification. Verification SMS typically arrives within 30 seconds; failed attempts take up to 5 minutes before retrying.

Extracting the OTP code

The SMS body varies by service but the code is always a 4-8 digit number. Most agents use a regex like /\b\d{4,8}\b/ to extract. For higher reliability, have the LLM read the text and return just the code — Claude or GPT-4o handle this in milliseconds.

Authentication and security

Every webhook POST is signed with HMAC-SHA256. Verify X-MeiSIM-Signature using your API secret to confirm the request actually came from us, not a spoofer. Code sample in API docs.