SMS Webhooks

Delivery Status Callbacks

CloudVNO sends status update webhooks for every outbound message as it moves through the delivery pipeline.

Configure Status Callback

Set status_callback when sending:

message = client.messages.send(
    from_="+14155551234",
    to="+12125559876",
    body="Your code is 123456",
    status_callback="https://yourapp.com/sms-status"
)

Status Webhook Payload

{
  "MessageSid": "SM1a2b3c4d5e6f7890abcdef",
  "MessageStatus": "delivered",
  "From": "+14155551234",
  "To": "+12125559876",
  "ErrorCode": null,
  "ErrorMessage": null,
  "Timestamp": "2026-03-06T10:00:05Z"
}

Status Values

Status	Meaning
queued	Accepted by CloudVNO, waiting to send
sending	Being transmitted to the carrier
sent	Accepted by the carrier
delivered	Confirmed delivery to handset
undelivered	Carrier could not deliver
failed	Could not be sent (invalid number, etc.)

Handle Delivery Failures

@app.route("/sms-status", methods=["POST"])
def sms_status():
    status = request.form["MessageStatus"]
    sid = request.form["MessageSid"]

    if status == "failed":
        error_code = request.form.get("ErrorCode")
        print(f"Message {sid} failed: {error_code}")
        # Retry logic or alert
    elif status == "delivered":
        print(f"Message {sid} delivered successfully")

    return Response("", status=204)