Dispatcher Guide · v5.3.4

RoadReady Fleet OS - Dispatcher User Guide

The Dispatcher manages routes, Drivers, fleet activity, documents, maintenance and operational reporting. Billing, company branding, invitations and team removal remain Owner-only.

Open RoadReadyFix a problemPDF quick guide

Updated August 22, 2026 · reflects distance-based trip progress, Automatic Load Inbox and provider-first GPS/HOS workflows.

Quick start
  1. Sign in with your Dispatcher account and confirm you are in the correct company.
  2. Check Dashboard/Activity for active routes and exceptions.
  3. Use Smart Load Intake or Load Calculator before assigning a new route.
  4. Confirm Driver, default/assigned truck, pickup/delivery addresses and appointments.
  5. Check Telematics Integration Hub / Fleet Map and live ETA data health before relying on GPS/HOS.
  6. Monitor route statuses, BOL/POD, maintenance and chat.
  7. Create/revoke customer tracking links only with the intended privacy settings.

1. Joining and signing in

  1. Use Join company, register with your own email, confirm the email and enter the Dispatcher invitation code supplied by the Owner.
  2. After sign-in, verify the company name is correct and the sidebar shows Dashboard, Load Calculator, Dispatch, Fleet, Team, Maintenance, Documents, Chat, Reports, How to Use and Settings.
  3. If the code is invalid or expired, request a new code from the Owner. Do not register a second account unless the first account is intentionally abandoned.

2. Start-of-shift workflow

  1. Open Dashboard and review active routes, online Drivers, open maintenance and planned profit.
  2. Open the bell and process unread route, document, maintenance and form activity.
  3. Open Operations chat for company-wide updates, then check private unread Driver conversations.
  4. Review Dispatch for routes that are Unassigned, waiting for location, delayed, at delivery or missing POD.

3. Load Calculator

  1. Enter rate type, rate, loaded miles, deadhead, accessorial revenue, fuel assumptions, tolls, reserve and other costs.
  2. Choose the Driver pay method and enter the correct rate. Compare profit and profit per mile with company policy.
  3. Use calculation in a route so the financial estimate is carried into Dispatch. Drivers never see this financial section.
  4. Treat the calculator as a planning tool; verify final invoices, payroll and actual expenses outside RoadReady.

4. Creating and assigning routes

  1. Enter route/load number, Driver, origin/destination, exact pickup/delivery addresses, appointment times, equipment and instructions.
  2. Select the correct Driver before saving. If the Driver changes, edit the route and confirm the new Driver received the assignment.
  3. Use Assigned for a new route. The progress percentage is distance-based; statuses still need to match the real workflow because they control route state, stop handling and notifications.
  4. Do not place private financial details in Driver instructions or Operations chat.

5. Monitoring route execution

  1. Open a route to see distance-based progress from trip start, POD status, latest location, ETA and Driver activity. Driver and Dispatch should show the same canonical progress for the same trip.
  2. Waiting for location means RoadReady does not currently have a fresh usable trip position. Check the connected telematics mapping first; if no provider GPS is available, ask the Driver to use Share current location as fallback.
  3. Use Add update or route notes for operational events that should remain in the timeline.
  4. Use Open Driver chat for route-specific questions. Use Operations only when the whole company needs the update.
  5. When the Driver marks Delivered, confirm the signed POD is linked before considering the route administratively complete.

6. Fleet and Team

  1. Use Fleet to add or edit trucks and trailers if the Owner permits this operational workflow. Keep unit status accurate before assigning equipment.
  2. Team shows Owner, Dispatchers and Drivers with online presence. Use Message for private chat and Assign route from a Driver card.
  3. Dispatcher accounts cannot invite or remove team members. Send those requests to the Owner.

7. Documents

  1. Use the Driver filter to open a Driver document folder, then filter by BOL, POD or another type.
  2. Document-to-Driver assignment is based primarily on Related route. Correct route selection prevents files from appearing under Unassigned/company files.
  3. Photos selected through Documents become a PDF; a ready PDF remains unchanged. Confirm page order and readability after upload.
  4. Use clear titles such as POD - Load 1048 or BOL - Winnipeg to Chicago. Avoid generic names such as image or document.

