a rejected WhatsApp content template blocks every send

"""Report WhatsApp content templates that cannot currently be sent.

Read only. GET requests and nothing else: give this an API Key with read access
rather than the account auth token. The resubmission is printed, never
performed, because this script holds a credential to an account that can send
messages and spend money.
"""
import argparse
import datetime as dt
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("twilio_whatsapp_template_audit")

CONTENT = "https://content.twilio.com/v1"
MONITOR = "https://monitor.twilio.com/v1"

WA_CODES = {
    63016: "freeform message sent outside the 24 hour customer service window",
    63040: "template rejected",
    63041: "template paused",
    63042: "template disabled",
}
BLOCKING = (63040, 63041, 63042)


def code_of(alert):
    """error_code arrives as a string on some alerts and an int on others."""
    try:
        return int(alert.get("error_code"))
    except (TypeError, ValueError):
        return None


def whatsapp_status(approval):
    """Pull status and rejection_reason out of an approval request. Pure.

    An absent approval is not an error: it means nobody ever submitted this
    template, which is a different finding from one that was refused.
    """
    wa = ((approval or {}).get("whatsapp") or {})
    status = str(wa.get("status") or "unsubmitted").strip().lower()
    return status, str(wa.get("rejection_reason") or "").strip()


def explain_code(code):
    """What one of the four WhatsApp codes actually means. Pure."""
    return WA_CODES.get(code, "unrecognised WhatsApp error code")


def verdict(content, approval, code_hits=None):
    """Classify one Content template. Pure, so every status can be tested
    without a network.

    `code_hits` maps WhatsApp error codes to counts seen in the alert window.
    Alerts do not carry a ContentSid, so those counts are account-level context
    and the classifier says so rather than pretending to attribute them.
    Returns (state, detail).
    """
    hits = code_hits or {}
    status, reason = whatsapp_status(approval)

    blocked = sum(hits.get(c, 0) for c in BLOCKING)
    context = ""
    if blocked:
        context = (" Alerts logged %d blocked-template error(s) on this account "
                   "in the window; they carry no ContentSid, so treat that as "
                   "context rather than attribution." % blocked)

    if status == "rejected":
        return ("rejected",
                "whatsapp.status is rejected: %s. Every send using this template "
                "returns 63040 until it is rewritten, resubmitted and approved.%s"
                % (reason or "no rejection_reason given", context))

    if status == "paused":
        return ("paused",
                "whatsapp.status is paused, so sends return 63041. Meta pauses a "
                "template on negative feedback; it lifts on its own if the "
                "feedback stops, and does not if it does not.%s" % context)

    if status == "disabled":
        return ("disabled",
                "whatsapp.status is disabled, so sends return 63042. This is "
                "terminal for this template: build a new one rather than waiting."
                "%s" % context)

    if status == "pending":
        return ("pending",
                "submitted and not yet reviewed. It is not usable outside the 24 "
                "hour window yet, and sending against it now just adds failures.")

    if status == "unsubmitted":
        return ("unsubmitted",
                "no WhatsApp approval request exists for this template, so it "
                "has never been sendable outside the 24 hour window. Anything "
                "falling back to freeform text there returns 63016.")

    if status == "approved":
        freeform = hits.get(63016, 0)
        if freeform:
            return ("approved-but-freeform",
                    "approved, but the account logged %d 63016 in the window: "
                    "something is sending plain text outside the 24 hour window "
                    "instead of this template. That is a code fix, not a "
                    "resubmission." % freeform)
        return ("approved", "approved and sendable.")

    return ("unknown-status",
            "whatsapp.status is %s, which this script does not recognise: read "
            "the approval request before acting." % (status or "empty"))


def get(session, url, **params):
    r = session.get(url, params=params, timeout=30)
    if r.status_code in (401, 403):
        raise SystemExit("%d from Twilio: check TWILIO_ACCOUNT_SID and that the "
                         "API key belongs to that account with read access"
                         % r.status_code)
    r.raise_for_status()
    return r.json()


def list_v1(session, url, key, limit=1000, **params):
    """Page a v1 list. meta.next_page_url is absolute."""
    out = []
    params.setdefault("PageSize", 100)
    while url and len(out) < limit:
        page = get(session, url, **params)
        out.extend(page.get(key, []))
        url, params = (page.get("meta") or {}).get("next_page_url"), {}
    return out[:limit]


