> 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/embedded-repair-booking-widget.md).

# Embedded Repair Booking Widget

The Embedded Repair Booking Widget is the public intake path for a repair business's own website. Its job is to collect a structured repair request and hand the information to RepairBox so staff can continue the intake/workshop workflow without retyping the entire request.

The widget is not a separate repair-management system. RepairBox remains the source of truth for customer association, Repair Orders, Repair Items, statuses, estimate/approval state, billing and repair history.

## The customer booking journey

A typical booking journey is:

1. Customer opens the business's “Book a Repair” page.
2. Customer enters the contact details required by the configured form.
3. Customer describes one or more devices.
4. For each device, the form uses the standard catalog path where a suitable catalog record exists, or a custom-detail path where supported and necessary.
5. Customer reports the problem and requested service, and provides any supported condition/accessory details, notes or photos.
6. Customer submits the request.
7. RepairBox validates the input and associates it with the intended intake flow/outlet according to the installed widget behavior.
8. Staff reviews the submitted request, verifies the customer/device details, and continues diagnosis, estimate/approval and repair processing.

**Submission is not automatically a confirmed diagnosis, an approved estimate, or a promise of a repair time.** The confirmation wording must match what the installed workflow actually creates—request awaiting staff review versus an order confirmed directly.

## What the widget captures

The following are part of the RepairBox intake model. The widget should present only the fields and selectors actually enabled by its deployed form.

| Input area                            | Purpose                                                                                  | How staff use it after submission                                                                  |
| ------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Customer identity and contact details | Identify and contact the requester                                                       | Match an existing customer where appropriate or create/review a customer record                    |
| Device Type                           | Broad equipment category                                                                 | Helps determine what device catalog/model choices are relevant                                     |
| Brand                                 | Manufacturer/brand                                                                       | Narrows catalog choices and improves consistency                                                   |
| Device / Model                        | Standard device entry where available                                                    | Links the repair item to structured catalog information                                            |
| Custom device fields                  | Manually identify equipment missing from catalog                                         | Preserves the submitted details on the repair item; must not auto-create global catalog records    |
| Reported problem                      | Records what the customer says is wrong                                                  | Guides technician diagnosis; it is not yet a confirmed finding                                     |
| Requested service                     | Records the repair work the customer is asking about                                     | Staff reviews applicability and creates an estimate when required                                  |
| Defects                               | Captures a reported problem using catalog labels when offered                            | Helps structured intake but must not be treated as proof of technical diagnosis                    |
| Condition / existing damage           | Captures visible condition before the repair                                             | Protects customer and workshop by recording pre-existing damage                                    |
| Accessories received                  | Identifies charger, cable, SIM/SIM tray, bag, stylus or other items actually handed over | Staff verifies the physical handover; never assume an accessory was received because it was listed |
| Notes and photos                      | Adds relevant explanation and visual evidence where supported                            | Helps intake, diagnosis and disputes, subject to access control                                    |
| Outlet or appointment                 | Routes the request where supported by the installed flow                                 | Staff verifies the saved outlet/appointment rather than trusting the browser display alone         |

The exact widget configuration controls, required/optional switches, styling values and embed method must be read from the widget settings/components in the deployed RepairBox version. Do not document a separate toggle just because it would be useful; first confirm it exists in the app.

## Configure the intake choices

### 1. Prepare the catalog first

Before exposing catalog choices publicly, review the configured Device Types, Brands, Devices/Models, Services and Defects. Use consistent names and remove inactive or irrelevant choices from the customer-facing list using the supported catalog controls.

The standard path is:

**Device Type → Brand → Device / Model → relevant Services and Defects**

A service/defect association is important: customers should not be offered choices that are not relevant to the selected device. If the exact model is missing, use the custom route if it is exposed by the widget; otherwise provide a staff review path instead of encouraging a wrong selection.

### 2. Decide how custom details are handled

RepairBox supports standard and custom repair descriptions in its repair-intake model. A custom entry may capture Device Type, Brand, Model, Problem, Service and Notes. Keep these values as submitted repair details. A public submission must not silently create permanent shared catalog entities, because untrusted visitors could create duplicates or malicious names.

### 3. Keep contact inputs accurate

Only require contact inputs that the business's intake and follow-up workflow actually uses. Ensure fields map to the correct customer attributes. Email must remain an email address; phone fields must remain phone numbers. Do not allow a public visitor to choose another customer, outlet, repair status, permission or pricing value by supplying a raw database identifier.

RepairBox's notification workflow also checks notification settings and contact methods. A submitted email/phone value alone does not guarantee confirmation delivery. See [Notification Settings](https://codehas.gitbook.io/the-repairbox/notification-settings.md).

