DEV Community

Ujjwal Dubey
Ujjwal Dubey

Posted on

Failed WhatsApp Template Sends Should Become CRM Tasks: Logging Error Codes With a Human Next Step (Python)

When a WhatsApp template message fails, most setups log it and move on. The customer never gets their reminder, and nobody on the team knows.

A better pattern for WhatsApp CRM automation that does not fail silently: every failed send becomes a CRM task with an owner and a suggested next step.

The flow

  1. Your provider sends a status webhook for each outgoing message.
  2. On a failed status, look up the contact and the deal in the CRM.
  3. Map the error to a plain-language reason and a next step.
  4. Create a task for the contact owner.
REASONS = {
    "not_on_whatsapp": ("Number is not on WhatsApp", "Call or email instead"),
    "template_rejected": ("Template not approved", "Ask the admin to review the template"),
    "rate_limited": ("Sending limit reached", "Retry automatically later"),
    "outside_window": ("Free-form message outside the service window", "Use an approved template"),
}

def classify(error_code):
    # map your provider's codes to the keys above; keep the table in config
    return REASONS.get(error_code, ("Unknown failure", "Check the message log"))

def on_status(event, crm):
    if event["status"] != "failed":
        return
    contact = crm.find_contact(phone=event["recipient"])
    reason, step = classify(event.get("error_key"))
    if step.startswith("Retry"):
        return crm.schedule_retry(event["message_id"])
    crm.create_task(
        contact_id=contact["id"] if contact else None,
        owner=contact.get("owner") if contact else "inbox-lead",
        title=f"WhatsApp send failed: {reason}",
        body=f"Message {event['message_id']}. Suggested next step: {step}.",
    )
Enter fullscreen mode Exit fullscreen mode

Notes

  • Keep the error map in config, not code, so a non-developer can update wording.
  • Unmatched contacts go to a named inbox lead, never to nobody.
  • Review the task list weekly to spot template or data problems.

More on scoping this kind of work: our five-step audit guide.

Top comments (0)