twilio

# Twilio API Emulator Stateful Twilio REST emulation with seeded accounts, Auth Tokens, API keys, incoming phone numbers, Programmable Messaging, Messaging Services, Verify, basic Voice calls, Conversations REST resources, signed webhooks, local simulator routes, and an inspector. ## Start Local listeners bind to `127.0.0.1` by default. For access from containers or other machines, pass `--host 0.0.0.0` to the CLI or `hostname: '0.0.0.0'` to `createEmulator`. Configure `--base-url` or `baseUrl` for advertised URLs reachable by those clients. ```bash npx emulate --service twilio ``` Default URL: `http://localhost:4013` when all services are started, or `http://localhost:4000` when Twilio is the only service. ## Defaults ```text TWILIO_ACCOUNT_SID=AC00000000000000000000000000000000 TWILIO_AUTH_TOKEN=twilio_test_auth_token TWILIO_API_KEY=SK00000000000000000000000000000000 TWILIO_API_SECRET=twilio_test_api_secret TWILIO_PHONE_NUMBER=+15551234567 TWILIO_VERIFY_SERVICE_SID=VA00000000000000000000000000000000 ``` ## URL Mapping | Real Twilio URL | Emulator URL | |-----------------|--------------| | `https://api.twilio.com/2010-04-01/...` | `$TWILIO_EMULATOR_URL/2010-04-01/...` | | `https://messaging.twilio.com/v1/...` | `$TWILIO_EMULATOR_URL/messaging/v1/...` | | `https://verify.twilio.com/v2/...` | `$TWILIO_EMULATOR_URL/verify/v2/...` | The official Node SDK builds absolute Twilio product URLs. In SDK tests, use a custom request client that rewrites those hosts to the emulator prefixes above. ## Auth HTTP Basic auth accepts either: - Account SID and Auth Token - API Key SID and API Key Secret ## Core Routes - `POST /2010-04-01/Accounts/{AccountSid}/Messages.json` - create outbound message - `GET /2010-04-01/Accounts/{AccountSid}/Messages.json` - list messages - `POST /2010-04-01/Accounts/{AccountSid}/Calls.json` - create outbound call - `POST /verify/v2/Services/{ServiceSid}/Verifications` - start verification - `POST /verify/v2/Services/{ServiceSid}/VerificationCheck` - check verification code - `POST /conversations/v1/Services/{ServiceSid}/Conversations` - create Conversation - `POST /conversations/v1/Services/{ServiceSid}/Conversations/{ConversationSid}/Participants` - add participant - `POST /conversations/v1/Services/{ServiceSid}/Conversations/{ConversationSid}/Messages` - add message - `POST /_twilio/simulate/inbound-message` - simulate inbound SMS - `POST /_twilio/simulate/message-status` - simulate message status callback - `POST /_twilio/simulate/inbound-call` - simulate inbound call ## SMS And OTP Testing - The seeded Verify Service code is `123456`. - Use `CustomCode` when creating a Verification to force a per-verification code. - Use `GET /_twilio/simulate/verification-code?To=...&ServiceSid=...` with Basic auth to fetch the latest local code for an E2E test. - Use `POST /_twilio/simulate/verification-status` with `VerificationSid` or `To` to force local Verify state. - Use `POST /_twilio/simulate/inbound-message` to test inbound SMS webhooks. - Inbound SMS uses an assigned Messaging Service `inbound_request_url` before falling back to the phone number `sms_url`. - Use `POST /_twilio/simulate/message-status` to test outbound status callbacks. ## Current Limits No real SMS, MMS, WhatsApp, email, voice, carrier, compliance, billing, SendGrid, Studio, Flex, TaskRouter, Video, Sync, Segment, Conversations SDK websocket behavior, or complete TwiML interpreter behavior is implemented. ## Custom emulators alongside built-ins Use `npx emulate init --custom inventory` to scaffold a third-party API emulator and test. Register it in `emulate.config.ts` with `defineConfig` from `emulate`, alongside built-in entries such as `{ emulator: "twilio" }`. Run `npx emulate start --watch` to reload imports and inspect custom state at the printed `/_emulate` URL. Successful reloads reset the run to seed. Existing flat seed configs still work; `--config` selects an explicit file. For authoring and testing third-party API emulators, see https://emulate.dev/docs/custom-emulators.