whatsapp-cloud 0.0.3 → 0.0.5

package/agent_docs/messages-namespace-design.md

@@ -0,0 +1,357 @@
+# Messages Namespace Design
+
+This document describes the design patterns and architectural decisions for the Messages namespace. This serves as a blueprint for implementing other namespaces in the WhatsApp Cloud API SDK.
+
+## Core Design Principles
+
+### 1. **Namespace Client Pattern**
+
+Each namespace that requires a base path identifier (like `phoneNumberId` for messages) gets its own client wrapper that handles the base path automatically.
+
+**Pattern:**
+- Create a `{Namespace}Client` class that wraps `HttpClient`
+- The client automatically prepends the namespace identifier to all paths
+- Methods use simple relative paths (e.g., `/messages`) instead of full paths (e.g., `/${phoneNumberId}/messages`)
+
+**Example:**
+```typescript
+// MessagesClient wraps HttpClient with phoneNumberId as base endpoint
+export class MessagesClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly phoneNumberId: string
+  ) {}
+
+  async post<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.post<T>(`/${this.phoneNumberId}${path}`, body);
+  }
+}
+```
+
+**Why:** Treats the namespace identifier (phoneNumberId) as a "client" for that namespace. Different identifiers represent different endpoints, making the abstraction clean and intuitive.
+
+### 2. **Request Structure Matches API**
+
+Request schemas match the WhatsApp API structure exactly, minus fields that are handled internally.
+
+**Pattern:**
+- Request schemas mirror the API payload structure
+- Exclude: `messaging_product`, `recipient_type`, `type` (added by `buildMessagePayload`)
+- Exclude: `phoneNumberId` (handled at client level)
+- Include: All user-provided fields matching API structure
+
+**Example:**
+```typescript
+// API expects: { to, image: { id?, link?, caption? } }
+// Schema matches: { to, image: { id?, link?, caption? } }
+export const sendImageRequestSchema = baseMessageRequestSchema.extend({
+  image: imageSchema, // Matches API structure
+});
+```
+
+**Why:** 
+- Reduces transformation logic
+- Makes API documentation directly applicable
+- Clear mapping between user input and API payload
+
+### 3. **Client-Level Configuration**
+
+Namespace-specific identifiers (like `phoneNumberId`) are handled at the service construction level, not in individual requests.
+
+**Pattern:**
+- Service validates required identifier exists in `HttpClient` at construction
+- Service creates namespace client once with the identifier
+- Methods receive the namespace client, not the raw `HttpClient`
+- No per-request identifier resolution needed
+
+**Example:**
+```typescript
+export class MessagesService {
+  private readonly messagesClient: MessagesClient;
+
+  constructor(httpClient: HttpClient) {
+    // Validate identifier at construction
+    if (!httpClient.phoneNumberId) {
+      throw new WhatsAppValidationError(...);
+    }
+    
+    // Create namespace client once
+    this.messagesClient = new MessagesClient(httpClient, httpClient.phoneNumberId);
+  }
+
+  async sendImage(request: SendImageRequest) {
+    // Method receives namespace client, not HttpClient
+    return sendImage(this.messagesClient, request);
+  }
+}
+```
+
+**Why:**
+- Identifier is required, so validate early (fail fast)
+- Single source of truth for namespace identifier
+- Methods don't need to handle optional overrides
+- Cleaner method signatures
+
+### 4. **Clean Method Pattern**
+
+All methods follow a consistent pattern: validate → extract → build → request.
+
+**Pattern:**
+```typescript
+export async function sendImage(
+  messagesClient: MessagesClient,
+  request: SendImageRequest
+): Promise<MessageResponse> {
+  // 1. Validate request with schema
+  const result = sendImageRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  
+  // 2. Extract validated data
+  const data = result.data;
+  
+  // 3. Build payload (request structure already matches API)
+  const payload = buildMessagePayload(data.to, "image", {
+    image: data.image,
+  });
+  
+  // 4. Make API request (namespace client handles base path)
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}
+```
+
+**Why:**
+- Consistent, predictable flow
+- Easy to understand and maintain
+- Clear separation of concerns
+- Request → result → data trajectory
+
+### 5. **Request → Result → Data Trajectory**
+
+The validation flow follows a clear trajectory: request → validation result → validated data.
+
+**Pattern:**
+```typescript
+// Request comes in
+const result = schema.safeParse(request);
+
+// Extract validated data
+const data = result.data;
+
+// Use data directly (structure matches API)
+const payload = buildMessagePayload(data.to, "image", {
+  image: data.image,
+});
+```
+
+**Why:**
+- Clear path from user input to safe API request
+- No intermediate transformations needed
+- Type-safe throughout the flow
+
+### 6. **No Manual Undefined Filtering**
+
+Let `JSON.stringify` handle undefined values automatically.
+
+**Pattern:**
+```typescript
+// Don't filter undefined manually
+export function buildMessagePayload(to: string, type: string, content: T) {
+  return {
+    messaging_product: "whatsapp" as const,
+    recipient_type: "individual" as const,
+    to,
+    type,
+    ...content, // undefined values automatically omitted by JSON.stringify
+  };
+}
+```
+
+**Why:**
+- `JSON.stringify` automatically omits undefined values
+- Less code, simpler logic
+- No need for `omitUndefined` utilities
+
+## Architecture Layers
+
+### Layer 1: Service (MessagesService)
+- **Responsibility:** Validate namespace requirements, create namespace client
+- **Input:** `HttpClient` (with namespace identifier)
+- **Output:** Namespace client instance
+- **Pattern:** Constructor validation + client creation
+
+### Layer 2: Namespace Client (MessagesClient)
+- **Responsibility:** Handle namespace-specific base path
+- **Input:** `HttpClient` + namespace identifier
+- **Output:** Wrapped client with base path handling
+- **Pattern:** Proxy pattern - wraps HttpClient with path prefix
+
+### Layer 3: Methods (sendImage, sendText, etc.)
+- **Responsibility:** Validate request, build payload, make API call
+- **Input:** Namespace client + request object
+- **Output:** API response
+- **Pattern:** Validate → extract → build → request
+
+### Layer 4: Utilities (buildMessagePayload)
+- **Responsibility:** Add common API fields
+- **Input:** User data
+- **Output:** Complete API payload
+- **Pattern:** Simple object construction
+
+## File Structure
+
+```
+services/messages/
+├── MessagesService.ts      # Service layer - validates & creates client
+├── MessagesClient.ts        # Namespace client - handles base path
+├── methods/
+│   ├── send-image.ts       # Method implementations
+│   ├── send-text.ts
+│   ├── send-location.ts
+│   └── send-reaction.ts
+├── utils/
+│   └── build-message-payload.ts  # Common payload builder
+└── index.ts                # Exports
+```
+
+## Schema Structure
+
+```
+schemas/messages/
+├── request.ts              # Request schemas matching API structure
+└── response.ts             # Response schemas
+```
+
+**Request Schema Pattern:**
+```typescript
+// Base schema (common fields)
+const baseMessageRequestSchema = z.object({
+  to: z.string().regex(...),
+});
+
+// Type-specific schema (matches API structure)
+const imageSchema = z.object({
+  id: z.string().optional(),
+  link: z.string().url().optional(),
+  caption: z.string().max(1024).optional(),
+}).refine(...);
+
+// Combined schema
+export const sendImageRequestSchema = baseMessageRequestSchema.extend({
+  image: imageSchema,
+});
+```
+
+## Type Structure
+
+```
+types/messages/
+├── request.ts              # Request types (inferred from schemas)
+└── response.ts             # Response types
+```
+
+**Type Pattern:**
+```typescript
+// Types are inferred from schemas
+export type SendImageRequest = z.infer<typeof sendImageRequestSchema>;
+```
+
+## Key Design Decisions
+
+### ✅ Do's
+
+1. **Match API structure in requests** - Makes documentation directly applicable
+2. **Validate at service construction** - Fail fast, clear errors
+3. **Use namespace clients** - Clean abstraction for namespace-specific paths
+4. **Follow consistent method pattern** - Easy to understand and maintain
+5. **Let JSON.stringify handle undefined** - Simpler code
+
+### ❌ Don'ts
+
+1. **Don't include namespace identifiers in requests** - Handle at client level
+2. **Don't manually filter undefined** - Let JSON.stringify do it
+3. **Don't transform request structure unnecessarily** - Match API directly
+4. **Don't resolve identifiers in methods** - Do it at service level
+5. **Don't create namespace client per request** - Create once in constructor
+
+## Applying to Other Namespaces
+
+When creating a new namespace (e.g., `BusinessAccounts`):
+
+1. **Create namespace client** (`BusinessAccountsClient`)
+   - Wrap `HttpClient` with namespace-specific base path
+   - Handle namespace identifier (e.g., `businessAccountId`)
+
+2. **Create service** (`BusinessAccountsService`)
+   - Validate namespace identifier exists in constructor
+   - Create namespace client once
+   - Pass client to methods
+
+3. **Create methods** (`getProfile`, `updateProfile`, etc.)
+   - Follow validate → extract → build → request pattern
+   - Use namespace client, not raw `HttpClient`
+   - Match API structure in requests
+
+4. **Create schemas** (`schemas/business-accounts/`)
+   - Match API structure exactly
+   - Exclude internal fields (handled by utilities)
+   - Exclude namespace identifier (handled at client level)
+
+5. **Create types** (`types/business-accounts/`)
+   - Infer from schemas using `z.infer`
+
+## Example: Applying Pattern to Business Accounts
+
+```typescript
+// 1. Namespace Client
+export class BusinessAccountsClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly businessAccountId: string
+  ) {}
+
+  async get<T>(path: string): Promise<T> {
+    return this.httpClient.get<T>(`/${this.businessAccountId}${path}`);
+  }
+}
+
+// 2. Service
+export class BusinessAccountsService {
+  private readonly accountsClient: BusinessAccountsClient;
+
+  constructor(httpClient: HttpClient) {
+    if (!httpClient.businessAccountId) {
+      throw new WhatsAppValidationError(...);
+    }
+    this.accountsClient = new BusinessAccountsClient(
+      httpClient,
+      httpClient.businessAccountId
+    );
+  }
+
+  async getProfile() {
+    return getProfile(this.accountsClient);
+  }
+}
+
+// 3. Method
+export async function getProfile(
+  accountsClient: BusinessAccountsClient
+): Promise<ProfileResponse> {
+  return accountsClient.get<ProfileResponse>("/profile");
+}
+```
+
+## Summary
+
+The Messages namespace design provides a clean, consistent pattern for implementing API namespaces:
+
+- **Namespace clients** handle base paths automatically
+- **Request structures** match API directly
+- **Service layer** validates and creates clients
+- **Methods** follow a consistent pattern
+- **No manual filtering** - let JSON.stringify handle it
+
+This pattern ensures consistency, maintainability, and clarity across all namespaces in the SDK.
+

