@elizaos/plugin-whatsapp 2.0.0-alpha.8 → 2.0.0-beta.1

package/dist/normalize.d.ts

@@ -0,0 +1,69 @@
+/**
+ * WhatsApp text chunk limit
+ */
+export declare const WHATSAPP_TEXT_CHUNK_LIMIT = 4096;
+/**
+ * Normalizes a phone number to E.164 format
+ */
+export declare function normalizeE164(input: string): string;
+/**
+ * Checks if a value is a WhatsApp group JID (e.g., "123456789-987654321@g.us")
+ */
+export declare function isWhatsAppGroupJid(value: string): boolean;
+/**
+ * Checks if a value looks like a WhatsApp user target
+ * (e.g., "41796666864:0@s.whatsapp.net" or "123@lid")
+ */
+export declare function isWhatsAppUserTarget(value: string): boolean;
+/**
+ * Normalizes a WhatsApp target (phone number, user JID, or group JID)
+ * Returns null if the target is invalid
+ */
+export declare function normalizeWhatsAppTarget(value: string): string | null;
+/**
+ * Formats a WhatsApp ID for display
+ */
+export declare function formatWhatsAppId(id: string): string;
+/**
+ * Checks if a WhatsApp ID is a group
+ */
+export declare function isWhatsAppGroup(id: string): boolean;
+/**
+ * Gets the chat type from a WhatsApp ID
+ */
+export declare function getWhatsAppChatType(id: string): "group" | "user";
+/**
+ * Builds a WhatsApp JID from a phone number
+ */
+export declare function buildWhatsAppUserJid(phoneNumber: string): string;
+/**
+ * Options for text chunking
+ */
+export interface ChunkWhatsAppTextOpts {
+    limit?: number;
+}
+/**
+ * Chunks text for WhatsApp messages
+ */
+export declare function chunkWhatsAppText(text: string, opts?: ChunkWhatsAppTextOpts): string[];
+/**
+ * Truncates text to a maximum length with ellipsis
+ */
+export declare function truncateText(text: string, maxLength: number): string;
+/**
+ * Resolves the system location string for logging
+ */
+export declare function resolveWhatsAppSystemLocation(params: {
+    chatType: "group" | "user";
+    chatId: string;
+    chatName?: string;
+}): string;
+/**
+ * Validates a WhatsApp phone number
+ */
+export declare function isValidWhatsAppNumber(value: string): boolean;
+/**
+ * Formats a phone number for WhatsApp display
+ */
+export declare function formatWhatsAppPhoneNumber(phoneNumber: string): string;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AA0B9C;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAyBnD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAWzD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG3D;AAmBD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA+BpE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAIhE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA2DD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,MAAM,EAAE,CAwB1F;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQpE;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE;IACpD,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAIT;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAW5D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAcrE"}

package/dist/pairing-service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * WhatsApp pairing service — manages Baileys sessions for QR code authentication.
+ *
+ * This service is separate from the main WhatsApp plugin because the plugin
+ * initializes during runtime startup (too late for interactive QR flow).
+ * Once pairing succeeds, the auth state is persisted to disk so the plugin
+ * can reconnect automatically on subsequent startups.
+ */
+/** Validate accountId to prevent path traversal. Only allows alphanumeric, dash, underscore. */
+export declare function sanitizeAccountId(raw: string): string;
+export type WhatsAppPairingStatus = "idle" | "initializing" | "waiting_for_qr" | "connected" | "disconnected" | "timeout" | "error";
+export interface WhatsAppPairingEvent {
+    type: "whatsapp-qr" | "whatsapp-status";
+    accountId: string;
+    qrDataUrl?: string;
+    expiresInMs?: number;
+    status?: WhatsAppPairingStatus;
+    phoneNumber?: string;
+    error?: string;
+}
+export interface WhatsAppPairingOptions {
+    authDir: string;
+    accountId: string;
+    onEvent: (event: WhatsAppPairingEvent) => void;
+}
+export declare class WhatsAppPairingSession {
+    private socket;
+    private status;
+    private options;
+    private qrAttempts;
+    private readonly MAX_QR_ATTEMPTS;
+    private restartTimer;
+    constructor(options: WhatsAppPairingOptions);
+    start(): Promise<void>;
+    stop(): void;
+    getStatus(): WhatsAppPairingStatus;
+    private setStatus;
+}
+export declare function whatsappAuthExists(workspaceDir: string, accountId?: string): boolean;
+export declare function whatsappLogout(workspaceDir: string, accountId?: string): Promise<void>;
+//# sourceMappingURL=pairing-service.d.ts.map

