Messaging Performance Analyzer

<!--

• "MDR" is the human term for the Sent activities surface: GET /v3/messages/{id}/activities. There is no separate MDR endpoint.
• Lifecycle: QUEUED -> ROUTED -> SENT -> DELIVERED -> READ (WhatsApp/RCS only), with FAILED at any stage and RECEIVED for inbound.
• Sent exposes its own normalized error codes (AUTH_, VALIDATION_, RESOURCE_, BUSINESS_, CONFLICT_001, SERVICE_001, INTERNAL_*) on the HTTP envelope, plus send-time per-message codes (ERR_CONSENT_BLOCKED, ERR_ROUTE_DENIED, ERR_TEMPLATE_PARAMS_INVALID) on the message description field. See references/mdr-status-codes.md.

-->

Messaging performance analyzer

Overview

Use this skill to turn raw Sent message evidence into a concise diagnosis of what changed, where the funnel leaks, and what to fix first. Anchor every analysis to Sent message IDs, message status, message activities, and webhook events before interpreting carrier, WhatsApp, or RCS provider codes.

Sent’s v3 send endpoint accepts a template-based request and returns per-recipient message_id values for asynchronous tracking. Status is retrieved with GET /v3/messages/{id}, and detailed lifecycle evidence is retrieved with GET /v3/messages/{id}/activities. Webhook endpoints support event ingestion, event-type discovery, event history, test delivery, and secret rotation.

When to use

Use this skill when the user asks why messages failed, why delivery or read rate dropped, whether fallback is working, whether a provider is filtering traffic, or how a campaign performed. Trigger on words such as “MDR,” “delivery report,” “webhook event,” “activities,” “status,” “failed,” “undelivered,” “read rate,” “fallback,” “filtering,” “throttling,” or “carrier reject.”

Do not use this skill to register 10DLC, design a Sender Profile, onboard RCS, or author WhatsApp templates. Hand those workflows to the related skills after the performance symptom is isolated.

Evidence hierarchy

Start with Sent-owned evidence, then enrich it with provider context. This prevents overfitting to a carrier code that may be missing, stale, or normalized differently across channels.

Process

1. Pin the question before slicing the funnel

Restate the user’s exact question as a measurable comparison. “WhatsApp is bad” becomes “Did WhatsApp DELIVERED rate fall for order templates sent from profile A between Monday and Wednesday?” A precise question keeps the cohort stable and prevents mixed-channel averages from hiding the failure mode.

Capture these dimensions before calculating anything: profile or sender identity, template ID/name, channel, country, send window, recipient segment, and whether fallback or multi-channel broadcast was requested.

Example. If a user says “RCS fallback stopped working,” define the cohort as sends that omitted channel or used channel: ["sent"], then compare the selected payload.channel and message activities. Analyze any explicit multi-channel arrays separately as broadcasts.

2. Build cohorts from Sent message IDs

Use Sent message_id as the primary unit. A v3 send can create separate messages for each recipient and channel pair when multiple channels are specified. Count each Sent message once in a terminal-outcome rollup, then add recipient-level or campaign-level rollups only after deduplication.

Distinguish an activity history from a latest-status snapshot. A history can prove the transitions it contains. A snapshot such as status=DELIVERED proves only the observed current outcome; it does not prove that the export also observed QUEUED, ROUTED, or SENT. Report unavailable transition denominators as N/A, not zero, and never synthesize missing transitions.

Do not use provider IDs such as WhatsApp wamid, SMS carrier IDs, or RCS message IDs as the primary join key unless the exported evidence lacks Sent IDs. Provider IDs are useful for escalation, but the Sent API and dashboard track status by Sent message ID.

3. Normalize lifecycle stages to Sent’s documented statuses

Use Sent’s documented delivery lifecycle as the first-pass funnel: QUEUED, ROUTED, SENT, and DELIVERED. Treat READ as a separate engagement measure for WhatsApp and RCS, never as an SMS delivery requirement. Keep terminal failures, deferred/in-flight messages, inbound RECEIVED messages, and malformed/unknown records in separate buckets using only fields present in the evidence.

4. Check webhook health before diagnosing delivery

A drop in dashboard activity or customer-side events can be a webhook ingestion problem, not a delivery problem. Confirm webhook existence, active status, event subscriptions, recent event history, and test delivery. Rotate secrets only when the user explicitly asks or when a credential compromise is suspected, because rotation immediately invalidates the old secret.

Example. If Sent status shows DELIVERED but the customer database shows “no delivery callbacks,” inspect /v3/webhooks/{id}/events and the customer’s endpoint logs. If Sent has events but the endpoint returned failures, the fix is webhook handling, not campaign routing.

5. Split by channel before naming a root cause

SMS, WhatsApp, and RCS fail differently. Do not average them together unless the user explicitly asked for a blended KPI. Compare each channel’s funnel and then compare the aggregate.

6. Quantify impact before recommending fixes