8. Maintenance

  1. Review Driver repair requests and attached photos. Confirm vehicle, location, safe-to-drive answer and priority.
  2. Move requests through New, Approved, Scheduled, In Repair, Complete or Cancelled.
  3. Urgent and Out of Service issues require direct communication; changing a status in the app is not a substitute for safety procedures.

9. Driver Forms

  1. Reports contains submitted Accident/Incident, Cargo Damage, Reefer Temperature and Border Checklist forms.
  2. Open supporting files, read all fields and contact the Driver for missing information.
  3. Escalate safety, cargo, insurance, customs or legal issues according to company procedures. RoadReady records the report but does not replace required external reporting.

10. Chat and notifications

  1. Use Operations for shared instructions and private chat for one Driver.
  2. Read receipts show whether a message was opened. Do not send repeated messages solely because a Driver is temporarily offline.
  3. Install RoadReady to the Home Screen and enable push notifications from Settings for new messages and operational updates.
  4. If chat or unread counts look wrong, open How to Use and run the system check before reporting the issue.

11. Reports and end-of-shift handoff

  1. Review route financials, completed routes, missing PODs, open maintenance and Driver Forms.
  2. Post a concise handoff in Operations or private Dispatcher chat: active load, current status, next appointment, issue, required follow-up and document status.
  3. Do not mark a route Delivered simply to clear it from the active list. The status must reflect the actual trip.

12. Dispatcher limitations

  1. You cannot manage Stripe billing, change company branding, create invitation codes or remove users.
  2. You can manage operational routes, financial estimates, fleet, Drivers, maintenance, documents, reports and chat.
  3. Contact the Owner for subscription, access or company identity changes.

13. Live Fleet Map

  1. Use Fleet Map to see the latest Driver-shared position for active routes and identify stale or missing updates.
  2. The map is not continuous GPS and does not calculate actual movement or ETA. Request a new location when operationally necessary.
  3. Open the route or private chat to follow up without broadcasting Driver-specific instructions in Operations.

14. Fuel Log

  1. Record or review fuel purchases with the correct Driver, truck, route, odometer and receipt.
  2. Check for implausible odometer or quantity values before relying on totals.
  3. Gallons and litres remain separate and must be converted outside RoadReady when a combined unit report is required.

15. Service schedules and reminders

  1. Create preventive maintenance schedules with a due date or odometer target.
  2. Mark work completed only after confirming the vehicle service is complete. Repeating schedules advance to the next interval automatically.
  3. Treat overdue items as an operational escalation and coordinate with the Owner and Driver.

16. Scorecards and document controls

  1. Use Driver Scorecards as a workflow consistency tool, not a safety or employment rating.
  2. Use document search and date filters during billing, audit or customer follow-up.
  3. Export a filtered document index when a broker, customer or internal reviewer needs a register of stored files.

17. Accounting and invoice workflow

  1. Open Accounting to enter operating expenses and attach receipts.
  2. Create invoices only after confirming the route is delivered and the customer, charges and due date are correct.
  3. Dispatchers can sync expenses and invoices using the Owner's saved mappings but cannot disconnect QuickBooks or change company mappings.
  4. Export driver pay CSV for payroll review; verify all figures before payment.

18. Smart Load Intake and Document AI

  1. Use Intelligence → Smart Load Intake to read Rate Confirmations, BOLs and PODs from PDFs, scans or photos.
  2. Review the detected document type, confidence and every imported route field before saving.
  3. Correct pickup/delivery/reference data manually when needed. AI is an extraction assistant, not an automatic dispatch authority.
  4. If AI is unavailable, RoadReady can fall back to local PDF/OCR parsing.

19. Driver default truck

  1. In Team, confirm each Driver's Default truck when your role has access to manage it.
  2. Selecting a Driver in Dispatch auto-fills the default truck; override it when a different unit is used for that load.

20. Live ETA + HOS

  1. Use Intelligence → Refresh live ETA to recalculate remaining road distance and ETA from the freshest location/HOS data.
  2. Review On time / At Risk / Late plus Why this ETA before communicating an ETA to the customer.
  3. If data is stale, verify provider mapping/last sync or ask the Driver to share a current location as fallback.