package/dist/pairing-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-service.d.ts","sourceRoot":"","sources":["../src/pairing-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED,MAAM,MAAM,qBAAqB,GAC7B,MAAM,GACN,cAAc,GACd,gBAAgB,GAChB,WAAW,GACX,cAAc,GACd,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,aAAa,GAAG,iBAAiB,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;CAChD;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAA6E;IAC3F,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAK;IACrC,OAAO,CAAC,YAAY,CAA8C;gBAEtD,OAAO,EAAE,sBAAsB;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuG5B,IAAI,IAAI,IAAI;IAaZ,SAAS,IAAI,qBAAqB;IAIlC,OAAO,CAAC,SAAS;CAQlB;AAED,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,SAAY,GAAG,OAAO,CAGvF;AAED,wBAAsB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,SAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA8D/F"}

package/dist/runtime-service.d.ts

@@ -0,0 +1,116 @@
+import { type IAgentRuntime, type Memory, Service, type UUID } from "@elizaos/core";
+import type { WhatsAppMessageResponse, WhatsAppWebhookEvent } from "./types";
+type RuntimeServiceConfig = {
+    accountId: string;
+    name?: string;
+    transport: "baileys";
+    authDir: string;
+    dmPolicy?: "open" | "allowlist" | "pairing" | "disabled";
+    groupPolicy?: "open" | "allowlist" | "disabled";
+    allowFrom?: string[];
+    groupAllowFrom?: string[];
+} | {
+    accountId: string;
+    name?: string;
+    transport: "cloudapi";
+    accessToken: string;
+    phoneNumberId: string;
+    businessAccountId?: string;
+    webhookVerifyToken?: string;
+    apiVersion?: string;
+    dmPolicy?: "open" | "allowlist" | "pairing" | "disabled";
+    groupPolicy?: "open" | "allowlist" | "disabled";
+    allowFrom?: string[];
+    groupAllowFrom?: string[];
+};
+type RuntimeSendHandler = Parameters<IAgentRuntime["registerSendHandler"]>[1];
+type ConnectorTargetInfo = Parameters<RuntimeSendHandler>[1];
+type MessageConnectorRegistration = Parameters<IAgentRuntime["registerMessageConnector"]>[0];
+type MessageConnectorQueryContext = Parameters<NonNullable<MessageConnectorRegistration["resolveTargets"]>>[1];
+type ConnectorFetchMessagesParams = {
+    target?: ConnectorTargetInfo;
+    limit?: number;
+    before?: string;
+    after?: string;
+    channelId?: string;
+    roomId?: UUID;
+};
+type ConnectorSearchMessagesParams = ConnectorFetchMessagesParams & {
+    query?: string;
+};
+type ConnectorReactionParams = {
+    target?: ConnectorTargetInfo;
+    channelId?: string;
+    roomId?: UUID;
+    messageId?: string;
+    emoji?: string;
+    remove?: boolean;
+};
+type ConnectorUserLookupParams = {
+    userId?: string;
+    username?: string;
+    handle?: string;
+    query?: string;
+};
+type KnownWhatsAppTarget = {
+    accountId: string;
+    chatId: string;
+    senderId: string;
+    label: string;
+    isGroup: boolean;
+    lastMessageAt: number;
+    roomId?: UUID;
+};
+export declare class WhatsAppConnectorService extends Service {
+    static serviceType: string;
+    protected runtime: IAgentRuntime;
+    capabilityDescription: string;
+    connected: boolean;
+    phoneNumber: string | null;
+    private defaultAccountId;
+    private clients;
+    private configs;
+    private phoneNumbers;
+    private client;
+    config: RuntimeServiceConfig | undefined;
+    private knownTargets;
+    constructor(runtime?: IAgentRuntime);
+    resolveAccountId(accountId?: string | null): string;
+    private getClientForAccount;
+    private getConfigForAccount;
+    private getConnectorAccountIds;
+    private targetKey;
+    private roomIdFor;
+    private entityIdFor;
+    private worldIdFor;
+    private metadataMatchesAccount;
+    static start(runtime: IAgentRuntime): Promise<WhatsAppConnectorService>;
+    static registerSendHandlers(runtime: IAgentRuntime, service: WhatsAppConnectorService): void;
+    initialize(): Promise<void>;
+    stop(): Promise<void>;
+    handleWebhook(event: WhatsAppWebhookEvent): Promise<void>;
+    verifyWebhook(mode: string, token: string, challenge: string, accountId?: string): string | null;
+    private resolveWebhookAccountId;
+    private bindClientEvents;
+    private handleNormalizedMessage;
+    private handleIncomingWebhookMessage;
+    private processIncomingMessage;
+    private sendTextMessage;
+    sendMessage(message: {
+        accountId?: string;
+        type: "text";
+        to: string;
+        content: string;
+        replyToMessageId?: string;
+    }): Promise<WhatsAppMessageResponse>;
+    fetchConnectorMessages(context: MessageConnectorQueryContext, params: ConnectorFetchMessagesParams): Promise<Memory[]>;
+    searchConnectorMessages(context: MessageConnectorQueryContext, params: ConnectorSearchMessagesParams): Promise<Memory[]>;
+    reactConnectorMessage(runtime: IAgentRuntime, params: ConnectorReactionParams): Promise<void>;
+    getConnectorUser(_runtime: IAgentRuntime, params: ConnectorUserLookupParams): Promise<unknown>;
+    listKnownTargets(accountId?: string | null): KnownWhatsAppTarget[];
+    getKnownTarget(chatId: string, accountId?: string | null): KnownWhatsAppTarget | null;
+    findKnownChatByParticipant(participant: string, accountId?: string | null): KnownWhatsAppTarget | null;
+    private rememberTarget;
+}
+export {};
+//# sourceMappingURL=runtime-service.d.ts.map

