> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Utilities outage and usage notifications: an end-to-end walkthrough

> Compose a utility customer communications posture end to end in Devotel Orbit: classify outage, billing, usage, and conservation notices into tenant-owned classes, build the push plus voice-to-SMS outage cascade with per-step windows and pricing, run two-way outage reporting and payment assistance on WhatsApp, send RCS bill-preview and usage-summary cards, take meter readings and outage reports by IVR, deliver statements and regulatory notices by email, and read the delivery and cost record after the outage window closes.

# Utilities outage and usage notifications: an end-to-end walkthrough

This walkthrough takes a power, water, or gas utility from the first classification decision to a live, monitored outage and usage setup. It composes pieces that already ship: [voice broadcasts with an SMS fallback waterfall](https://docs.orbit.devotel.io/guides/voice-broadcast-with-sms-fallback.md), [push notifications](https://docs.orbit.devotel.io/guides/push-integration.md), [two-way conversations](https://docs.orbit.devotel.io/guides/sms-two-way-conversation.md), [RCS rich cards](https://docs.orbit.devotel.io/guides/rcs-rich-card-builder.md), [IVR slot-filling](https://docs.orbit.devotel.io/guides/ivr-slot-filling-intake.md), and [email with attachments](https://docs.orbit.devotel.io/guides/email-attachments.md). The examples below use one fictional utility, Cedar Valley Power & Light (CVPL), 214,000 customers across three service territories.

Every control on this page is tenant-owned. Your organization decides which notice classes exist, which channels carry each class, which windows apply, and how hard conservation outreach is capped. Orbit provides the channels and the controls; the posture decisions are yours. If your regulator requires specific notice content or timing, your team maps these controls to it.

## 1. Classify every notice before you send it

Write the classes down first, because the class decides the controls:

1. **Urgent outage and safety.** Outage started, restoration updates, restoration complete, and safety notices such as downed lines or gas leaks. This class is exempt from your quiet hours by your configuration, and it should be the only class that is.
2. **Billing and usage transactional.** Statements, payment confirmations, payment reminders, payment-due alerts, and usage-threshold notices. This class respects quiet hours by your configuration and sits outside marketing frequency caps.
3. **Conservation and program marketing.** Rebate campaigns, program enrollment, and conservation appeals. This class respects quiet hours, [frequency caps](https://docs.orbit.devotel.io/guides/frequency-caps.md), and every promotional gate in [send gates](https://docs.orbit.devotel.io/compliance/send-gates.md).

Declare the classes in [send gates](https://docs.orbit.devotel.io/compliance/send-gates.md), set the per-class windows in [quiet-hours configuration](https://docs.orbit.devotel.io/guides/quiet-hours-configuration.md), and cap the marketing class with [frequency caps](https://docs.orbit.devotel.io/guides/frequency-caps.md). Two decisions deserve explicit sign-off before the first send:

* **What counts as urgent.** An outage is urgent; a planned-maintenance window may or may not be. Write the rule down ("outage started, restoration updates, and safety notices are urgent; planned outage reminders are transactional") so the quiet-hours exemption is never decided at send time.
* **Where time-sensitive conservation lands.** A peak-day alert that protects grid stability is transactional for many utilities; a peak-day enrollment appeal is marketing. Decide once per event type, not per send.

Then build the customer record the classes act on: `phone` in E.164, account number, service address, `preferred_language`, and a channel-preference field when you honor one. Create them as [custom fields](https://docs.orbit.devotel.io/guides/custom-fields.md) if your import does not carry them, and build one segment per territory and feeder so an outage blast addresses the affected area rather than the whole book ([CDP segments](https://docs.orbit.devotel.io/guides/cdp-segments.md) for attribute-driven groups, [static contact lists](https://docs.orbit.devotel.io/guides/contact-lists-static-targeting.md) for rosters you maintain by hand).

## 2. The outage blast: push, voice, and SMS as one cascade

Fire the outage blast as three legs with different semantics, launched together:

1. **Push, immediate at T+0**, to every registered device in the affected segment.
2. **Voice, immediate at T+0 per recipient**, the primary reach for everyone push cannot cover.
3. **SMS, armed as the fallback hop**, firing per recipient only when the voice hop terminally fails inside the fallback window.

Push is not a hop in the voice-to-SMS waterfall, and understanding why keeps the payload honest: the [notify waterfall](https://docs.orbit.devotel.io/guides/voice-broadcast-with-sms-fallback.md) escalates per recipient across E.164 hops on terminal delivery receipts, while push addresses device tokens and has no per-recipient DLR to escalate from. Fire the push fan-out at T+0 with `POST /api/v1/push/send`; it costs no per-segment carrier spend and lands on app devices while the voice calls are still ringing. The waterfall then guarantees the per-recipient escalation on the phone-number side. The per-hop failure semantics and the policy for ordering channels are in [notify cascade failover](https://docs.orbit.devotel.io/guides/notify-cascade-failover.md) and the [cross-channel cascade failover policy](https://docs.orbit.devotel.io/guides/cross-channel-cascade-failover-policy.md).

### Push leg: a curated outage category

Define the category once, with an interactive surface, then reference it on every outage send ([push integration](https://docs.orbit.devotel.io/guides/push-integration.md)):

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/push/categories \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Utility outage alerts",
    "identifier": "UTILITY_OUTAGE",
    "sound": "alert-high.aiff",
    "actions": [
      { "identifier": "VIEW_STATUS", "title": "View outage status", "options": ["background"] },
      { "identifier": "REPORT_ISSUE", "title": "Report an issue", "options": ["foreground"] }
    ]
  }'
```

Every outage push then names `"notification_channel": "UTILITY_OUTAGE"`, and the two actions return through your Inbox the same way the WhatsApp keywords in section 3 do.

### Voice to SMS leg: the waterfall payload

Reuse the two-binding waterfall shape from the [voice broadcast with SMS fallback guide](https://docs.orbit.devotel.io/guides/voice-broadcast-with-sms-fallback.md), with utility copy and an outage-sized window:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/notify" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "waterfall",
    "fallback_window_seconds": 600,
    "from": "+15550123",
    "metadata": { "campaign": "cvpl-outage-millbrook-2026" },
    "bindings": [
      {
        "channel": "voice",
        "address": "+14155552671",
        "body": "Cedar Valley Power and Light: A power outage is affecting the Millbrook area. Crews are on site. We estimate restoration by 6 PM. Updates are posted at the CVPL status page. This is an automated message from Cedar Valley Power and Light.",
        "max_price": 0.25
      },
      {
        "channel": "sms",
        "address": "+14155552671",
        "body": "CVPL: Outage in Millbrook area. Crews on site. Est. restore 6 PM. Updates: cvpl.link/status",
        "max_price": 0.02
      }
    ],
    "max_total_price": 0.27
  }'
```

Per-step window and pricing as your posture dials them:

| Leg | When it fires | Window | Cost control |
| - | - | - | - |
| Push | T+0, fan-out to registered devices | None; immediate | Device-token audience; no per-segment carrier cost |
| Voice (hop 0) | T+0 per recipient | Federal 8 AM to 9 PM recipient-local dialing window, non-relaxable | `max_price` per binding |
| SMS (hop 1) | Only on a terminal voice failure | `fallback_window_seconds` (600 here; a major storm event can run 900) | `max_price` per binding, one SMS segment |
| Envelope | Across both numbered hops | | `max_total_price` per recipient |

### Quiet hours: urgent outages versus everything else

The classes get different quiet-hours postures, and both are your configuration:

* **Urgent outage alerts.** Exempt the urgent class from quiet hours in [quiet-hours configuration](https://docs.orbit.devotel.io/guides/quiet-hours-configuration.md) so a 2 AM restoration update is not held until 8 AM. The voice hop still stays inside the federal 8 AM to 9 PM recipient-local window; no workspace setting relaxes it, for any message class, and an outage does not change that. The SMS and push legs carry the urgent reach outside business hours.
* **Billing, usage, and conservation.** These respect your quiet-hours windows, on purpose. A payment reminder held overnight and delivered at 9 AM is the posture most utilities choose; confirm it with the quiet-hours preview before the first billing cycle runs on the new setup.

Write both decisions into the posture document next to the class definitions from section 1.

## 3. Two-way on WhatsApp: outage reporting and payment assistance

A one-way blast leaves the outage desk counting silence, and a payment-due SMS leaves the customer with no place to ask about assistance. Run both conversations on WhatsApp the same way the [SMS two-way conversation guide](https://docs.orbit.devotel.io/guides/sms-two-way-conversation.md) runs them on SMS, after connecting your number per [WhatsApp getting started](https://docs.orbit.devotel.io/guides/whatsapp/getting-started.md):

* **Outage reporting.** A customer message that names an address or says "outage" opens a thread in your [Inbox](https://docs.orbit.devotel.io/guides/inbox-setup.md), gets an automated acknowledgement with the current estimated restoration time for their service address, and is tagged so the outage desk watches the report count build instead of refreshing a spreadsheet. Wire the acknowledgement with [keyword auto-reply rules](https://docs.orbit.devotel.io/guides/keyword-auto-reply-rules.md); the worked shapes for routing and tagging are in [keyword rules recipes](https://docs.orbit.devotel.io/guides/keyword-rules-recipes.md).
* **Payment assistance.** A "payment" or "help" message gets an automated reply with your payment-options link and your assistance line's hours, then routes to a staffed queue when the customer asks for a person. Keep the assistance thread on the same number as the rest of the customer conversation so the agent answering sees the billing reminders that prompted it.
* **Session shape.** The first message of a customer session goes out on an approved template; once the customer replies, the conversation continues free-form. That is the WhatsApp session model, and it fits utilities well: the outage blast opens on SMS or voice, and the customer who replies on WhatsApp gets the richer conversation from then on.

Read the tally next to the delivery record: replies by keyword and conversation volume per sender tell the outage desk how big the event is before the first crew report lands.

## 4. RCS: bill-preview and usage-summary cards

For customers on RCS-capable devices, replace the one-line "your bill is ready" SMS with a card that carries the bill:

* **Bill-preview card.** Amount due, due date, usage versus the same month last year, and suggested actions: View bill, Payment options, Report an outage. The actions deep-link into your payment portal and status page, so the card is both the notice and the interface.
* **Usage-summary card.** A mid-cycle card with usage to date and the customer's own plan threshold, for the high-bill alert class: a customer who sees the usage climb mid-cycle is not surprised by the statement at the end of it.

Compose both in the [RCS rich card builder](https://docs.orbit.devotel.io/guides/rcs-rich-card-builder.md). Customers whose device or carrier does not support RCS get the SMS statement-ready notice instead; decide that fallback in the [cross-channel cascade failover policy](https://docs.orbit.devotel.io/guides/cross-channel-cascade-failover-policy.md) rather than maintaining a second audience list by hand.

## 5. IVR: meter reading and outage reporting by phone

Not every customer wants an app, and a storm puts your least digital customers on the phone first. Build two lanes with [build an IVR flow](https://docs.orbit.devotel.io/guides/build-ivr-flow.md) and [IVR slot-filling intake](https://docs.orbit.devotel.io/guides/ivr-slot-filling-intake.md):

* **Meter-reading lane.** Collect the account number and the reading with slot filling, play both back for confirmation, and after two failed confirmations offer a callback instead of looping. Route the confirmed reading into your billing system the same way a web form entry arrives.
* **Outage lane.** Match the calling number to a service address, play the current outage status and estimated restoration time for that feeder, and offer one keystroke to report an outage the system has not yet seen. The lane should read from the same outage data your status page shows, so the IVR never tells a caller something the web contradicts.

During a major event, the outage lane is also your overflow valve: update its prompt the moment the estimated restoration time changes, and callers get the answer without waiting for an agent.

## 6. Email: statements and regulatory notices

Email carries the two notice types that need a document, not a message:

* **Statements.** Attach the statement PDF rather than relying on a portal link alone ([email attachments](https://docs.orbit.devotel.io/guides/email-attachments.md)); several utility commissions require the document itself to be delivered. Keep the statement email in the transactional class so a customer's marketing unsubscribe never stops a statement.
* **Regulatory notices.** Rate-change notices, privacy notices, and program terms go out with the same lifecycle controls; the [email lifecycle guide](https://docs.orbit.devotel.io/guides/email-lifecycle-guide.md) walks the class split, the suppression behavior per class, and the delivery record to keep as your evidence of notice.

Conservation program kits and rebate campaigns belong to the marketing class here: unsubscribe applies, quiet hours apply, and frequency caps apply. One suppression list covers the whole book across every channel; a customer who opts out on SMS is not emailed around the decision.

## 7. Monitor the window, control the cost, close the loop

During and after an outage window, run three reads:

* **Delivery log.** Filter the [delivery log](https://docs.orbit.devotel.io/guides/delivery-log.md) by the campaign value you set in `metadata` and by the outage window. Per-hop receipts (`GET /api/v1/notify/:notifyId`) show which leg landed each recipient and at what price; [track a cascade](https://docs.orbit.devotel.io/guides/track-a-cascade.md) reads every column. Export the recipients every hop missed and load them as a `missed-<event>` segment for the next, different leg: a staff phone tree or a door-knock list for the customers who are push-blind and voice-blind both. Never re-run the same cascade at the same audience hoping for a different result.
* **Alerts.** Set the [insights alerts](https://docs.orbit.devotel.io/guides/insights-alerts-console-operator-guide.md) that matter during a window: delivery-failure rate above your baseline, inbound outage-keyword volume as an early size signal, and voice answer rate below the norm for a dial of that size.
* **Cost.** Read spend per class in [cost intelligence](https://docs.orbit.devotel.io/guides/cost-intelligence.md). The urgent class is price-inelastic and should be; the conservation class is where caps, budgets, and per-segment cost checks apply. After each event, deliver the summary (per-channel reached counts against the segment size, hop prices, keyword volume) as a [scheduled report](https://docs.orbit.devotel.io/guides/scheduled-reports.md) so the post-event review exists before anyone asks for it.

### Rollout checklist

1. Classes written down with their quiet-hours and frequency-cap posture, urgent exemption signed off.
2. Territory and feeder segments built; suppressed and opted-out counts known per segment.
3. Push category `UTILITY_OUTAGE` created; device-token coverage counted per segment.
4. Waterfall payload tested against a volunteer list with the production `max_price` values.
5. WhatsApp outage and payment keywords live, acknowledgement copy approved, staffed queues named.
6. RCS bill-preview and usage-summary cards built with the fallback to SMS decided.
7. IVR meter-reading and outage lanes rehearsed, including the two-failed-confirmation path.
8. Statement and regulatory email classes split; attachment delivery verified.
9. Delivery-log filter, insights alerts, and the post-event scheduled report configured.
10. One suppression list confirmed across SMS, voice, WhatsApp, RCS, and email.

### Troubleshooting

* **`TCPA_FEDERAL_DIALING_WINDOW_BLOCKED` on the voice hop.** A schedule fact, not a configuration error: the federal window does not relax for outages. The SMS and push legs carry those recipients; confirm your urgent-class SMS posture is open overnight.
* **Push leg thinner than expected.** Stale device tokens return provider errors such as `BadDeviceToken`; prune them from the delivery-log export and recount coverage per segment.
* **Conservation sends held.** A rebate campaign refused by a frequency cap is the cap working. Check the cap before raising it; the urgent class never goes through these caps in the first place.
* **Opt-out replies after an outage blast.** A STOP reply writes to the suppression list of the account that sent. If drills or conservation traffic share the production account, a customer can opt out of the wrong class; separate accounts or suppression exclusions per class keep the urgent list intact.
* **Customers with no resolvable timezone.** The voice hop refuses them under the federal guard; the SMS hop catches them when your urgent-class SMS posture allows it. The section 2 counts surface how many customers that is before the first event, not during it.

## See also

* [Industries overview: Utilities](https://docs.orbit.devotel.io/guides/industries-overview.md) — the vertical's buyer problem, compliance posture, and channel matrix.
* [Utilities usage-messaging buyer explainer](https://docs.orbit.devotel.io/blog/utilities-usage-messaging-buyer-explainer) — the outage, usage, and billing workflow for the buying decision.
* [Devotel Orbit for utilities](https://orbit.devotel.io/en/utilities) — the product page for this vertical.
* [Voice broadcast with SMS fallback](https://docs.orbit.devotel.io/guides/voice-broadcast-with-sms-fallback.md) — the waterfall payload and receipt semantics this page reuses.
* [Push integration](https://docs.orbit.devotel.io/guides/push-integration.md) — device tokens, categories, and the send endpoint.
* [Quiet-hours configuration](https://docs.orbit.devotel.io/guides/quiet-hours-configuration.md), [frequency caps](https://docs.orbit.devotel.io/guides/frequency-caps.md), and [send gates](https://docs.orbit.devotel.io/compliance/send-gates.md) — the tenant-owned class controls.
* [RCS rich card builder](https://docs.orbit.devotel.io/guides/rcs-rich-card-builder.md) — bill-preview and usage-summary cards.
* [Build an IVR flow](https://docs.orbit.devotel.io/guides/build-ivr-flow.md) and [IVR slot-filling intake](https://docs.orbit.devotel.io/guides/ivr-slot-filling-intake.md) — the meter-reading and outage lanes.
* [Email lifecycle guide](https://docs.orbit.devotel.io/guides/email-lifecycle-guide.md) and [email attachments](https://docs.orbit.devotel.io/guides/email-attachments.md) — statements and regulatory notices.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.