Skip to content
The InfiQ GlossaryFeature

Webhooks & events

Template Quality Webhook

The message_template_quality_update webhook reports when a template's quality score moves between GREEN, YELLOW and RED — the early warning before a pause.

Also called: message_template_quality_update · Template quality update · Template quality score webhook

InfiQ Glossaryreviewed Practitioner

What is the template quality webhook?

The template quality webhook is the message_template_quality_update field. Meta sends it whenever the quality score of one of your approved message templates changes — each message template in each language is scored on its own. Each notification names the template (message_template_id, message_template_name, message_template_language) and gives previous_quality_score and new_quality_score, each one of GREEN (high), YELLOW (medium), RED (low) or UNKNOWN (not yet rated, where every new template starts).

The score — Meta's template quality rating — reflects how recipients react to the template: negative feedback such as blocks and reports (the block rate), low read rates, and overall engagement. GREEN, YELLOW and UNKNOWN templates can be sent normally. A template that drops to RED is paused automatically under Meta's template pausing rules — for 3 hours the first time, 6 hours the second — and disabled the third time. So a move to YELLOW is the moment to act, while a move to RED usually means a pause is about to follow.

This webhook reports scores, not states. The pause itself, the disable and the return to active arrive in the template status webhook as message_template_status_update events, with other_info.title values such as FIRST_PAUSE. A move between marketing and utility arrives in the template category update webhook. And a template's score is not the phone number's quality rating, which is read from the number's quality_rating field. Template quality is per template and per language, and like other template webhooks it always goes to the app's default callback URL.

Key takeaways

  • The template quality webhook (message_template_quality_update) reports when a template's score moves between GREEN, YELLOW, RED and UNKNOWN.
  • A drop to YELLOW is the moment to throttle and fix the copy, while the template can still send.
  • A template at low quality is paused for 3 hours the first time, 6 hours the second, and disabled the third time.
  • The pause itself arrives in the template status webhook: this webhook reports scores, not states.
  • Template quality is tracked per template and language, separately from the phone number's quality rating.

Figure 1

Watch a template's score slide, and recover

5 / 5
025507510079
  • RED · low0–33
  • YELLOW · medium33–66
  • GREEN · high66–100
Reading 5 of 5GREEN · high

YELLOW → GREEN

79

Recovered. Ramp volume back up gradually, sending only to engaged, opted-in users.

Each reading is one message_template_quality_update. The dial position is illustrative — Meta reports only the colour — but the zones and what each move triggers are real.

YELLOW → GREEN: 79 — GREEN · high zone. Recovered. Ramp volume back up gradually, sending only to engaged, opted-in users.

Why it matters

Why does the template quality webhook matter?

A falling score is the cheapest problem to fix and the most expensive to miss. Caught at YELLOW, a marketer can cut frequency, tighten the audience or rewrite the copy while the template still sends. Missed, the template pauses in the middle of a campaign, sends fail until the pause ends, and repeated low quality can eventually affect the phone number itself. A webhook turns quality from a monthly dashboard glance into an alert that arrives while there is still time.

Example: A reminder that wore out its welcome, Kochi

A Kochi insurance broker sends a renewal_offer template three times in a week to everyone whose motor policy expires within 60 days. On the fourth day a message_template_quality_update arrives: previous_quality_score: GREEN, new_quality_score: YELLOW. The handler pauses the remaining reminder waves and alerts the marketing lead. She cuts the sequence to one message, sends it only to customers who opened an earlier one, and adds a "Stop reminders" quick reply. Two weeks later another webhook reports YELLOW → GREEN, and the template never paused.

— A reminder that wore out its welcome, Kochi

How does the template quality webhook work?

  1. Subscribe and keep a score history

    Tick message_template_quality_update in the app's webhook fields. Store each change with its time against the template ID and language, so you can see which campaign preceded a drop.

  2. Alert on any downward move

    Treat GREEN → YELLOW as a warning and anything → RED as urgent. Send both to the template's owner with the campaigns that used it in the last few days.

  3. Throttle before Meta pauses

    On YELLOW, slow or stop the campaigns sending that template, narrow the audience to engaged, recently opted-in users, and review frequency across all your templates.

  4. Pair it with the status webhook

    A RED score is usually followed by a PAUSED status event. Your scheduler should stop on the pause and resume only after the status returns to active, not on a timer.

  5. Fix the cause, then watch recovery

    Rewrite copy that reads as spam, add a clear opt-out button and stop sending to people who never read. Expect a later webhook moving the score back up as feedback improves.

Common mistakes with the template quality webhook

  • Waiting for RED

    By the time a template is RED, a pause is usually on its way. Alert and throttle on the first drop to YELLOW, when the template can still send.

  • Confusing template and number quality

    This webhook is about one template in one language. The phone number's quality_rating is a separate signal; a GREEN number can have a RED template and vice versa.

  • Resuming on a timer after a pause

    Pauses end automatically, but resume campaigns when the status webhook says the template is active again, and only after fixing the cause — the third low-quality strike disables it.

  • Ignoring UNKNOWN

    A new template sent at full volume to a cold list before it has a score is how many drops start. Ramp new templates up gradually and watch the first score that arrives.

The template quality webhook in code

const RANK = { RED: 0, YELLOW: 1, UNKNOWN: 2, GREEN: 3 };
 
export async function onTemplateQuality(entry, change) {
  const v = change.value;
  const key = v.message_template_id + ":" + v.message_template_language;
  await qualityHistory.add(key, v.previous_quality_score, v.new_quality_score, entry.time);
 
  const down = RANK[v.new_quality_score] < RANK[v.previous_quality_score];
  if (!down) return;                                  // recovery: log it, no action
 
  if (v.new_quality_score === "RED") {
    await campaigns.stopUsing(v.message_template_id); // a pause usually follows
    await alerts.urgent(v.message_template_name + " is RED: expect a pause");
  } else {
    await campaigns.throttle(v.message_template_id, { factor: 0.25 });
    await alerts.warn(v.message_template_name + " fell to " + v.new_quality_score);
  }
}

Record every move, act only on drops, and stop sending at RED instead of waiting for the pause.

Best practices for the template quality webhook

  • Plot quality changes on the same chart as campaign sends; the cause is usually obvious.
  • Give marketing templates a visible opt-out quick reply — an easy stop beats a block.
  • Retire templates that stay YELLOW after a rewrite instead of nursing them along.
  • Spread frequent messages across several templates only if each is genuinely useful; rotation does not hide fatigue.

Template Quality Webhook FAQs

Does a RED template stop sending immediately?
A template that reaches the lowest rating is paused automatically: 3 hours the first time, 6 hours the second, and disabled the third. Attempts to send a paused template are rejected and not charged.
Is there a numeric quality score?
No. The webhook and the template's quality_score field report only GREEN, YELLOW, RED or UNKNOWN, along with when the score was set.
Can I edit a template whose quality dropped?
Yes, even while paused. Editing sends it back to review, and it cannot be sent again until it is approved and active.
Does a low-quality template affect my phone number?
Not at first, but it can over time. A paused template leaves the number initially unaffected; sustained low quality, though, blocks messaging-limit upgrades and can lead to restrictions, so fix falling templates early.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms