The runbook goal
A failed account alert should not send support hunting across logs, dashboards, and provider consoles. The runbook should turn delivery evidence into a calm answer: what happened, what the user can try, whether retry is safe, and what engineering needs if escalation is required.
The runbook should cover more than final failure. Account alerts often involve risk, billing, security, or access events, so the wrong support answer can create confusion or account-safety problems. Support needs a script for accepted, delayed, delivered, failed, blocked, expired, and unknown states. They also need guidance on when to avoid resending, when to move the user to a fallback path, and when to ask engineering for message evidence.
Support does not need every telecom detail. Support needs trustworthy states, safe copy, and the evidence to escalate.
Failed alert support table
| State | Support response | Escalation evidence |
|---|---|---|
| accepted or queued | Tell the user the message was submitted and may still be processing. | Request time, queue age, message ID, destination country. |
| sent | Avoid saying the user received it. Ask them to wait briefly or check the number. | Sent timestamp, route, sender identity, provider message ID. |
| delivered | Say the provider reported delivery, but offer account-safe next steps. | Delivery timestamp, receipt source, recipient, template version. |
| failed or undelivered | Offer retry, fallback, or account recovery based on the alert type. | Error code, error category, raw callback, country, sender identity. |
| fraud or policy block | Use safe copy and escalate only when the account action is legitimate. | Rule category, attempt history, country, user account risk context. |
Keep the support response neutral and evidence-based. Do not say an SMS was received just because the API call succeeded, and do not call a message lost while it is still queued or waiting for a final receipt. The runbook should give agents clear language such as submitted, still processing, reported delivered, failed before delivery, expired, or blocked by a safety rule. That wording is easier to trust and easier to correct when more evidence arrives.
Who owns each next action
- Support confirms user-facing details and gathers safe recovery context.
- Engineering reviews webhook history, idempotency keys, retries, and state ordering.
- Operations checks country, sender identity, route, approval state, and provider incidents.
- Product adjusts resend timing, fallback paths, and user copy when the pattern repeats.
Ownership matters during incidents because failed alerts can touch several systems at once. Support owns the customer conversation, but should not invent delivery explanations. Engineering owns event ordering, retries, idempotency, and message history. Operations owns sender setup, route health, country configuration, and provider escalation. Product owns whether the user can complete the account action through another path when SMS is delayed or unavailable.
Review the runbook after any repeated pattern. If support keeps asking engineering for the same field, add it to the timeline. If users keep trying expired codes, change the copy or resend behavior. If failures cluster around one country, add a country-specific note and escalation checklist. A runbook should improve as the team learns from real failed alerts.
Give support the delivery evidence
Use Notilify to keep account alerts, delivery states, and support timelines in one place.
Start sending