### 4. Capture condition and accessories per device

When a customer has multiple devices, condition, reported defect, accessories, photos and notes should attach to the appropriate Repair Item—not to a generic shared description that loses which facts belong to which device.

Example: the phone has a cracked screen and includes a SIM tray; the laptop has battery issues and includes a charger. The two sets of information must remain separate.

### 5. Decide the outlet/intake route

If the widget supports outlet selection, use the business's actual outlets and verify that a public request can only choose an active, valid destination. If selection is not available, the request should follow the configured/default routing path. Confirm the saved order/item belongs to the intended outlet after a test submission.

Do not claim that appointment booking, pickup/delivery scheduling or automatic outlet selection exists unless it is present in the deployed widget and its saved-record workflow.

## Embed the widget on the business website

1. Open the widget/integration configuration provided by the deployed RepairBox version.
2. Copy the embed snippet or use the documented embed method generated for that installation.
3. Place it on the intended “Book a Repair” page using the site's supported HTML/embed block.
4. Test it on desktop and mobile, with the host site's real content-security policy and browser settings.
5. Submit a controlled test booking.
6. Confirm the resulting RepairBox record, customer, outlet, Repair Items, catalog/custom details and notification outcome.
7. Publish the live page only after the test has passed.

The current source available for this documentation does not verify whether the deployed embed is an iframe, script bundle or another mechanism. Therefore this guide deliberately does not invent a script URL, HTML attribute, widget-specific setting name or code sample. Use the integration method actually shown by the app.

## Booking confirmation versus repair acceptance

Make the customer-facing result clear:

* If the widget creates a request for staff review, say that the request was received and the business will follow up.
* If the widget creates a Repair Order immediately, show the customer-safe repair reference and accurate next step.
* If payment is part of the actual installed booking flow, document the provider and state transitions used by that build; do not infer it from the existence of Stripe elsewhere in RepairBox.
* Do not describe a requested service as a final quote until the applicable estimate and approval process has occurred.

## Validation and security

* Use HTTPS and validate all submitted data on the server.
* Validate catalog IDs against active records and supported relationships.
* Apply supported rate limiting/abuse controls to public submission.
* Restrict uploaded file types, sizes and read access where attachments are supported.
* Do not expose staff API tokens, credentials, private customer data, internal notes or administrative resources.
* Do not trust browser-provided price, status, priority, outlet ID, customer ID or permission claims.
* Escape customer-entered text when displaying it in staff/customer pages.
* Explain the business privacy notice and collect only necessary data.
* Ensure notification retries do not repeatedly create customer messages or repair orders.

## Verify the saved RepairBox record

After test submission, inspect the actual record—not only the form's success state.

* [ ] Request/order was created in the expected workflow.
* [ ] Customer matched or was created correctly.
* [ ] Human-readable repair number is available where expected.
* [ ] One Repair Item exists for each submitted device.
* [ ] Standard catalog relationships or custom fields were preserved.
* [ ] Problem is clearly recorded as customer-reported.
* [ ] Condition, accessories, notes and photo attachments belong to the correct item.
* [ ] Status, priority and outlet match the configured intake behavior.
* [ ] Confirmation/notification logs show the expected channel and recipient.
* [ ] A public visitor cannot read or modify another customer's record.

## Troubleshooting

**Catalog choices are missing:** verify active Device Types/Brands/Devices and the device-to-service/defect relationships. Do not patch the public form with an arbitrary catalog ID.

**Custom fields disappear:** check the server-side intake request mapping and ensure custom values are stored on the submitted repair item rather than treated as catalog write requests.

**Multiple devices become one item:** inspect how the widget maps each device entry into Repair Items and test with two distinctly different devices.

**The success message appears but no repair exists:** check server validation, the submission response, processing/queue logs where used, and the configured create-request/create-order flow.

**Wrong outlet/status is saved:** verify actual stored values and the default/routing rules; do not rely on a browser-only selection.

**Confirmation fails:** inspect the actual notification event and log. Customer Notification enablement, Default Contact Methods, active templates and provider configuration are separate checks.

**The embed does not load:** confirm the actual snippet, HTTPS, host policy and supported embed mechanism. Do not guess a script URL or remove browser security controls.

## Actual booking flow documented in RepairBox

The product guide describes a public booking sequence with these customer steps:

1. **Choose the brand.** The available device list is filtered to the selected brand.
2. **Choose a device/model.** The form then shows the services/defects associated with that device.
3. **Choose one or more services/defects.** The selection describes the requested repair.
4. **Choose a repair priority.** In the documented booking flow, Low priority is the default and carries zero extra charge. Other configured priorities may have a preset extra charge. The actual names and amounts are whatever the Admin priority configuration contains.
5. **Complete required customer information.** The form validates required fields before submission.
6. **Enter payment information** when the deployed booking flow requires online payment.
7. **Submit the request.** The documented flow confirms the Repair Order by email after successful payment and provides a printable result.

Confirm these steps against the currently deployed widget before going live; if the new build uses a revised booking flow, update the steps to match it. Do not describe an unpaid submission as paid/confirmed when the app has not recorded payment success.

## Configure the actual embed snippet

The product guide documents an **Embedding Code** area in App Settings that generates snippets for Repair Booking Forms, Track Repair and Support Form widgets. Use the current app's generated snippet rather than writing an undocumented script URL from memory.

1. Open the installed App Settings and find the Embedding Code group if it is present.
2. Select the intended widget type (booking, tracking or support form) from the options actually shown.
3. Copy the generated code.
4. Place it in the relevant page of the business website using the site's supported HTML/embed capability.
5. Open the public page in a clean browser session and complete a controlled test.
6. Inspect the saved RepairBox record and relevant notification/payment state.
7. Publish the website page only after the test has passed.

The product guide documents the widget types; available visual options, sizing controls, language selector, custom CSS, origin restrictions and other settings should only be listed if they appear in the current embed UI.

## Priority and payment behavior during booking

Priority is a customer-facing choice in the documented booking flow. The extra charge is configured on the priority record, displayed during booking, and included according to the booking/payment calculation. Examples such as Standard $0, Express $15 or Urgent $30 are illustrative only—not universal defaults. Always use the configured amount displayed by the current application.

If payment is part of the deployed flow:

* Verify that the displayed total includes the intended service prices, priority fee and configured tax/discount treatment.
* Use the configured payment gateway and test-mode credentials for development.
* After submission, verify a successful payment is recorded and tied to the correct order.
* Confirm the email notification and printable order/confirmation show the same reference and correct total.
* Never treat browser redirection alone as authoritative proof of payment.

## Terms and anti-spam controls

The product guide includes a Terms & Conditions configuration and CAPTCHA configuration among App Settings. Verify whether the current booking form displays the terms and whether the installed CAPTCHA mechanism is enabled. Test both normal submissions and repeated/automated requests.

## Known validation points

* [ ] Brand filters the correct devices/models.
* [ ] Device selection shows only relevant services/defects.
* [ ] Multiple service/defect selections behave as intended.
* [ ] Priority and extra charge match the configured record.
* [ ] Required customer information is validated.
* [ ] Payment step appears only according to the deployed flow.
* [ ] Successful payment creates/updates the expected RepairBox records.
* [ ] Email confirmation references the correct order after successful payment.
* [ ] Print/confirmation behavior works as documented in the current build.
* [ ] Public submission cannot set privileged fields or view another customer's repair.

{% hint style="success" icon="tag" %}
**Get RepairBox at a 10% discounted price**

Purchase RepairBox through the [official Gumroad listing](https://codehas.gumroad.com/l/repairbox) to get the product at a **10% discounted price**.
{% endhint %}

{% hint style="info" icon="envelope" %}
**Need a customized version?**

We also offer customized versions for business-specific requirements. Email <info.codehas@gmail.com> with your needs so we can discuss the right approach.
{% endhint %}

## Related pages

* [General Application Settings](https://codehas.gitbook.io/the-repairbox/general-application-settings.md)
* [Repair Statuses & Priorities](https://codehas.gitbook.io/the-repairbox/repair-statuses-and-priorities.md)
* [Device Catalog](https://codehas.gitbook.io/the-repairbox/device-catalog.md)
* [Services & Defects](https://codehas.gitbook.io/the-repairbox/services-and-defects.md)
* [Stripe Integration](https://codehas.gitbook.io/the-repairbox/stripe-integration.md)

## Related pages

* [Public Repair Tracking Widget](https://codehas.gitbook.io/the-repairbox/public-repair-tracking-widget.md)
* [Creating a Repair Order](https://codehas.gitbook.io/the-repairbox/creating-a-repair-order.md)
* [Adding Multiple Devices](https://codehas.gitbook.io/the-repairbox/adding-multiple-devices.md)
* [Standard vs. Custom Repairs](https://codehas.gitbook.io/the-repairbox/standard-vs.-custom-repairs.md)
* [Device Catalog](https://codehas.gitbook.io/the-repairbox/device-catalog.md)
* [Services & Defects](https://codehas.gitbook.io/the-repairbox/services-and-defects.md)
* [Notification Settings](https://codehas.gitbook.io/the-repairbox/notification-settings.md)
