mcpField
T
twilio

twilio

github.com/vercel-labsTesting & quality2.0k75 installsUpdated 2d ago
Repository

About twilio

A stateful emulator of Twilio’s REST API for developers testing messaging, verification, calls, and conversations locally. It includes seeded credentials and routes for simulating inbound events and callbacks.

Key features

  1. 01Stateful Twilio REST API emulation
  2. 02Seeded accounts and credentials
  3. 03Messaging, Verify, Voice, Conversations routes
  4. 04Inbound event and callback simulation
  5. 05Local verification-code inspection

Use cases

  1. 01Test outbound messaging and status callbacks
  2. 02Exercise OTP verification flows
  3. 03Simulate inbound SMS and calls
  4. 04Test applications without real Twilio traffic

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/vercel-labs/emulate --skill twilio

After installing, type/twilioin Claude Code to confirm it loaded.

Details

From the project README

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.

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

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 URLEmulator 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.

Comments

Markdown supported