21. Telematics providers

  1. Fleet → Telematics Integration Hub shows provider connection and data health separately.
  2. After Motive/Samsara/Geotab is connected, use Review mapping to match RoadReady trucks/Drivers to provider records.
  3. Connected + mapped can still show Waiting for device or Waiting for ELD data when the fleet has no active hardware/HOS source.
  4. Use Sync now after mapping changes. Simulator remains available for training/testing.

22. Customer tracking links

  1. Open a route → Customer link to create an expiring broker/customer tracking URL.
  2. Keep exact GPS and Driver name hidden unless the carrier wants those fields shared.
  3. If the customer only needs progress, ETA and remaining miles, leave exact GPS off.
  4. Revoke the link after the load/customer access is no longer required.

System-wide rules

23. Connected is not the same as live data

Provider authorization, truck mapping, Driver mapping, Live GPS and Live HOS are separate states. A provider can be Connected while GPS waits for a physical device or HOS waits for ELD data.

24. RoadReady is not an ELD

Provider HOS remains the authoritative compliance source. RoadReady normalizes data for dispatch visibility and ETA planning; Simulator/manual HOS are test/planning inputs.

25. Smart Intake requires review

AI/OCR never replaces Owner/Dispatcher review. Verify document type, shipment reference, pickup, delivery, dates, rate/miles and confidence before saving a route.

26. Customer tracking is privacy-controlled

Customer links can expire or be revoked. Exact GPS and Driver name are off unless the carrier explicitly enables them.

27. Route-document linking matters

BOL/POD should be linked to the exact Related route so Driver folders, POD status, invoices and delivery-to-cash automation work correctly.

28. Default Driver truck is a convenience, not a lock

Team can store a default truck for each Driver. Selecting the Driver auto-fills that truck, but Dispatch can override it for a specific route.

29. Realtime problems should be isolated

Run System check and inspect the specific Edge Function log for the failing feature. Avoid reinstalling unrelated functions when only one workflow fails.

30. Secrets stay server-side

OAuth client secrets, provider tokens, OpenAI keys and QuickBooks secrets belong in Supabase/secure server-side storage, never in public frontend files or browser storage.

Fix a problem

Provider says Connected, but there is no live GPS
  1. Connected only confirms provider authorization. Open Fleet → Telematics Integration Hub and check Truck mapping, Last sync and Live GPS separately.
  2. Confirm the RoadReady truck is mapped to the correct provider vehicle.
  3. Tap Sync now and wait for a fresh provider timestamp.
  4. If Live GPS still says Waiting for device, the mapped vehicle is not currently sending telematics. Motive normally needs an installed/assigned Vehicle Gateway; Samsara/Geotab likewise need an active device/source.
  5. Use RoadReady Simulator or Driver → Share current location as a fallback while testing. Do not treat OAuth Connected as proof that hardware data exists.
Provider says Connected, but there is no HOS
  1. Open Review mapping and confirm the RoadReady Driver is mapped to the correct provider Driver.
  2. Tap Sync now and check Live HOS separately from account connection.
  3. The provider must actually have ELD/HOS data for that Driver. A developer account or vehicle record alone may not produce HOS clocks.
  4. If HOS says Waiting for ELD data, RoadReady will keep the provider connected but will not invent compliance clocks.
  5. For ETA testing, use the RoadReady Simulator HOS clocks until real ELD data is available.
Motive Connect / OAuth does not complete
  1. In Motive Developer Portal, confirm Success Redirect URI is exactly https://roadreadyfleetos.com/app/?oauth_provider=motive
  2. Confirm Motive permissions include Company Details, Drivers and Fleet Managers, Vehicles, Vehicles with Current Location and Current Driver, Drivers with Available Time, and Drivers with Hours of Service.
  3. In Supabase Edge Function Secrets, confirm MOTIVE_OAUTH_CLIENT_ID and MOTIVE_OAUTH_CLIENT_SECRET exist. Never put the secret in app.js or Netlify.
  4. In RoadReady, use Reconnect after changing Motive app settings. If the authorization session expired, tap Connect again instead of reusing the old browser page.
  5. If the account connects but shows zero provider vehicles, verify the authorized Motive fleet actually contains vehicles and that the app has access to them.
