Handbook

Appearance

WhatsApp as a Channel ​

What this chapter covers ​

WhatsApp is a channel that reaches people where they already are. This chapter describes the three ways Korido uses it: delivering vehicle alerts to owners through approved French templates, answering owners' questions through a conversational bot, and prompting drivers. It covers the delivery windows and retry behavior that make alerts trustworthy, and the per-tenant and platform switches that decide whether anything is sent at all.

Who it is for ​

WhatsApp serves the people who do not sit in front of the fleet app all day. An owner receives corridor alerts and can ask the bot a quick question from the same thread that carries their sign-in codes. A driver receives directed prompts, such as a request to confirm a pause. Customers meet WhatsApp only as the carrier of a tracking link; proactive milestone messages to customers are a future direction.

The channel is French-first throughout — templates, bot replies, and prompts all speak the corridor's operating language.

Alert delivery ​

When the engine raises a vehicle event worth telling an owner about, the delivery decision is made once, at the moment the event is recorded, and then carried out by scheduled senders. Two things happen up front: the event waits out a short anti-flap delay of 5 minutes so a condition that instantly clears never becomes a message, and its delivery mode — immediate or digest — is resolved from the tenant's configuration and frozen onto the event.

Two delivery windows carry the traffic:

  • Immediate alerts are drained every 2 minutes. Each due event renders its own French copy and sends the vehicle-alert template to every verified owner of that tenant. Every send is recorded.
  • Digest alerts are gathered hourly and grouped into a single capped summary per tenant, sent through the digest template — so lower-urgency events arrive as one readable roundup.

A separate path prompts a mission's owner and driver to confirm a pause through its own French template, sent directly by the engine when a mission looks paused.

Retry behavior keeps delivery honest without spamming. A send that fails transiently is retried; after the third failed attempt the event is marked failed rather than retried forever. Status transitions only ever move forward, so an event cannot be delivered twice by a re-run. What actually went out is observable, down to the latency from the truck's timestamp to the send.

The bot ​

The same WhatsApp thread that delivers alerts also answers questions. An owner sends a short command and the bot replies from live fleet state. The current vocabulary is small and purposeful:

  • localiser — where is a vehicle now.
  • statut — a vehicle's current status.
  • mission — the active mission for a vehicle.
  • aide — help.
  • menu — the list of what the bot understands.

Every inbound message is handled defensively. WhatsApp delivers webhooks at least once and re-delivers on any hiccup, so Korido dedupes each message on its unique Meta message id before acting — a redelivered message never runs twice or replies twice. Inbound numbers are rate-limited, and the "you are rate limited" notice itself is sent at most once per window so it cannot become the very flood it announces. A command is parsed into an intent, answered within the sender's own tenant scope, and the reply is recorded.

Windows and switches ​

Whether anything is sent at all is governed by two independent gates.

  • Per-tenant enablement. A tenant can switch its WhatsApp channel off. Both delivery paths honor that toggle on the same layer: an event whose type has WhatsApp disabled for its tenant is suppressed as channel-disabled — whether it would have gone out immediately or rolled into the hourly digest — while everything else for that tenant stays intact.
  • The platform kill-switch. Outbound WhatsApp is gated globally and is fail-safe off — during the pilot it defaults to off. While paused, due alerts stay pending rather than being attempted and burned to failed, so nothing is lost; they simply wait. Sign-in codes and bot replies are unaffected by the proactive-alert pause. The gate distinguishes a deliberate pause from a misconfiguration, and a paused deploy can never quietly send a broken message.

Turning proactive delivery on is a deliberate operation, not a flag flip: the French templates must be approved on the WhatsApp side, the accumulated backlog of waiting alerts must be reconciled so the first live tick does not flood owners with stale news, and only then is the switch enabled. As a matter of channel hygiene, templates are French-first with explicit opt-in, and outbound volume is warmed up gradually — narrow high-value alerts before broad digests.

The boundaries of this surface ​

  • A messaging channel. WhatsApp carries alerts, replies, and prompts. Alert triage and mission management happen in the fleet app.
  • Owner and driver, today. Alerts go to verified owners and directed prompts to drivers. Proactive customer milestone messages are future work.
  • Alerts are auto-generated. Outbound alerts are approved templates rendered from engine events, each one tied to the event that triggered it.
  • Fail-safe by default. When in doubt, the channel sends nothing and holds the work rather than risking a wrong or stale message.

How it connects ​