Sign in Talk to us Free trial
Free trial

Design and software studio
Colour

A tow call from first ring to completed

Take a call, assign it, follow it through each status and cancel or reopen it, with the rules that guide each move.

For
DispatcherService advisorAdministrator
Hosting
Any hosting
Devices
All devices
Business
Towing

Checked against Pop Street Dispatch 0.1.0

A tow call moves through nine statuses. You will be able to take a call, move it along, cancel it with a reason and reopen it.

Before you start #

You need the dispatcher, advisor, manager or owner role.

Take a call #

  1. Open Tow calls and choose to take a call.
  2. Enter the pickup address. It is required, up to 250 characters.
  3. Add what you know: drop-off address, caller name and phone, vehicle, drive type (FWD, RWD, AWD, 4WD or EV), reason, priority, account, purchase order number, notes and condition notes.
  4. Choose the reason: breakdown, accident, lockout, jump start, flat tire, winch out, fuel, private property, impound or transport. The default is breakdown.
  5. Choose the priority: normal, high or urgent. The default is normal.
  6. Choose how the call is paid: collect, or account.
  7. Save. The call gets the next number (T-3001, T-3002 and so on), a tracking link and an entry in the timeline. A call with a scheduled time starts as Scheduled, and any other call starts as New.

The statuses and moves #

FromMoves to
NewDispatched, Scheduled, Cancelled
ScheduledDispatched, New, Cancelled
DispatchedEn route, New, Cancelled
En routeOn scene, Dispatched, Cancelled
On sceneLoaded, En route, Cancelled
LoadedDelivered, On scene, Cancelled
DeliveredCompleted, Loaded
Completednone
CancelledNew
  • Dispatching needs a driver. Assigning a driver to a New or Scheduled call dispatches it in the same step.
  • Moving a call back to New clears the driver, the truck and the ETA.
  • Moving back a step clears the later time stamps, so the timeline stays true.
  • Only the driver steps (en route, on scene, loaded, delivered) belong to the driver app. Completing is the dispatcher's step.

Cancel a call #

  1. Choose Cancel. A call can be cancelled from New through Loaded.
  2. Type the reason. It is required, up to 200 characters.
  3. A cancelled call can be reopened as New.

Same request twice #

Send an Idempotency-Key header when taking a call. A repeat with the same key returns the first call and creates nothing new. See "Safe retries (idempotency)".

Technical details
  • Every status change writes a timeline event and an audit entry in the same transaction, and queues a tow.status webhook event. Taking a call queues tow.created.
  • GET /tow/options lists the allowed values and the allowed next statuses for each status.
  • GET /tow/calls filters by status (also active for dispatched through loaded, and open), driver_id, q and updated_since, and pages with cursor and limit.
  • Position pings from drivers write the driver record only and no audit entry, because a ping every 20 seconds would bury the audit log.
  • AWD, 4WD and EV drives, and a flatbed need, mark the call as flatbed only.

If something goes wrong #

  • A message that names two statuses (for example new and loaded): the move sits outside the table. Follow the steps in order.
  • "Choose a driver first.": assign a driver before dispatching.
  • "Say why the call is cancelled.": add a reason.
  • validation_failed (422) naming reason, priority, drive_type or payment_mode: use one of the listed values.
  • invalid_date (422): scheduled_at needs an ISO 8601 date and time.