def approval_for(session, content_sid):
    """A template with no approval request answers 404, and that is a finding
    rather than an error."""
    r = session.get("%s/Content/%s/ApprovalRequests" % (CONTENT, content_sid),
                    timeout=30)
    if r.status_code == 404:
        return None
    if r.status_code in (401, 403):
        raise SystemExit("%d from Twilio: the API key needs read access to Content"
                         % r.status_code)
    r.raise_for_status()
    return r.json()


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=7, help="alert window, max 30")
    ap.add_argument("--max-templates", type=int, default=500)
    args = ap.parse_args()

    account = os.environ.get("TWILIO_ACCOUNT_SID")
    key = os.environ.get("TWILIO_API_KEY")
    secret = os.environ.get("TWILIO_API_SECRET")
    if not (account and key and secret):
        log.error("set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET "
                  "(an API Key with read access, not the auth token)")
        return 2

    session = requests.Session()
    session.auth = (key, secret)

    contents = list_v1(session, CONTENT + "/Content", "contents", args.max_templates)
    if not contents:
        log.info("no Content templates on this account")
        return 0

    since = (dt.datetime.now(dt.timezone.utc)
             - dt.timedelta(days=min(args.days, 30))).strftime("%Y-%m-%dT%H:%M:%SZ")
    hits = {}
    for a in list_v1(session, MONITOR + "/Alerts", "alerts", 10000,
                     LogLevel="error", StartDate=since):
        c = code_of(a)
        if c in WA_CODES:
            hits[c] = hits.get(c, 0) + 1
    for c, n in sorted(hits.items()):
        log.info("%d alert(s) of %d: %s", n, c, explain_code(c))

    bad = 0
    for content in contents:
        state, detail = verdict(content, approval_for(session, content.get("sid")), hits)
        line = "%-21s %s  %s" % (state, content.get("friendly_name",
                                                    content.get("sid")), detail)
        if state == "approved":
            log.info(line)
            continue
        bad += 1
        log.warning(line)
        if state in ("rejected", "disabled", "unsubmitted"):
            log.warning("  repair: fix the body, then POST %s/Content/%s/"
                        "ApprovalRequests/whatsapp with Name and Category, and "
                        "wait for approved before sending", CONTENT,
                        content.get("sid"))

    log.info("%d template(s), %d not usable", len(contents), bad)
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report WhatsApp content templates that cannot currently be sent.
 *
 * Read only. GET requests and nothing else: give this an API Key with read
 * access rather than the account auth token. The resubmission is printed, never
 * performed.
 */
const CONTENT = 'https://content.twilio.com/v1';
const MONITOR = 'https://monitor.twilio.com/v1';

const WA_CODES = new Map([
  [63016, 'freeform message sent outside the 24 hour customer service window'],
  [63040, 'template rejected'],
  [63041, 'template paused'],
  [63042, 'template disabled'],
]);
const BLOCKING = [63040, 63041, 63042];

/** error_code arrives as a string on some alerts and a number on others. */
export function codeOf(alert) {
  const n = Number(alert?.error_code);
  return Number.isFinite(n) ? n : null;
}

/**
 * Pull status and rejection_reason out of an approval request. Pure. An absent
 * approval is not an error: it means nobody ever submitted this template.
 */
export function whatsappStatus(approval) {
  const wa = approval?.whatsapp ?? {};
  const status = String(wa.status ?? 'unsubmitted').trim().toLowerCase();
  return [status, String(wa.rejection_reason ?? '').trim()];
}

/** What one of the four WhatsApp codes actually means. Pure. */
export function explainCode(code) {
  return WA_CODES.get(code) ?? 'unrecognised WhatsApp error code';
}

/**
 * Classify one Content template. Pure, so every status can be tested without a
 * network. `codeHits` maps WhatsApp error codes to counts seen in the alert
 * window; alerts carry no ContentSid, so the classifier reports those as
 * context rather than attribution. Returns [state, detail].
 */