package/cloud-api-docs/webhooks/endpoint.md

@@ -0,0 +1,112 @@
+Nav-Logo
+Build with us
+Docs
+Blog
+Resources
+Developer centers
+Meine Apps
+Dokumente
+Übersicht
+Webhook-Endpunkt erstellen
+Webhook-Endpunkt erstellen
+Aktualisiert: 07.11.2025
+Erfahre mehr über Webhook-Anfragen und -Antworten, damit du deinen eigenen Webhook-Endpunkt auf einem öffentlichen Server einrichten und konfigurieren kannst.
+Bevor du deine App in einer Produktionsumgebung nutzen kannst, musst du deinen eigenen Webhook-Endpunkt auf einem öffentlichen Server erstellen und konfigurieren, der GET- und POST-Anfragen empfangen und beantworten sowie Webhook-Payloads validieren und erfassen kann.
+TLS/SSL
+Der Server des Webhook-Endpunkts muss über ein korrekt konfiguriertes und installiertes digitales TLS- oder SSL-Sicherheitszertifikat verfügen. Selbstsignierte Zertifikate werden nicht unterstützt.
+mTLS
+Webhooks unterstützen für zusätzliche Sicherheit gegenseitiges TLS (mutual TLS, mTLS). Im Dokument mTLS für Webhooks der Graph API erfährst du, wie du mTLS aktivieren und verwenden kannst.
+Beachte, dass das Aktivieren und Deaktivieren von mTLS nicht auf der Ebene eines WABA oder einer Unternehmenstelefonnummer unterstützt wird. Wenn mehr als eine App auf die Plattform zugreift, musst du mTLS für jede App aktivieren.
+GET-Anfragen
+GET-Anfragen werden verwendet, um deinen Webhook-Endpunkt zu verifizieren. Jedes Mal, wenn du im App-Dashboard das Feld Rückruf-URL oder Verifizierungstoken festlegst oder bearbeitest, senden wir eine GET-Anfrage an deinen Webhook-Endpunkt. Du musst diese Anfrage validieren und auf sie antworten.
+Anfragesyntax
+GET <CALLBACK_URL>
+?hub.mode=subscribe
+&hub.challenge=<HUB.CHALLENGE>
+&hub.verify_token=<HUB.VERIFY_TOKEN>
+Anfrageparameter
+Platzhalter Beschreibung Beispielwert
+<CALLBACK_URL>
+Die URL deines Webhook-Endpunkts
+Füge diese URL im App-Dashboard im Feld Rückruf-URL hinzu, wenn du später Webhooks konfigurierst.
+https://www.luckyshrub.com/webhooks
+<HUB.CHALLENGE>
+Ein zufälliger String, den wir generieren
+1158201444
+<HUB.VERIFY_TOKEN>
+Ein Verifizierungs-String deiner Wahl. Speichere diesen String auf deinem Server.
+Füge diesen String später beim Konfigurieren von Webhooks im Feld Verifizierungstoken im App-Dashboard hinzu.
+vibecoding
+Validierung
+Um GET-Anfragen zu validieren, vergleiche den hub.verify_token-Wert in der Anfrage mit dem Verifizierungs-String, den du auf deinem Server gespeichert hast. Stimmen die Werte überein, ist die Anfrage gültig, andernfalls ist sie ungültig.
+Antwort
+Wenn die Anfrage gültig ist, antworte mit dem HTTP-Status 200 und dem hub.challenge-Wert. Wenn die Anfrage ungültig ist, antworte mit einem HTTP-Statuscode auf der 400er-Ebene oder mit einem anderen Status als 200.
+Wenn du Webhooks konfigurierst, senden wir eine GET-Anfrage an deinen Webhook-Endpunkt. Wenn der Status 200 und der in der Anfrage enthaltene hub.challenge-Wert zurückgesendet werden, betrachten wir deinen Webhook-Endpunkt als verifiziert und beginnen damit, dir Webhooks zu senden. Wenn dein Webhook-Endpunkt mit einer anderen Antwort reagiert, betrachten wir deinen Webhook-Endpunkt jedoch als nicht verifiziert und es werden keine Webhooks an deinen Endpunkt gesendet.
+POST-Anfragen
+Jedes Mal, wenn ein Webhook-Event für Webhook-Felder ausgelöst wird, die du abonniert hast, wird eine POST-Anfrage an deinen Webhook-Endpunkt gesendet. Sie enthält eine JSON-Payload mit einer Beschreibung des Events.
+Anfragesyntax
+POST <CALLBACK_URL>
+Content-Type: application/json
+X-Hub-Signature-256: sha256=<SHA256_PAYLOAD_HASH>
+Content-Length: <CONTENT_LENGTH><JSON_PAYLOAD>
+Anfrageparameter
+Platzhalter Beschreibung Beispielwert
+<CALLBACK_URL>
+Die URL deines Webhook-Endpunkts
+https://www.luckyshrub.com/webhooks
+<CONTENT_LENGTH>
+Inhaltslänge in Byte
+492
+<JSON_PAYLOAD>
+Post-Text-Payload, formatiert als JSON
+In den Referenzen zu den Feldern findest du Beispiel-Payloads.
+<SHA256_PAYLOAD_HASH>
+HMAC-SHA256-Hash, berechnet aus dem Text der POST-Payload und deinem App-Geheimcode als Secret Key.
+b63bb356dff0f1c24379efea2d6ef0b2e2040853339d1bcf13f9018790b1f7d2
+Validierung
+So validierst du die Anfrage:
+Generiere einen HMAC-SHA256-Hash mit der JSON-Payload als Nachrichteneingabe und deinem App-Geheimcode als Secret Key. Vergleiche deinen generierten Hash mit dem Hash, der dem X-Hub-Signature-256-Header (alles nach sha256=) zugewiesen ist.
+Stimmen die Hashes überein, ist die Payload gültig. Erfasse die Payload und verarbeite ihren Inhalt je nach Geschäftsanforderungen. Wenn sie nicht übereinstimmen, kannst du die Payload als ungültig betrachten.
+Beachte, dass wir keine APIs zum Abrufen von Webhook-Verlaufsdaten anbieten. Du musst also entsprechend die Webhook-Payload erfassen und speichern.
+Antwort
+Wenn die Anfrage gültig ist, antworte mit dem HTTP-Status 200. Andernfalls sendest du eine Antwort mit einem HTTP-Status der 400er-Ebene oder mit einem anderen Status als 200.
+Batching
+POST-Anfragen werden in einem Batch mit maximal 1.000 Aktualisierungen aggregiert und gesendet. Die Zusammenfassung in Batches kann jedoch nicht garantiert werden, also passe deine Server so an, dass sie jede POST-Anfrage einzeln verarbeiten können.
+Wenn eine an deinen Server gesendete POST-Anfrage fehlschlägt, wiederholen wir den Vorgang unmittelbar und starten anschließend in immer größeren Abständen innerhalb der nächsten 36 Stunden weitere Wiederholungsversuche. Dein Server sollte in diesen Fällen eine Deduplizierung durchführen können.
+Antworten, die nicht innerhalb von 36 Stunden bestätigt werden, werden gelöscht.
+Webhooks konfigurieren
+Nachdem du deinen Webhook-Endpunkt erstellt hast, navigiere zum Bereich App-Dashboard > WhatsApp > Konfiguration und füge im Feld Rückruf-URL die URL deines Webhook-Endpunkts und im Feld Verifizierungstoken deinen Verifizierungs-String hinzu.
+Hinweis: Wenn du deine App mit dem Anwendungsfall Über WhatsApp mit deinen Kunden in Kontakt treten erstellt hast, navigiere stattdessen zu App-Dashboard > Anwendungsfälle > Anpassen > Konfiguration.
+
+Wenn dein Webhook-Endpunkt auf GET-Anfragen zur Webhook-Verifizierung korrekt antwortet, werden deine Änderungen im Bereich gespeichert und es wird eine Liste der Felder angezeigt, die du abonnieren kannst. Anschließend kannst du die Felder abonnieren, die deinen geschäftlichen Anforderungen entsprechen.
+Beachte, dass du den Endpunkt POST Application Subscriptions verwenden kannst, um Webhooks als alternative Methode zu konfigurieren. Dazu ist allerdings ein App-Token erforderlich. Im Dokument Subscriptions-Edge der Graph API erfährst du, wie das geht. Verwende dabei „whatsapp_business_account“ als Objektwert.
+War diese Seite hilfreich?
+„Daumen hoch“-Symbol
+„Daumen runter“-Symbol
+Meta
+FacebookInstagramXLinkedInYouTube
+Build with Meta
+AI
+Meta Horizon
+Social technologies
+Wearables
+News
+Meta for Developers
+Blog
+Success stories
+Support
+Developer Support
+Bug tool
+Platform status
+Developer community forum
+Report an incident
+About us
+About
+Careers
+Terms and policies
+Responsible platform initiatives
+Platform terms
+Developer policies
+Privacy policy
+Cookies
+English (US)

