Bow Chat API·api-guide·Version 1

Delivery states and safe fallback

Use terminal failure, consent, deduplication, and a one-fallback limit to recover delivery without sending duplicate or prohibited messages.

OpenAPI contract

Recommended state machine

queued -> accepted/sent -> delivered -> read
                    \-> failed -> classify -> optional one-time fallback

accepted or sent is not failure. Do not resend merely because delivered has not arrived within a short polling interval. Provider receipts can be delayed.

Classify the terminal failure

Failure class	Fallback?	Action
Temporary transport or disconnected session	Sometimes	Apply a cooling period, then use one approved alternate channel if consent permits
Invalid recipient or address	No	Correct the contact record before another attempt
Opt-out, block, complaint, or consent failure	No	Suppress the recipient across the campaign or purpose
Template, category, quality, account, or policy rejection	No automatic fallback	Fix the policy or account condition; do not route around it
Duplicate or already delivered business event	No	Mark complete and suppress every later attempt

Fallback invariants

One stable business-event ID controls every channel attempt.
One recipient, purpose, message, and doctor or clinic sender stay attached to that event.
Only a terminal failed state can enter fallback evaluation.
Allow at most one fallback attempt unless a human explicitly approves another.
Re-check consent, suppression, and recipient identity immediately before fallback.
Never fall back after an opt-out, block, complaint, or policy/quality failure.
If a late delivered or read event arrives after fallback began, suppress any unsent duplicate and record both states.

A practical hybrid for healthcare notifications

Send approved appointment, recall, or operational templates through the WhatsApp Business Platform as the primary path.
If that specific attempt reaches a recoverable terminal transport failure, offer one consented recovery path: a low-volume message from the same clinic's linked WhatsApp number, an SMS, an email, or a Customer Room notification.
Keep clinical detail out of the fallback message unless the channel, purpose, legal basis, and security controls permit it. A neutral prompt to open the private Customer Room often carries less sensitive content.

Measure the journey

Track acceptance rate, terminal-failure rate, delivered rate, duplicate-prevention count, fallback rate, fallback delivery, opt-outs, complaints, and time to delivery. Separate transport recovery from recipient engagement; a read receipt is not a medical outcome.

For WhatsApp Web constraints, read Safe use of a WhatsApp Web connection.