export function verdict(content, approval, codeHits = null) {
  const hits = codeHits ?? {};
  const [status, reason] = whatsappStatus(approval);

  const blocked = BLOCKING.reduce((n, c) => n + (hits[c] ?? 0), 0);
  const context = blocked
    ? ` Alerts logged ${blocked} blocked-template error(s) on this account in ` +
      'the window; they carry no ContentSid, so treat that as context rather ' +
      'than attribution.'
    : '';

  if (status === 'rejected') {
    return ['rejected',
      `whatsapp.status is rejected: ${reason || 'no rejection_reason given'}. ` +
      'Every send using this template returns 63040 until it is rewritten, ' +
      `resubmitted and approved.${context}`];
  }

  if (status === 'paused') {
    return ['paused',
      'whatsapp.status is paused, so sends return 63041. Meta pauses a template ' +
      'on negative feedback; it lifts on its own if the feedback stops, and ' +
      `does not if it does not.${context}`];
  }

  if (status === 'disabled') {
    return ['disabled',
      'whatsapp.status is disabled, so sends return 63042. This is terminal for ' +
      `this template: build a new one rather than waiting.${context}`];
  }

  if (status === 'pending') {
    return ['pending',
      'submitted and not yet reviewed. It is not usable outside the 24 hour ' +
      'window yet, and sending against it now just adds failures.'];
  }

  if (status === 'unsubmitted') {
    return ['unsubmitted',
      'no WhatsApp approval request exists for this template, so it has never ' +
      'been sendable outside the 24 hour window. Anything falling back to ' +
      'freeform text there returns 63016.'];
  }

  if (status === 'approved') {
    const freeform = hits[63016] ?? 0;
    if (freeform) {
      return ['approved-but-freeform',
        `approved, but the account logged ${freeform} 63016 in the window: ` +
        'something is sending plain text outside the 24 hour window instead of ' +
        'this template. That is a code fix, not a resubmission.'];
    }
    return ['approved', 'approved and sendable.'];
  }

  return ['unknown-status',
    `whatsapp.status is ${status || 'empty'}, which this script does not ` +
    'recognise: read the approval request before acting.'];
}

function authHeader(key, secret) {
  return `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`;
}

async function get(auth, url, params = {}) {
  const u = new URL(url);
  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
  const res = await fetch(u, { headers: { Authorization: auth } });
  if (res.status === 401 || res.status === 403) {
    throw new Error(`${res.status} from Twilio: check TWILIO_ACCOUNT_SID and ` +
                    'that the API key belongs to that account with read access');
  }
  if (!res.ok) throw new Error(`${res.status} from ${u.pathname}`);
  return res.json();
}

export async function listV1(auth, url, key, limit = 1000, params = {}) {
  const out = [];
  let next = url;
  let query = { PageSize: 100, ...params };
  while (next && out.length < limit) {
    const page = await get(auth, next, query);
    out.push(...(page[key] ?? []));
    next = page.meta?.next_page_url ?? null;
    query = {};
  }
  return out.slice(0, limit);
}

export async function approvalFor(auth, contentSid) {
  const res = await fetch(`${CONTENT}/Content/${contentSid}/ApprovalRequests`,
                          { headers: { Authorization: auth } });
  if (res.status === 404) return null;
  if (res.status === 401 || res.status === 403) {
    throw new Error(`${res.status} from Twilio: the API key needs read access to Content`);
  }
  if (!res.ok) throw new Error(`${res.status} reading approvals for ${contentSid}`);
  return res.json();
}

