Observe Whatsapp

What Is This?

Overview

Observe WhatsApp is a diagnostic skill within the Kapso platform that provides structured visibility into WhatsApp messaging operations. It enables developers and operations teams to investigate message delivery failures, inspect webhook payloads, triage API errors, and run systematic health checks against WhatsApp infrastructure. Rather than relying on scattered logs or manual API calls, this skill centralizes the observability workflow into a consistent, repeatable process.

The skill is designed for production environments where WhatsApp serves as a critical communication channel. When messages fail to deliver, webhooks stop firing, or API responses return unexpected errors, teams need a fast path to root cause analysis. Observe WhatsApp provides that path by surfacing relevant signals, delivery states, and retry histories in a structured format that supports rapid triage.

Built on top of the Kapso agent framework, this skill integrates with WhatsApp Cloud API endpoints and webhook delivery infrastructure. It treats observability as a first-class concern, giving teams the tools to move from symptom to diagnosis without writing custom debugging scripts for every incident.

Who Should Use This

• Backend developers building or maintaining WhatsApp integrations who need to verify message delivery and inspect API response codes during development and production incidents.
• DevOps and platform engineers responsible for monitoring messaging infrastructure and ensuring webhook endpoints remain healthy and responsive.
• Support engineers triaging customer-reported message failures who need to trace a specific message through the delivery pipeline.

Why Use It?

Problems It Solves

• Silent message failures: Messages appear sent on the application side but never reach recipients. Without delivery state inspection, these failures are invisible until a customer reports them.
• Webhook delivery gaps: Webhook events fail to reach your endpoint due to network issues, misconfigured URLs, or server errors. Retry histories are difficult to reconstruct without dedicated tooling.
• Ambiguous API errors: WhatsApp Cloud API returns error codes that require cross-referencing documentation. Triage without context wastes time and delays resolution.

Core Highlights

• Inspect message delivery status and delivery timestamps for specific message IDs
• Retrieve webhook delivery logs including payload content, HTTP response codes, and retry attempts
• Triage WhatsApp Cloud API errors with structured error code context
• Run health checks covering credentials, phone number status, and webhook configuration
• Filter delivery events by time range, status, or recipient
• Surface retry histories for failed webhook deliveries
• Identify patterns across multiple failed messages to distinguish isolated failures from systemic issues
• Operate directly within the Kapso agent interface without switching between external dashboards

How to Use It?

Basic Usage

To begin observing WhatsApp activity in Kapso, invoke the skill with a diagnostic intent. The following examples illustrate common starting points.

Check the delivery status of a specific message:

observe whatsapp message status --message-id wamid.HBgLMTY1MDUwNzY1NQIQERgSM0E3NEI2QzQ4NTY3OEJBMAA=

Run a general health check on your WhatsApp configuration:

observe whatsapp health-check --phone-number-id 123456789

Retrieve recent webhook delivery attempts:

observe whatsapp webhooks --last 50 --status failed

Specific Scenarios

Scenario 1: Investigating a reported message failure A customer reports they did not receive a message sent two hours ago. Use the message ID from your application logs to pull the delivery state, timestamp, and any error codes returned by the WhatsApp API.

Scenario 2: Debugging webhook retry storms Your endpoint logs show repeated identical payloads arriving. Query the webhook delivery history for a specific event ID to confirm retry count, intervals, and whether your endpoint returned non-200 responses that triggered retries.

Scenario 3: Pre-launch health verification Before enabling a new WhatsApp channel in production, run a full health check to confirm that the phone number is registered, the webhook URL is reachable, and the API token has the required permissions.

Real-World Examples

A support team uses this skill to resolve a ticket where a transactional notification failed. By querying the message ID, they identify a 131047 error code indicating a recipient phone number that is not a valid WhatsApp account, allowing them to update the contact record.

An operations engineer notices a spike in webhook failures during a deployment. Using the webhook inspection command, they confirm that a load balancer configuration change caused 502 responses, triggering WhatsApp retry logic and flooding the endpoint.

A developer integrating a new business account runs the health check before launch and discovers the webhook subscription is missing the messages field, which would have caused all inbound messages to be silently dropped.

Important Notes

Requirements

• An active Kapso account with the Observe WhatsApp skill enabled
• A configured WhatsApp Cloud API integration with valid credentials and a registered phone number ID
• Webhook endpoint accessible from WhatsApp infrastructure with proper SSL configuration