API reference

Every operation of the mock is live: the message is stored, the lifecycle runs and the webhooks leave the service. The native API speaks JSON, the Twilio API the form fields a Twilio SDK sends, and the simple API a query string.

Conventions

Base URL: http://localhost:8899, the port the container publishes on the host.
Authentication: none. The mock has no key: any Authorization header is accepted, Basic or Bearer, and the Twilio API ignores the credentials.
Errors: three shapes, one per API. The native API answers {"error":{"code","message","field"}}, the Twilio API {code,message,more_info,status} and the simple API {status:"error",code,message}.
Webhooks: a status event for every status change and an inbound event when the handset replies, posted as JSON or, for a message that came through the Twilio API, as a form. With SMS_WEBHOOK_SECRET set, the body is signed with x-sms-signature: sha256=<hmac>.
Local guard: every route but GET /health asks for an admitted Host; the state-changing methods, the /ws handshake and GET /sms/send also ask for an admitted Origin.

The code of every refusal is in the docs.

The operations

Every operation the application calls, with the parameters it takes, the request example and every answer with its example, errors included. Open one to read it.

The magic numbers

The mock reads the last four digits of the number and stages a failure with them, so the failure a test wants is the number it sends to. Every other number delivers normally.

Last four digits	What happens	Final status	Error code
`0001`	The handset is unreachable.	`failed`	30003
`0002`	The handset is unknown.	`undelivered`	30005
`0003`	The API refuses the number; the request answers HTTP 400 and nothing is stored.	—	21211
`0004`	The message is sent and the handset never answers.	`sent`	—
`0005`	The carrier filters the message.	`failed`	30007
any other	The message walks the whole life.	`delivered`	—

The mock's own routes

Only for what an application has no endpoint for: the settings of the mock, the reply of the handset, the status by hand, the clean store between tests and the log of the webhook attempts. Open a route for what it takes and what it answers: every answer below, errors included, was captured from a run of the image.