Samsara Connect is unavailable or fails
  1. RoadReady needs provider-issued Samsara OAuth credentials before one-click Connect can work.
  2. Confirm SAMSARA_OAUTH_CLIENT_ID and SAMSARA_OAUTH_CLIENT_SECRET are saved only in Supabase Edge Function Secrets.
  3. The Samsara app must request read access needed for vehicles/telematics, Drivers and HOS.
  4. If the fleet is hosted in a different Samsara region/cloud than the app credentials, the provider setup must match that region.
  5. If RoadReady is still waiting for Samsara partner/developer approval, continue testing through Simulator or another connected provider.
Geotab will not connect
  1. Use a dedicated MyGeotab service/integration account rather than a personal admin login when possible.
  2. Enter the correct MyGeotab database, username/email and password.
  3. The account needs read access to vehicles/device status/location, Drivers and HOS data used by RoadReady.
  4. After Connect, use Review mapping, then Sync now.
  5. If authentication works but data is missing, verify the service account can see the same vehicles and Drivers in MyGeotab.
Customer tracking link will not create
  1. Confirm the route exists and you are signed in as Owner or Dispatcher.
  2. Confirm the Supabase Edge Function roadready-public-track is deployed with Verify JWT OFF.
  3. If an old link was revoked or expired, create a new link rather than trying to restore the old token.
  4. The full token URL is shown only when the link is created; RoadReady stores only a SHA-256 hash. If the URL is lost, create another link.
  5. Keep Share exact live truck location OFF unless the carrier intentionally wants the customer to see precise coordinates.
Customer link opens but exact truck location is missing
  1. Edit/create the customer link and enable Share exact live truck location only if appropriate.
  2. RoadReady still needs a fresh vehicle location from Motive/Samsara/Geotab, Simulator or Driver-shared location.
  3. If the provider card says Waiting for device, the customer link can still show route status, ETA and remaining miles but not a real live truck point.
  4. Driver name is a separate privacy option and stays hidden unless explicitly enabled.
Smart Load Intake extracted the wrong pickup, delivery or load number
  1. Do not save immediately. Smart Intake is a review workflow, not an automatic final dispatch decision.
  2. Check the detected document type, field confidence and every route field before Save & assign route.
  3. For scans/photos, use a clear, straight image with the full page visible. For multi-page documents, include the pages that contain shipper/consignee and reference information.
  4. Correct any field manually. Layout-aware AI is designed to handle different formats but it must not guess missing data.
  5. If AI is unavailable, RoadReady falls back to local PDF/OCR parsing; lower-quality OCR may require more manual review.
Document AI does not run
  1. Confirm roadready-document-ai is deployed in Supabase and the OPENAI_API_KEY Edge Function Secret exists.
  2. Check that the file type/size is supported and that the signed-in role is allowed to use Smart Intake.
  3. Retry once with a clearer PDF/photo. If AI remains unavailable, RoadReady should fall back to the local parser instead of blocking the workflow.
  4. Never place the OpenAI API key in Netlify, app.js, config.js or browser storage.
ETA looks wrong or stale
  1. Verify the route has a usable delivery address and the correct truck/Driver assignment.
  2. Check the latest location source: provider GPS, Simulator or Driver-shared location. Stale location produces stale ETA.
  3. Check HOS freshness. RoadReady uses live provider HOS first, then available planning/fallback data.
  4. Tap Intelligence → Refresh live ETA after correcting mapping, address or location.
  5. Review Why this ETA for road distance, HOS limits and risk reasons. ETA is a planning estimate, not an ELD compliance decision.
Simulator will not start or route cannot be geocoded
  1. The route needs Pickup address, Delivery address, Driver and Truck.
  2. Use real street/city/province/state addresses. Remove PO Box-only text or unrelated shipping instructions when the location cannot be resolved.
  3. For rural facilities, include the nearest city/municipality and province/state; RoadReady tries simplified address fallbacks.
  4. If the route starts successfully, wait for the simulator heartbeat, then use Fleet Map or Refresh live ETA.
  5. Simulator is a test source only and is not a certified ELD or real GPS device.
Default truck does not auto-fill for a Driver
  1. Open Team → Driver → Set/Change default truck and choose an active RoadReady truck.
  2. Create or edit a route and select that Driver after the default truck is saved.
  3. RoadReady should auto-select the Driver's default truck; Dispatch can still override it for a specific route.
  4. If the truck was deleted/inactivated, assign a new default truck.