package/dist/runtime-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-service.d.ts","sourceRoot":"","sources":["../src/runtime-service.ts"],"names":[],"mappings":"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"}

package/dist/services/whatsapp-pairing.d.ts

@@ -0,0 +1,41 @@
+/**
+ * WhatsApp pairing service — manages Baileys sessions for QR code authentication.
+ *
+ * This service is separate from `@elizaos/plugin-whatsapp` because the plugin
+ * initializes during runtime startup (too late for interactive QR flow).
+ * Once pairing succeeds, the auth state is persisted to disk so the plugin
+ * can reconnect automatically on subsequent startups.
+ */
+/** Validate accountId to prevent path traversal. Only allows alphanumeric, dash, underscore. */
+export declare function sanitizeAccountId(raw: string): string;
+export type WhatsAppPairingStatus = "idle" | "initializing" | "waiting_for_qr" | "connected" | "disconnected" | "timeout" | "error";
+export interface WhatsAppPairingEvent {
+    type: "whatsapp-qr" | "whatsapp-status";
+    accountId: string;
+    qrDataUrl?: string;
+    expiresInMs?: number;
+    status?: WhatsAppPairingStatus;
+    phoneNumber?: string;
+    error?: string;
+}
+export interface WhatsAppPairingOptions {
+    authDir: string;
+    accountId: string;
+    onEvent: (event: WhatsAppPairingEvent) => void;
+}
+export declare class WhatsAppPairingSession {
+    private socket;
+    private status;
+    private options;
+    private qrAttempts;
+    private readonly MAX_QR_ATTEMPTS;
+    private restartTimer;
+    constructor(options: WhatsAppPairingOptions);
+    start(): Promise<void>;
+    stop(): void;
+    getStatus(): WhatsAppPairingStatus;
+    private setStatus;
+}
+export declare function whatsappAuthExists(workspaceDir: string, accountId?: string): boolean;
+export declare function whatsappLogout(workspaceDir: string, accountId?: string): Promise<void>;
+//# sourceMappingURL=whatsapp-pairing.d.ts.map

