Debug WhatsApp Message Delivery and Health

Observe WhatsApp is a skill for observing and troubleshooting WhatsApp in Kapso. It searches Logs across API, Meta webhook, workflow and webhook-delivery events, debugs message delivery, inspects webhook retries, triages API errors and runs health checks. It is meant for operational diagnostics: Logs search, message delivery investigation, webhook delivery debugging, error triage, workflow event correlation and WhatsApp health checks.

Every task has a preferred path using the Kapso CLI and a fallback path using bundled Node scripts. Setup for the preferred path is the Kapso CLI installed and authenticated, then kapso status to confirm project access and available WhatsApp numbers. The fallback path uses environment variables for the API base URL (host only) and the API key.

The four main workflows are:

• Search logs. Start with Logs search when you have an identifier, endpoint, message ID, workflow execution ID, webhook delivery ID or request ID, or only a vague "what happened?" prompt. Search the last 24 hours, and if the exact search is empty retry with 7 days before concluding there are no logs. Add a problems-only flag for broad error scans, and leave it off when reconstructing an exact timeline. Log sources are external_api_log, whatsapp_webhook_event, flow_event and webhook_delivery, and filters such as flow_execution_id, endpoint_contains, response_status, whatsapp_message_id and webhook_id narrow a search on purpose.
• Investigate message delivery. Search the WAMID or the customer phone first, resolve the number, list recent messages, inspect a specific message and inspect the conversation.
• Triage errors. Confirm project and number state, run the number health check, search recent problem logs and inspect related templates when relevant.
• Run health checks. Get a project overview, then the health of a phone number.

A typical first step in an investigation is:

kapso logs search --query "<id-or-text>" --period 24h --source all --limit 20 --output json

The package ships example payloads for health, message debugging and triage (health-example.json, message-debugging-example.json and triage-example.json), and its dependencies are installed once with npm i. The bundled scripts cover the fallback path: messages.js, message-details.js and lookup-conversation.js for messages, log-search.js, errors.js, api-logs.js and webhook-deliveries.js for errors and logs, overview.js and whatsapp-health.js for health, and openapi-explore.mjs to explore the OpenAPI spec (search, op, schema and where).

The reference guides add interpretation rules. The message debugging playbook says to review the status timeline in order (sent, delivered, read), surface error codes in status events and map them to remediation, and confirm recipient number formatting, template approval status, messaging health (LIMITED or BLOCKED) and webhook subscription. The health guide gives a 60-second triage order: confirm the check ran, then find the blocking check among phone number access, token validity, messaging health, webhook verification, webhook subscription and the test message. It defines overall status as healthy, degraded, unhealthy or error, treats BLOCKED messaging health as critical and LIMITED as degraded, explains how to pick the most actionable limited entity (phone number, WABA, business portfolio, app or message template), and lists what to collect when escalating. Specific cases are spelled out: an invalid or expired token is a critical blocker that the user cannot fix directly and should be escalated to support; an account with a PENDING status is under Meta review, which is normal and can take a few hours; a payment method issue that limits messaging means templates are blocked while 24-hour window messages still work; and an unverified webhook is verified after a message is sent to the business number and the health check is re-run. The triage guide adds separate procedures for webhook delivery failures (search the webhook_delivery source, review recent attempts, check response status codes and error messages, and verify the webhook URL availability and signature verification logic) and for API errors (search the external_api_log source, filter by status code or endpoint, and identify auth errors, rate limits or upstream failures). Phone number details report a verified name, display number and a quality rating of GREEN, YELLOW or RED, and an unapproved display name affects cold message limits but is not usually the source of an error. It also notes that error 141000 means contacting support, and that when retry_after is present the payload repeats the last check, with delays growing across repeated failures to 5, 15, 30 and then 60 minutes.

Use it when investigating production issues, message failures, workflow behavior or webhook delivery problems in Kapso.

Some neighboring jobs belong to other skills. For webhook setup (create, update, delete, signature verification, event types), use integrate-whatsapp. For Project Event definitions, event-triggered workflow setup or emit_event graph changes, use automate-whatsapp. Prefer resolving a display phone number to the canonical phone_number_id before deep debugging, and prefer Logs search before the older single-resource log endpoints when correlating across messages, workflows, API calls and webhook deliveries. The Platform API fallback returns indexed Logs payloads for the API-key project and requires Logs and Elasticsearch to be enabled. Keep the scripts as the fallback when the CLI is unavailable or when you need API-log or webhook-delivery inspection.

Inputs are an identifier such as a WAMID, message ID, workflow execution ID, webhook delivery ID or request ID, a customer phone number or display number, and a time period. Outputs are log search results (JSON from the CLI), message and conversation details, error and delivery-attempt lists, and health check results that the skill interprets as healthy, degraded, unhealthy or error with the failing checks named.

Developers and operators on Kapso who need to find out why a message failed, a webhook did not deliver or a phone number is unhealthy.