POD still says pending after delivery
  1. Upload the document as type POD, not Other/BOL.
  2. Select the exact Related route for that delivery.
  3. Confirm the upload completed and the document appears in the correct Driver/route folder.
  4. If the wrong route was linked, upload/link the correct POD before relying on the delivery-to-cash workflow.
QuickBooks sync fails or an invoice/receipt is missing
  1. Confirm QuickBooks is still connected in Settings.
  2. Use Refresh QuickBooks lists after changing accounts, items, customers or vendors in QuickBooks.
  3. Verify required expense mappings, payment account and invoice service item are selected.
  4. Use Retry QB receipt / Retry POD for attachment-only failures and review the Intuit TID/sync history for provider errors.
  5. Deleting a RoadReady record does not delete the corresponding QuickBooks transaction.
Invite says invalid, expired or account already belongs to a company
  1. If the account already belongs to the intended company, sign out and sign back in instead of entering another invite.
  2. Create a new invite if the old code expired or reached its maximum uses.
  3. Use one-person invite codes where possible.
  4. If the wrong company membership exists, the Owner should resolve the membership before issuing another code.
RoadReady is not updating in real time
  1. Check the sidebar/realtime indicator and internet connection.
  2. Open How to Use and run System check.
  3. Fully close the iPhone Home Screen app/Safari and reopen after a new Netlify deploy so the service worker can update.
  4. If only one feature is failing, check the related Supabase Edge Function logs rather than reinstalling everything.
Push notifications do not appear on iPhone
  1. Open RoadReady in Safari and use Add to Home Screen.
  2. Launch RoadReady from the installed Home Screen icon, then enable notifications from Settings/Profile.
  3. Confirm notifications are allowed for RoadReady in iPhone Settings.
  4. Keep each user on an individual account so notification routing matches the correct role.

FAQ

Why does Motive show Connected but Live GPS says Waiting for device?

OAuth authorization worked, but the mapped Motive vehicle is not sending a live location. A vehicle record alone is not telematics; the fleet needs an active device/source. RoadReady keeps the connection and shows the data state separately.

Why does Live HOS say Waiting for ELD data?

The provider account may be connected and the Driver mapped, but the provider has not returned current HOS/available-time data for that Driver. RoadReady does not invent legal HOS clocks.

Can I test GPS/HOS without Samsara, Motive or Geotab hardware?

Yes. Use the RoadReady Simulator. It writes normalized GPS, speed and HOS into the same RoadReady live-data layer used by provider adapters, but it is test data and not an ELD.

What should I do if Smart Load Intake reads a document incorrectly?

Review every field, correct the wrong values and save only after verification. Upload a clearer scan/photo if needed. Layout-aware AI has confidence scores and falls back to local PDF/OCR parsing when AI is unavailable.

Why is a customer tracking link not showing exact truck location?

Exact GPS is privacy opt-in. Enable it for that link and make sure RoadReady has a fresh provider/Simulator/Driver location. The link can still show route status, ETA and remaining miles without exact coordinates.

Why does POD pending remain on a delivered route?

A document of type POD must be uploaded and linked to that exact route.

Why did the default truck not load when I selected a Driver?

Open Team and save a Default truck on that Driver. The truck must still exist/active. Dispatch can always override the default for a specific route.

What does RoadReady sync with QuickBooks?

RoadReady can sync trucking expenses and receipts, create customer invoices from delivered routes, attach the latest linked POD, match/create vendors and customers, and refresh invoice balances. Payroll remains an export/review workflow.

Who can create or revoke customer tracking links?

Owner/Dispatcher roles can create expiring links, control exact GPS and Driver-name visibility, and revoke links.

Does RoadReady continuously track the Driver phone?

No. Provider telematics can supply vehicle location. Without provider telematics, the Driver can intentionally share a current position as fallback.

Do I need to press Refresh now for Motive, Samsara or Geotab?

No. RoadReady automatically syncs connected telematics providers about once per minute while the manager app is open and visible, then refreshes Account, mappings, Live GPS, Live HOS and Last sync. Refresh now remains a manual fallback. When the app is reopened, RoadReady also checks for fresh provider data.