package/dist/services/whatsapp-pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp-pairing.d.ts","sourceRoot":"","sources":["../../src/services/whatsapp-pairing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED,MAAM,MAAM,qBAAqB,GAC7B,MAAM,GACN,cAAc,GACd,gBAAgB,GAChB,WAAW,GACX,cAAc,GACd,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,aAAa,GAAG,iBAAiB,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;CAChD;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAA6E;IAC3F,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAK;IACrC,OAAO,CAAC,YAAY,CAA8C;gBAEtD,OAAO,EAAE,sBAAsB;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuG5B,IAAI,IAAI,IAAI;IAaZ,SAAS,IAAI,qBAAqB;IAIlC,OAAO,CAAC,SAAS;CAQlB;AAED,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,SAAY,GAAG,OAAO,CAGvF;AAED,wBAAsB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,SAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA8D/F"}

package/dist/setup-routes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * WhatsApp setup HTTP routes.
+ *
+ * Provides QR-code pairing, status, disconnect, and webhook endpoints:
+ *
+ *   GET  /api/whatsapp/webhook       Meta webhook verification
+ *   POST /api/whatsapp/webhook       Meta webhook event delivery
+ *   POST /api/whatsapp/pair          Start QR pairing session
+ *   GET  /api/whatsapp/status        Check connection / pairing status
+ *   POST /api/whatsapp/pair/stop     Stop active pairing session
+ *   POST /api/whatsapp/disconnect    Logout + remove auth state
+ *
+ * These routes are registered with `rawPath: true` so they mount at their
+ * legacy paths without the plugin-name prefix.
+ */
+import type { Route } from "@elizaos/core";
+/**
+ * Plugin routes for WhatsApp setup and webhooks.
+ * Registered with `rawPath: true` to preserve legacy `/api/whatsapp/*` paths.
+ */
+export declare const whatsappSetupRoutes: Route[];
+/**
+ * Stop all active pairing sessions. Called during shutdown cleanup.
+ */
+export declare function stopAllPairingSessions(): void;
+//# sourceMappingURL=setup-routes.d.ts.map

package/dist/setup-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-routes.d.ts","sourceRoot":"","sources":["../src/setup-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAiB,KAAK,EAA+B,MAAM,eAAe,CAAC;AA6XvF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,KAAK,EAyCtC,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAS7C"}

package/dist/types.d.ts