async function main() {
  const account = process.env.TWILIO_ACCOUNT_SID;
  const key = process.env.TWILIO_API_KEY;
  const secret = process.env.TWILIO_API_SECRET;
  if (!account || !key || !secret) {
    console.error('set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET ' +
                  '(an API Key with read access, not the auth token)');
    process.exitCode = 2;
    return;
  }
  const auth = authHeader(key, secret);
  const days = Math.min(Number(process.env.DAYS ?? 7), 30);

  const contents = await listV1(auth, `${CONTENT}/Content`, 'contents', 500);
  if (contents.length === 0) {
    console.log('no Content templates on this account');
    return;
  }

  const since = new Date(Date.now() - days * 86400000).toISOString().slice(0, 19) + 'Z';
  const hits = {};
  for (const a of await listV1(auth, `${MONITOR}/Alerts`, 'alerts', 10000,
                               { LogLevel: 'error', StartDate: since })) {
    const c = codeOf(a);
    if (WA_CODES.has(c)) hits[c] = (hits[c] ?? 0) + 1;
  }
  for (const [c, n] of Object.entries(hits).sort()) {
    console.log(`${n} alert(s) of ${c}: ${explainCode(Number(c))}`);
  }

  let bad = 0;
  for (const content of contents) {
    const [state, detail] = verdict(content, await approvalFor(auth, content.sid), hits);
    const line = `${state.padEnd(21)} ${content.friendly_name ?? content.sid}  ${detail}`;
    if (state === 'approved') { console.log(line); continue; }
    bad += 1;
    console.warn(line);
    if (state === 'rejected' || state === 'disabled' || state === 'unsubmitted') {
      console.warn(`  repair: fix the body, then POST ${CONTENT}/Content/${content.sid}` +
                   '/ApprovalRequests/whatsapp with Name and Category, and wait ' +
                   'for approved before sending');
    }
  }

  console.log(`${contents.length} template(s), ${bad} not usable`);
  process.exitCode = bad ? 1 : 0;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing credentials and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from twilio_whatsapp_template_audit import explain_code, verdict, whatsapp_status

TPL = {"sid": "HX0123456789", "friendly_name": "order_shipped_en"}


def approval(status, reason=""):
    return {"whatsapp": {"type": "whatsapp", "status": status,
                         "rejection_reason": reason}}


def test_rejected_carries_the_reason_meta_gave():
    state, detail = verdict(TPL, approval("rejected", "variable at start of body"))
    assert state == "rejected"
    assert "variable at start of body" in detail
    assert "63040" in detail


def test_paused_and_disabled_are_different_repairs():
    paused, pdetail = verdict(TPL, approval("paused"))
    disabled, ddetail = verdict(TPL, approval("disabled"))
    assert (paused, disabled) == ("paused", "disabled")
    assert "lifts on its own" in pdetail
    assert "terminal" in ddetail


def test_no_approval_request_is_unsubmitted_not_rejected():
    # 404 from ApprovalRequests: nobody ever submitted it.
    state, detail = verdict(TPL, None)
    assert state == "unsubmitted"
    assert "63016" in detail


def test_an_approved_template_on_an_account_logging_63016_is_a_code_bug():
    state, detail = verdict(TPL, approval("approved"), {63016: 84})
    assert state == "approved-but-freeform"
    assert "code fix, not a resubmission" in detail


def test_a_clean_approved_template_is_the_only_healthy_state():
    assert verdict(TPL, approval("approved"))[0] == "approved"
    assert verdict(TPL, approval("APPROVED"))[0] == "approved"


def test_blocking_counts_are_labelled_as_context_not_attribution():
    state, detail = verdict(TPL, approval("rejected"), {63040: 3, 63041: 2})
    assert state == "rejected"
    assert "5 blocked-template error(s)" in detail
    assert "context rather than attribution" in detail


def test_status_and_codes_are_read_defensively():
    assert whatsapp_status({}) == ("unsubmitted", "")
    assert whatsapp_status({"whatsapp": {"status": "Pending"}})[0] == "pending"
    assert verdict(TPL, {"whatsapp": {"status": "in_appeal"}})[0] == "unknown-status"
    assert explain_code(63042) == "template disabled"
    assert "unrecognised" in explain_code(12345)

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { explainCode, verdict, whatsappStatus } from './twilio-whatsapp-template-audit.mjs';

const TPL = { sid: 'HX0123456789', friendly_name: 'order_shipped_en' };
const approval = (status, reason = '') =>
  ({ whatsapp: { type: 'whatsapp', status, rejection_reason: reason } });

test('rejected carries the reason Meta gave', () => {
  const [state, detail] = verdict(TPL, approval('rejected', 'variable at start of body'));
  assert.equal(state, 'rejected');
  assert.match(detail, /variable at start of body/);
  assert.match(detail, /63040/);
});

test('paused and disabled are different repairs', () => {
  const [paused, pdetail] = verdict(TPL, approval('paused'));
  const [disabled, ddetail] = verdict(TPL, approval('disabled'));
  assert.deepEqual([paused, disabled], ['paused', 'disabled']);
  assert.match(pdetail, /lifts on its own/);
  assert.match(ddetail, /terminal/);
});

test('no approval request is unsubmitted, not rejected', () => {
  const [state, detail] = verdict(TPL, null);
  assert.equal(state, 'unsubmitted');
  assert.match(detail, /63016/);
});

test('an approved template on an account logging 63016 is a code bug', () => {
  const [state, detail] = verdict(TPL, approval('approved'), { 63016: 84 });
  assert.equal(state, 'approved-but-freeform');
  assert.match(detail, /code fix, not a resubmission/);
});

test('a clean approved template is the only healthy state', () => {
  assert.equal(verdict(TPL, approval('approved'))[0], 'approved');
  assert.equal(verdict(TPL, approval('APPROVED'))[0], 'approved');
});

test('blocking counts are labelled as context, not attribution', () => {
  const [state, detail] = verdict(TPL, approval('rejected'), { 63040: 3, 63041: 2 });
  assert.equal(state, 'rejected');
  assert.match(detail, /5 blocked-template error\(s\)/);
  assert.match(detail, /context rather than attribution/);
});

test('status and codes are read defensively', () => {
  assert.deepEqual(whatsappStatus({}), ['unsubmitted', '']);
  assert.equal(whatsappStatus({ whatsapp: { status: 'Pending' } })[0], 'pending');
  assert.equal(verdict(TPL, { whatsapp: { status: 'in_appeal' } })[0], 'unknown-status');
  assert.equal(explainCode(63042), 'template disabled');
  assert.match(explainCode(12345), /unrecognised/);
});