Skip to main content
Prerequisites: An SMS number must be provisioned by Momentic.
SMS runs inside the JavaScript step’s sandbox via the global sms object.

sms.send

Send an SMS from a Momentic-provisioned number.

sms.fetchLatest

Returns the most recent message, polling until one arrives or the timeout elapses. Throws on timeout.
Without afterDate, fetchLatest may return stale messages from previous runs. Keep tests single-flow per number to avoid race conditions.

sms.lease

Check out a free phone number from your org’s pool for the duration of a test. Numbers are mutually exclusive: while a number is leased, no other test in your org can claim it. Use this when running tests in parallel against the same SMS flow (e.g. multiple OTP signups in CI), to avoid two tests racing on the same inbound code.
You do not release the number yourself. It returns to the pool automatically when the test finishes, in two layers:
  1. Local CLI cleanup. When a test process exits, including a crash, a thrown exception, or a Ctrl-C, the CLI best-effort releases every lease the test still holds before tearing down.
  2. Server-side TTL sweep. If even the local cleanup misses (kill -9, network partition), the lease expires after ttlMs (default 5 minutes) and a background sweep returns the number to the pool within ~1 minute.

sms.release (optional)

If you want a number freed during the test (e.g. you only need it for the OTP fetch and have a long flow afterwards), call sms.release with the leaseToken returned by lease():
The leaseToken is an opaque scoping handle: thread it back into release().

Pool exhaustion

sms.lease() accepts options for tuning lease duration and wait behavior:
If every number in your pool is already leased when you call sms.lease(), it polls for up to timeoutMs (default ~30 seconds) waiting for one to free up. If no number becomes available in that window, it throws:
Pass timeoutMs: 0 to fail fast instead of waiting:
The JavaScript step defaults to a 90 second timeout. On Momentic cloud, this is effectively capped at 60 seconds by the platform; on the CLI, it can be configured up to 10 minutes. If you raise timeoutMs past the JavaScript step’s timeout, or chain sms.lease with a long fetchLatest poll, set the JavaScript step’s Timeout field high enough to cover the whole script or the step will be killed before your code returns.

Monitoring the pool

Lease state is visible in Settings > Phone numbers. Every provisioned number shows whether it’s currently leased and when its lease expires.
Phone numbers settings page

Phone numbers settings page showing per-number lease state