@@ -0,0 +1,370 @@
+export type WhatsAppConfig = CloudAPIConfig | BaileysConfig;
+export interface CloudAPIConfig {
+    authMethod?: "cloudapi";
+    accessToken: string;
+    phoneNumberId: string;
+    webhookVerifyToken?: string;
+    businessAccountId?: string;
+    apiVersion?: string;
+}
+export interface BaileysConfig {
+    authMethod?: "baileys";
+    authDir: string;
+    printQRInTerminal?: boolean;
+    sessionPath?: string;
+}
+/**
+ * Message types supported by WhatsApp Cloud API.
+ */
+export type WhatsAppMessageType = "text" | "template" | "image" | "audio" | "video" | "document" | "sticker" | "location" | "contacts" | "interactive" | "reaction";
+export interface WhatsAppMessage {
+    type: WhatsAppMessageType;
+    to: string;
+    content: string | WhatsAppTemplate | WhatsAppMediaMessage | WhatsAppInteractiveMessage | WhatsAppReactionMessage | WhatsAppLocationMessage;
+    replyToMessageId?: string;
+}
+export interface WhatsAppTemplate {
+    name: string;
+    language: {
+        code: string;
+    };
+    components?: Array<{
+        type: string;
+        parameters: Array<{
+            type: string;
+            text?: string;
+            image?: {
+                link: string;
+            };
+            document?: {
+                link: string;
+                filename?: string;
+            };
+            video?: {
+                link: string;
+            };
+        }>;
+    }>;
+}
+/**
+ * Media message content.
+ */
+export interface WhatsAppMediaMessage {
+    link?: string;
+    id?: string;
+    caption?: string;
+    filename?: string;
+    mimeType?: string;
+}
+/**
+ * Reaction message content.
+ */
+export interface WhatsAppReactionMessage {
+    messageId: string;
+    emoji: string;
+}
+/**
+ * Location message content.
+ */
+export interface WhatsAppLocationMessage {
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+}
+/**
+ * Interactive message types.
+ */
+export type InteractiveMessageType = "button" | "list" | "product" | "product_list" | "flow";
+/**
+ * Interactive message content.
+ */
+export interface WhatsAppInteractiveMessage {
+    type: InteractiveMessageType;
+    header?: {
+        type: "text" | "image" | "video" | "document";
+        text?: string;
+        image?: {
+            link: string;
+        };
+        video?: {
+            link: string;
+        };
+        document?: {
+            link: string;
+            filename?: string;
+        };
+    };
+    body: {
+        text: string;
+    };
+    footer?: {
+        text: string;
+    };
+    action: WhatsAppInteractiveAction;
+}
+/**
+ * Interactive action based on message type.
+ */
+export type WhatsAppInteractiveAction = WhatsAppButtonAction | WhatsAppListAction | WhatsAppFlowAction;
+/**
+ * Button action for interactive messages.
+ */
+export interface WhatsAppButtonAction {
+    buttons: Array<{
+        type: "reply";
+        reply: {
+            id: string;
+            title: string;
+        };
+    }>;
+}
+/**
+ * List action for interactive messages.
+ */
+export interface WhatsAppListAction {
+    button: string;
+    sections: Array<{
+        title?: string;
+        rows: Array<{
+            id: string;
+            title: string;
+            description?: string;
+        }>;
+    }>;
+}
+/**
+ * Flow action for interactive messages.
+ */
+export interface WhatsAppFlowAction {
+    name: "flow";
+    parameters: {
+        flow_message_version: string;
+        flow_token: string;
+        flow_id: string;
+        flow_cta: string;
+        flow_action: "navigate" | "data_exchange";
+        flow_action_payload?: {
+            screen: string;
+            data?: Record<string, unknown>;
+        };
+    };
+}
+export interface WhatsAppIncomingMessage {
+    from: string;
+    id: string;
+    timestamp: string;
+    text?: {
+        body: string;
+    };
+    image?: {
+        caption?: string;
+        mime_type: string;
+        sha256: string;
+        id: string;
+    };
+    video?: {
+        caption?: string;
+        mime_type: string;
+        sha256: string;
+        id: string;
+    };
+    audio?: {
+        mime_type: string;
+        sha256: string;
+        id: string;
+        voice?: boolean;
+    };
+    document?: {
+        caption?: string;
+        filename: string;
+        mime_type: string;
+        sha256: string;
+        id: string;
+    };
+    sticker?: {
+        mime_type: string;
+        sha256: string;
+        id: string;
+        animated?: boolean;
+    };
+    location?: {
+        latitude: number;
+        longitude: number;
+        name?: string;
+        address?: string;
+    };
+    contacts?: Array<{
+        name: {
+            formatted_name: string;
+            first_name?: string;
+            last_name?: string;
+        };
+        phones?: Array<{
+            phone: string;
+            type: string;
+        }>;
+    }>;
+    interactive?: {
+        type: "button_reply" | "list_reply" | "nfm_reply";
+        button_reply?: {
+            id: string;
+            title: string;
+        };
+        list_reply?: {
+            id: string;
+            title: string;
+            description?: string;
+        };
+        nfm_reply?: {
+            response_json: string;
+            body: string;
+            name: string;
+        };
+    };
+    reaction?: {
+        message_id: string;
+        emoji: string;
+    };
+    context?: {
+        from: string;
+        id: string;
+        referred_product?: {
+            catalog_id: string;
+            product_retailer_id: string;
+        };
+    };
+    type: string;
+}
+export interface WhatsAppStatusUpdate {
+    id: string;
+    status: "sent" | "delivered" | "read" | "failed";
+    timestamp: string;
+    recipient_id: string;
+    conversation?: {
+        id: string;
+        origin?: {
+            type: string;
+        };
+        expiration_timestamp?: string;
+    };
+    pricing?: {
+        billable: boolean;
+        pricing_model: string;
+        category: string;
+    };
+    errors?: Array<{
+        code: number;
+        title: string;
+        message?: string;
+        error_data?: {
+            details: string;
+        };
+    }>;
+}
+export interface WhatsAppWebhookEvent {
+    object: string;
+    entry: Array<{
+        id: string;
+        changes: Array<{
+            value: {
+                messaging_product: string;
+                metadata: {
+                    display_phone_number: string;
+                    phone_number_id: string;
+                };
+                statuses?: WhatsAppStatusUpdate[];
+                messages?: WhatsAppIncomingMessage[];
+                contacts?: Array<{
+                    profile: {
+                        name: string;
+                    };
+                    wa_id: string;
+                }>;
+                errors?: Array<{
+                    code: number;
+                    title: string;
+                    message?: string;
+                    error_data?: {
+                        details: string;
+                    };
+                }>;
+            };
+            field: string;
+        }>;
+    }>;
+}
+export interface WhatsAppMessageResponse {
+    messaging_product: string;
+    contacts: Array<{
+        input: string;
+        wa_id: string;
+    }>;
+    messages: Array<{
+        id: string;
+        message_status?: string;
+    }>;
+}
+export interface QRCodeData {
+    terminal: string;
+    dataURL: string;
+    raw: string;
+}
+export type ConnectionStatus = "connecting" | "open" | "close";
+export interface NormalizedMessage {
+    id: string;
+    from: string;
+    timestamp: number;
+    type: "text" | "image" | "audio" | "video" | "document";
+    content: string;
+    chatId?: string;
+    senderId?: string;
+    replyToId?: string;
+}
+/**
+ * Send reaction parameters.
+ */
+export interface SendReactionParams {
+    to: string;
+    messageId: string;
+    emoji: string;
+}
+/**
+ * Send reaction result.
+ */
+export interface SendReactionResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+}
+/**
+ * WhatsApp event types.
+ */
+export declare enum WhatsAppEventType {
+    MESSAGE_RECEIVED = "WHATSAPP_MESSAGE_RECEIVED",
+    MESSAGE_SENT = "WHATSAPP_MESSAGE_SENT",
+    MESSAGE_DELIVERED = "WHATSAPP_MESSAGE_DELIVERED",
+    MESSAGE_READ = "WHATSAPP_MESSAGE_READ",
+    MESSAGE_FAILED = "WHATSAPP_MESSAGE_FAILED",
+    REACTION_RECEIVED = "WHATSAPP_REACTION_RECEIVED",
+    REACTION_SENT = "WHATSAPP_REACTION_SENT",
+    INTERACTIVE_REPLY = "WHATSAPP_INTERACTIVE_REPLY",
+    WEBHOOK_VERIFIED = "WHATSAPP_WEBHOOK_VERIFIED"
+}
+/**
+ * Common WhatsApp reaction emojis.
+ */
+export declare const WHATSAPP_REACTIONS: {
+    readonly THUMBS_UP: "👍";
+    readonly THUMBS_DOWN: "👎";
+    readonly HEART: "❤️";
+    readonly LAUGHING: "😂";
+    readonly SURPRISED: "😮";
+    readonly SAD: "😢";
+    readonly PRAYING: "🙏";
+    readonly CLAPPING: "👏";
+    readonly FIRE: "🔥";
+    readonly CELEBRATION: "🎉";
+};
+export type WhatsAppReactionEmoji = (typeof WHATSAPP_REACTIONS)[keyof typeof WHATSAPP_REACTIONS];
+//# sourceMappingURL=types.d.ts.map