> For the complete documentation index, see [llms.txt](https://codehas.gitbook.io/the-repairbox/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codehas.gitbook.io/the-repairbox/notification-settings.md).

# Notification Settings

This page explains the notification controls that are confirmed in the current RepairBox implementation and how they affect delivery. The important principle is that **channel provider setup, customer channel selection, and notification templates are separate gates**. Enabling one does not automatically enable every customer message.

## What notifications do in RepairBox

The notification pipeline takes an application event (for example, the Repair Created event), finds the relevant active notification template(s), resolves the intended recipient and delivery channel, and attempts delivery. The application records the outcome so staff/developers can distinguish a sent message from a message that was skipped or failed.

A simplified flow is:

```
Repair event occurs
    ↓
Matching notification template(s)
    ↓
Customer notification enabled?
    ↓
Template channel selected in Default Contact Methods?
    ↓
Channel provider/configuration valid?
    ↓
Resolve correct recipient
    ↓
Send or skip/fail and record result
```

A status saved in RepairBox and a notification delivery are different things. A message failure must not be interpreted as a failed repair operation, and a successful provider/API response is not proof the customer read the message.

## Controls confirmed in the current implementation

### Customer Notifications

This control enables/disables the customer notification path. When customer notifications are disabled, do not expect a customer message merely because a template and provider exist.

**Use it to:** temporarily disable customer notification dispatch while validating templates or resolving a delivery issue. Before switching it back on, test the intended event with a controlled customer record.

### Default Contact Methods

The current setting is stored as `default_contact_method` and its observed default value is `['email']`. It acts as a gate for customer notification template channels: if a template's channel is not included in the selected contact methods, the dispatcher skips that delivery and records the skip reason.

The current documented choices in the implementation evidence are:

* **Email**
* **SMS**
* **WhatsApp**

The exact display labels may vary slightly in the settings form, but the stored values are channel identifiers, not provider credentials.

**Important:** selecting a default contact method does not configure the provider. It only determines whether that channel is selected for customer notifications.

### Channel provider settings

SMS and WhatsApp have their own provider configuration/enablement settings. These are separate from Default Contact Methods. A channel needs the relevant selection and valid provider setup before its delivery path can operate.

Email also requires a working outgoing mail configuration. A selected Email contact method alone does not prove that SMTP/API delivery is configured correctly.

### Notification templates

The dispatcher works with templates that have a channel. Templates must be active and match the event being processed. If there is no matching active template for the event/channel, that channel has no message to send.

The current evidence confirms the Repair Created event is used by the repair notification flow. Do not assume every possible status, assignment, approval, invoice, refund or QC event is a template trigger unless that event is present in the installed template list/application code.

## Configure customer notifications in the correct order

1. Open the Notifications settings area in the current RepairBox Admin UI.
2. Confirm whether **Customer Notifications** is enabled.
3. Review **Default Contact Methods**. The observed starting default is Email only.
4. Open the notification template list/editor and verify the intended event has an active template for the desired channel.
5. Configure the underlying outgoing channel separately (mail settings, SMS provider, or WhatsApp provider as applicable).
6. Verify the customer record contains the matching contact type: an email address for Email, or a valid phone number for SMS/WhatsApp.
7. Trigger a controlled test event and inspect the notification result/log. Check the status and recipient—not just whether the settings were saved.
8. Only enable live customer delivery after the test confirms the correct channel and destination.

Do not enable Email, SMS and WhatsApp all at once as a first test. Enable and test one channel at a time so the failure cause is clear.

## How Default Contact Methods and providers differ

| Setting/state                             | What it means                                             | What it does not mean                                                                         |
| ----------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Customer Notifications enabled            | Customer notification dispatch is allowed                 | Does not guarantee a template matches or provider delivery succeeds                           |
| Email selected in Default Contact Methods | Email channel passes the contact-method gate              | Does not configure SMTP or prove inbox delivery                                               |
| SMS selected                              | SMS channel passes the contact-method gate                | Does not create a provider account, validate a sender, or fix a missing/wrong phone recipient |
| WhatsApp selected                         | WhatsApp channel passes the contact-method gate           | Does not complete WhatsApp Business/provider onboarding                                       |
| Provider enabled/configured               | The channel's delivery integration is available to try    | Does not mean every template is enabled or every customer has opted in                        |
| Active event/channel template             | The dispatcher has message content for that event/channel | Does not guarantee recipient correctness or external delivery                                 |

## Current SMS/WhatsApp recipient warning

A current code review note identifies a recipient-resolution defect in the repair notification flow: the repair dispatcher passes the customer's email as a generic `recipient`, and the SMS/WhatsApp branches can prefer that value before `customer_phone`. That can cause an SMS/WhatsApp delivery attempt or log to use an email address instead of the customer's phone number.

**Until that defect is verified as fixed in the deployed build, do not enable live SMS or WhatsApp customer notifications.** This is not a provider credential problem. The code must route:

* Email → customer email address.
* SMS → customer phone number.
* WhatsApp → customer phone number.
* In-app → the appropriate application notification recipient.

After a fix is deployed, run a controlled test and confirm both the actual destination and the delivery log show the phone number for SMS/WhatsApp. A green provider status or saving the settings is not sufficient.

## Notification result/log interpretation

When diagnosing an attempt, distinguish at least these cases:

* **Sent/accepted:** the application or provider accepted the request. This does not necessarily mean the customer received/read it.
* **Skipped:** dispatch logic intentionally did not attempt delivery, such as when the template channel is not among Default Contact Methods.
* **Failed:** a delivery attempt was made but returned or raised an error.
* **No record/no event:** the event may not have fired, no active matching template may exist, or the log path may not cover that action; investigate the trigger path rather than changing provider credentials blindly.

Use the actual status labels stored/displayed by your installed log view. The descriptions above explain their meaning, not a promise that the UI uses those exact English labels in every version.

## Safe troubleshooting sequence

1. Confirm the event actually occurred.
2. Confirm an active matching template exists for that event and channel.
3. Confirm Customer Notifications is enabled.
4. Confirm the template channel is selected in Default Contact Methods.
5. Confirm the channel's provider settings and credentials.
6. Verify the resolved recipient has the right type (email vs phone).
7. Inspect the recorded status/skip reason and provider response where available.
8. Check queue processing only if the installed delivery path dispatches asynchronously.
9. Re-test with a controlled customer, then confirm no duplicate messages were sent.

Do not repeatedly change repair status to force a message. That can alter repair history and create duplicate notifications.

## Recommended release checklist

* [ ] Customer Notifications toggle tested both off and on.
* [ ] Default Contact Methods reviewed; Email-only default understood.
* [ ] Templates checked against events actually emitted by the app.
* [ ] Email tested to the customer's email address.
* [ ] SMS/WhatsApp remain disabled for live use until recipient routing is fixed and verified.
* [ ] Test logs distinguish sent, skipped and failed outcomes.
* [ ] Customer channel preference/consent is respected by the deployed implementation.
* [ ] Multi-item repair messages are checked for order-vs-item accuracy.

## Related documentation

* Email Configuration
* SMS Configuration
* WhatsApp Configuration
* Webhooks and Notifications
* Repair Management Overview