package/cloud-api-docs/webhooks/overview.md

@@ -0,0 +1,154 @@
+Nav-Logo
+Build with us
+Docs
+Blog
+Resources
+Developer centers
+Meine Apps
+Dokumente
+Übersicht
+Webhooks
+Webhooks
+Aktualisiert: 07.11.2025
+In diesem Dokument werden Webhooks beschrieben und wie sie auf der WhatsApp Business-Plattform verwendet werden.
+Webhooks sind HTTP-Anfragen mit JSON-Payloads, die von Meta-Servern an einen von dir bestimmten Server gesendet werden. Die WhatsApp Business-Plattform verwendet Webhooks, um dich über eingehende Nachrichten, den Status ausgehender Nachrichten und andere wichtige Informationen zu informieren, wie z. B. Änderungen an deinem Kontostatus, Upgrades der Nachrichtenfunktion und Änderungen an der Qualitätsbewertungen deiner Vorlagen.
+Hier siehst du einen Webhook, der eine Nachricht beschreibt, die von einem*einer WhatsApp-Benutzer*in an ein Unternehmen gesendet wurde:
+{
+"object": "whatsapp_business_account",
+"entry": [
+{
+"id": "102290129340398",
+"changes": [
+{
+"value": {
+"messaging_product": "whatsapp",
+"metadata": {
+"display_phone_number": "15550783881",
+"phone_number_id": "106540352242922"
+},
+"contacts": [
+{
+"profile": {
+"name": "Sheena Nelson"
+},
+"wa_id": "16505551234"
+}
+],
+"messages": [
+{
+"from": "16505551234",
+"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
+"timestamp": "1749416383",
+"type": "text"
+"text": {
+"body": "Does it come in another color?"
+}
+}
+]
+},
+"field": "messages"
+}
+]
+}
+]
+}
+
+Einen Webhook-Endpunkt erstellen
+Um Webhooks zu empfangen, musst du einen Webhook-Endpunkt erstellen und konfigurieren. Im Dokument Webhook-Endpunkt erstellen erfährst du, wie du deinen eigenen Endpunkt erstellst.
+Wenn du noch nicht bereit bist, deinen eigenen Endpunkt zu erstellen, kannst du einen Test-Webhook-Endpunkt erstellen, der Webhook-Payloads an die Konsole exportiert. Beachte jedoch, dass du deinen eigenen Endpunkt erstellen musst, bevor du deine App in einer Produktionsumgebung verwenden kannst.
+Berechtigungen
+Du benötigst die folgenden Berechtigungen, um Webhooks zu erhalten:
+whatsapp_business_messaging – für messages-Webhooks
+whatsapp_business_management – für alle anderen Webhooks
+Wenn du ein*e direkte*r Entwickler*in bist, gewähre deiner App über deine*n Systemnutzer*in diese Berechtigungen, wenn du dein Systemtoken generierst.
+Wenn du als Lösungsanbieter*in diese Berechtigungen benötigst, um deinen Unternehmenskunden entsprechende Services zur Verfügung zu stellen, musst du vor der App-Review die Genehmigung für erweiterten Zugriff auf die Berechtigungen erhalten. Erst dann können deine Unternehmenskunden deiner App während des Onboardings diese Berechtigungen erteilen.
+Felder
+Sobald du deinen Webhook-Endpunkt erstellt und konfiguriert hast, kannst du die folgenden Webhook-Felder abonnieren.
+Name des Feldes Beschreibung
+account_alerts
+Der account_alerts-Webhook benachrichtigt dich über Änderungen des Messaging-Limits, des Unternehmensprofils und des Status als offizielles Unternehmenskonto einer Unternehmenstelefonnummer.
+account_review_update
+Der account_review_update-Webhook benachrichtigt dich, wenn ein WhatsApp-Unternehmenskonto hinsichtlich der Einhaltung unserer Richtlinien überprüft wurde.
+account_update
+Der account_update-Webhook benachrichtigt dich über Änderungen an der partnergeführten Unternehmensverifizierung eines WhatsApp-Unternehmenskontos, seiner Berechtigung für den Tarif für internationale Authentifizierung oder seinem Hauptgeschäftsstandort, wenn das Konto mit einem*einer Lösungsanbieter*in geteilt wird, bei Richtlinien- oder Nutzungsbedingungsverstößen oder wenn es gelöscht wird.
+automatic_events
+Der automatic_events-Webhook benachrichtigt dich, wenn wir ein Kauf- oder Lead-Event in einem Chat-Thread zwischen dir und einem*einer WhatsApp-Nutzer*in erkennen, der*die dir über deine Click-to-WhatsApp Ad eine Nachricht gesendet hat. Dazu musst du Berichte für automatische Events aktiviert haben.
+business_capability_update
+Der business_capability_update-Webhook informiert dich über Änderungen der Funktionen für WhatsApp-Unternehmenskonto oder Business-Portfolio (Messaging-Limits, Telefonnummer-Limits usw.).
+history
+Der history-Webhook wird verwendet, um den Chatverlauf in der WhatsApp Business-App eines Unternehmenskunden zu synchronisieren, der von einem*einer Lösungsanbieter*in freigeschaltet wurde.
+message_template_components_update
+Der message_template_components_update-Webhook benachrichtigt dich über Änderungen an den Komponenten einer Vorlage.
+message_template_quality_update
+Der message_template_quality_update-Webhook benachrichtigt dich über Änderungen an der Qualitätsbewertung einer Vorlage.
+message_template_status_update
+Der message_template_status_update-Webhook benachrichtigt dich über Änderungen am Status einer vorhandenen Vorlage.
+messages
+Der messages-Webhook beschreibt Nachrichten, die von einem*einer WhatsApp-Nutzer*in an ein Unternehmen gesendet werden, und den Status von Nachrichten, die von einem Unternehmen an eine*n WhatsApp-Nutzer*in gesendet werden.
+partner_solutions
+Der partner_solutions-Webhook beschreibt Änderungen am Status einer Multi-Partner-Lösung.
+payment_configuration_update
+Der payment_configuration_update-Webhook informiert dich über Änderungen an Zahlungskonfigurationen für die Payments API für Indien und die Payments API für Brasilien.
+phone_number_name_update
+Der phone_number_name_update-Webhook informiert dich über die Verifizierung des Display-Namens der Unternehmenstelefonnummer.
+phone_number_quality_update
+Der phone_number_quality_update-Webhook benachrichtigt dich über Änderungen an der Durchsatzrate einer Unternehmenstelefonnummer.
+security
+Der security-Webhook benachrichtigt dich über Änderungen an den Sicherheitseinstellungen einer Unternehmenstelefonnummer.
+smb_app_state_sync
+Der smb_app_state_sync-Webhook wird zum Synchronisieren von Kontakten von Nutzer*innen der WhatsApp Business-App verwendet, die über eine*n Lösungsanbieter*in freigeschaltet wurden.
+smb_message_echoes
+Der smb_message_echoes-Webhook benachrichtigt dich über Nachrichten, die über die WhatsApp Business-App oder ein begleitendes („verknüpftes“) Gerät von einem Unternehmenskunden gesendet wurden, der über eine*n Lösungsanbieter*in für die Cloud API freigeschaltet wurde.
+template_category_update
+Der template_category_update-Webhook benachrichtigt dich über Änderungen an der Kategorie einer Vorlage.
+user_preferences
+Der user_preferences-Webhook benachrichtigt dich über Änderungen an den Marketing-Nachrichten-Einstellungen eines*einer WhatsApp-Nutzer*in.
+Webhooks überschreiben
+Du kannst einen alternativen Webhook-Endpunkt für messages-Webhooks für dein WhatsApp-Unternehmenskonto (WABA) oder deine Unternehmenstelefonnummer verwenden. Dieser kann für Testzwecke nützlich sein oder wenn du als Lösungsanbieter eindeutige Webhook-Endpunkte für alle deine registrierten Kund\*innen verwenden möchtest.
+In unserem Dokument zu Webhook-Überschreibungen erfährst du, wie du Webhooks überschreiben kannst.
+Payload-Größe
+Payload-Webhooks können bis zu 3 MB groß sein.
+Fehler bei der Webhook-Auslieferung
+Wenn wir eine Webhook-Anfrage an deinen Endpunkt senden und dein Server mit einem anderen HTTP-Statuscode als 200 antwortet oder wenn wir den Webhook aus einem anderen Grund nicht zustellen können, versuchen wir es so lange mit abnehmender Häufigkeit, bis die Anfrage erfolgreich ist, und zwar bis zu 7 Tage lang.
+Beachte, dass Wiederholungsversuche an alle Apps gesendet werden, die Webhooks (und ihre entsprechenden Felder) für das WhatsApp Business-Konto abonniert haben. Dies kann zu doppelten Webhook-Benachrichtigungen führen.
+IP-Adressen
+Du kannst die IP-Adressen unserer Webhook-Server abrufen, indem du in deinem Terminal den folgenden Befehl ausführst:
+whois -h whois.radb.net — '-i origin AS32934' | grep '^route' | awk '{print $2}' | sort
+Wir ändern diese IP-Adressen in regelmäßigen Abständen. Wenn du also unsere Server auf der Positivliste hast, solltest du diese Liste gelegentlich neu erstellen und deine Positivliste entsprechend aktualisieren.
+Problembehandlung
+Wenn du keine Webhooks erhältst:
+Vergewissere dich, dass dein Endpunkt Anfragen akzeptiert.
+Sende eine Test-Payload an deinen Endpunkt über das Panel App-Dashboard > WhatsApp > Konfigurationen.
+Stelle sicher, dass der Live-Modus für deine App aktiviert ist. Wenn deine App im Entwicklungsmodus ist, werden einige Webhooks nicht gesendet.
+Mehr dazu
+Siehe unseren Blogeintrag Implementierung von Webhooks mit Node.js für WhatsApp Business.
+War diese Seite hilfreich?
+„Daumen hoch“-Symbol
+„Daumen runter“-Symbol
+Meta
+FacebookInstagramXLinkedInYouTube
+Build with Meta
+AI
+Meta Horizon
+Social technologies
+Wearables
+News
+Meta for Developers
+Blog
+Success stories
+Support
+Developer Support
+Bug tool
+Platform status
+Developer community forum
+Report an incident
+About us
+About
+Careers
+Terms and policies
+Responsible platform initiatives
+Platform terms
+Developer policies
+Privacy policy
+Cookies
+English (US)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "whatsapp-cloud",
-  "version": "0.0.3",
-  "description": "",
+  "version": "0.0.5",
+  "description": "Work in progress. A WhatsApp client tailored for LLMs—built to actually work.",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -11,11 +11,18 @@
   "license": "MIT",
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
+    "@types/node": "^25.0.3",
+    "dotenv": "^17.2.3",
     "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
+  "dependencies": {
+    "zod": "^4.2.1"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
-    "lint": "tsc"
+    "lint": "tsc",
+    "example": "tsx src/examples/main.ts"
   }
 }