SMS OTP Lifecycle and Status Mapping for Twilio integration

Products

• VIP Service

Issue/Introduction

This article outlines the logical flow of our SMS One-Time Password (OTP) system, from the initial API request to final user verification. Understanding these statuses is essential for troubleshooting delivery issues and monitoring user conversion.

Environment

VIP Service

Resolution

The lifecycle of an SMS is divided into two distinct phases: Transmission (handling the provider handoff) and Verification (handling user interaction).

Phase 1: Transmission (Twilio Integration)

When the system initiates an SMS request, we communicate directly with Twilio. The status at this stage reflects whether the message was successfully handed off to the telecommunications network.

• FAILED: This occurs if Twilio rejects the request. Common causes include invalid phone formats, account suspension, or provider-side API errors.

• SENT: This indicates that Twilio has accepted the request and is currently attempting to route the message through local carriers to the recipient's device.

Phase 2: Verification (User Interaction)

Once a message is in the SENT state, the status remains static until the user interacts with the application.

• SUCCESS: The user has entered the correct OTP into the application within the valid timeframe.

• SENT (Persistent): If the user ignores the message, fails to receive it due to carrier issues, or enters an incorrect code, the status does not revert. It remains SENT to reflect that the transmission was attempted, but the handshake was never completed.

The following table serves as a quick reference for support and engineering teams:

Current Status	Event/Trigger	Logic Explanation
FAILED	Twilio API Error	The message never left the platform.
SENT	Request Accepted	The message is "in flight" or sitting on the user's device.
SUCCESS	OTP Validated	The user successfully completed the security loop.
SENT	No Action/Invalid OTP	The loop remains open; no successful verification occurred.