Article summary
Diagnose WA/WS failures across preflight, task execution, Excel reconciliation and queue admission, using explicit error codes to stop bad data from sending.
Diagnose WhatsApp checking errors by stage instead of rerunning whenever the match rate looks low. The same symptom may originate in the source phone, TXT generator, task choice, Excel import or messaging queue. Repetition without a failure_code makes evidence harder to recover.
Stage 1: source phones are already damaged
Scientific notation, altered trailing digits, missing country fields and a dropped plus sign occur before AIPUSH. Preserve phone_raw and inspect the source file type. Digits already changed by a spreadsheet cannot be reconstructed by changing display format.
Stage 2: the wrong country rule was applied
| Failure code | Symptom | Action |
|---|---|---|
| COUNTRY_GUESSED | Code added from language/campaign market | Return to provenance |
| TRUNK_DUPLICATED | Domestic zero retained after country code | Apply the country rule |
| LEGACY_PREFIX | Old dialing marker remains | Use a versioned migration map |
| DIGIT_LOSS | Length plausible but raw value altered | Recover the upstream original |
Stage 3: TXT is not one phone per line
AIPUSH accepts TXT only. A header, name, comma-separated CRM row, whitespace and duplicates can contaminate a batch. Record encoding, total rows, unique rows, blanks, hash and normalization_version after generation.
Stage 4: task and question do not match
| Question | Task | Frequent mistake |
|---|---|---|
| Did this run return registration? | WS Registration | Selecting Full Format for more columns |
| Need an activity observation? | WS Activity | Using registration as activity |
| Need an avatar field? | WS Avatar | Inferring identity from image |
| Need wider fields? | WS Full Format | Collecting without a defined purpose |
Stage 5: the Excel importer flattens states
Not returned, unknown, unavailable, processing error and explicit negative stay separate. An importer that converts blank to false corrupts registration, profile coverage and activity reporting at once.
Stage 6: the wrong reconciliation key is used
A phone is not a permanent master key. Use an internal contact_id crosswalk from phone_normalized to batch_row. A one-to-many or many-to-one mapped phone enters conflict review rather than the newest value overwriting the master.
Stage 7: the observation has no date
Registration, activity, avatar and business-account states can change. Store task_name, batch_id, checked_at and refresh_after for every result. A field without observation time should not drive a decision.
Stage 8: registration is mistaken for permission
Technical state does not show that the person expects a message. Check provenance, channel scope, purpose and opt-out independently. A purchased or scraped list is not admitted to marketing by a high registration rate.
Stage 9: “anti-ban tactics” hide a process defect
Random delays, account rotation, device changes and repeated checks do not repair complaints or violated expectations. Pause the queue, analyze source and copy, and use official support rather than attempting to bypass restrictions.
Install batch-level blocking rules
Stop sending when reconciliation falls below threshold, country guessing exceeds a limit, missing rates change abruptly, mapping collisions rise or suppression data is unavailable. Every failure needs owner, reason and resolution rather than a verbal explanation.
The real acceptance outcome
A qualified batch has reproducible input, the correct task, explainable states, reversible mapping, verified permission and blocked risk exceptions. The earlier an error receives an explicit code, the less downstream rework it creates.
