@copilotkit/channels-whatsapp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Atai Barkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @copilotkit/channels-whatsapp
+
+The **WhatsApp `PlatformAdapter`** for [`@copilotkit/channels`](../channels). It connects a
+WhatsApp Business number to any AG-UI agent: ingress via the Meta Cloud API webhook,
+egress as text or interactive messages rendered from the `@copilotkit/channels-ui` JSX
+vocabulary, opaque-id interactions, and HITL.
+
+You write your UI as JSX once (`@copilotkit/channels-ui`) and drive the bot with
+`@copilotkit/channels`; this package is the only one that talks to the WhatsApp Cloud API.
+
+## Install
+
+```sh
+pnpm add @copilotkit/channels @copilotkit/channels-whatsapp
+```
+
+## Quickstart
+
+```ts
+import { createBot } from "@copilotkit/channels";
+import {
+  whatsapp,
+  defaultWhatsAppContext,
+} from "@copilotkit/channels-whatsapp";
+
+const bot = createBot({
+  adapters: [
+    whatsapp({
+      accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+      phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
+      appSecret: process.env.WHATSAPP_APP_SECRET!,
+      verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
+      port: 3000,
+    }),
+  ],
+  agent: makeAgent(process.env.AGENT_URL!),
+  tools: [...appTools],
+  context: [...defaultWhatsAppContext, ...appContext],
+});
+
+// Every inbound text is for the bot — there is no @-mention concept on WhatsApp.
+bot.onMessage(async ({ thread }) => {
+  await thread.runAgent();
+});
+
+await bot.start();
+console.log("[whatsapp-bot] listening for webhooks");
+```
+
+`whatsapp(opts)` returns a `WhatsAppAdapter`. It starts an HTTP server on `port`
+(default 3000) that handles the Meta webhook: a `GET /webhook` verification
+handshake and signed `POST /webhook` event delivery. You must expose this port
+publicly (e.g. via ngrok) and register the URL + `verifyToken` in the Meta app
+configuration. See [`examples/whatsapp`](../../examples/whatsapp) for a complete
+setup walkthrough.
+
+### Required env
+
+| Var                        | Purpose                                                     |
+| -------------------------- | ----------------------------------------------------------- |
+| `WHATSAPP_ACCESS_TOKEN`    | Cloud API access token (Bearer), from Meta App → API setup. |
+| `WHATSAPP_PHONE_NUMBER_ID` | Business phone-number id that sends messages.               |
+| `WHATSAPP_APP_SECRET`      | App secret for `X-Hub-Signature-256` webhook validation.    |
+| `WHATSAPP_VERIFY_TOKEN`    | Token echoed during the GET verification handshake.         |
+
+## Capabilities
+
+| Capability          | Supported | Notes                                                          |
+| ------------------- | --------- | -------------------------------------------------------------- |
+| `supportsStreaming` | false     | WhatsApp messages are immutable; there is no edit-message API. |
+| `supportsModals`    | false     | No modal surface in the Cloud API.                             |
+| `supportsTyping`    | false     | No typing-indicator API for business accounts.                 |
+| `supportsReactions` | false     | No reaction API for business-sent messages.                    |
+
+Because messages are immutable, `thread.stream(...)` buffers the full iterable
+and sends it as a single message — there is no token-by-token streaming. Calls to
+`update` and `delete` are also no-ops (they post a new message instead, or silently
+drop). The `defaultWhatsAppContext` entry tells the agent about this constraint so
+it doesn't promise to "update this message."
+
+## `WhatsAppAdapterOptions` reference
+
+| Option                | Type                  | Default                        | Description                                                         |
+| --------------------- | --------------------- | ------------------------------ | ------------------------------------------------------------------- |
+| `accessToken`         | `string`              | required                       | Cloud API access token (Bearer).                                    |
+| `phoneNumberId`       | `string`              | required                       | Business phone-number id that sends messages.                       |
+| `appSecret`           | `string`              | required                       | App secret for `X-Hub-Signature-256` webhook validation.            |
+| `verifyToken`         | `string`              | required                       | Token echoed during the GET verification handshake.                 |
+| `port`                | `number`              | `3000`                         | HTTP server port.                                                   |
+| `path`                | `string`              | `"/webhook"`                   | Webhook path.                                                       |
+| `apiVersion`          | `string`              | `"v21.0"`                      | Graph API version.                                                  |
+| `graphBaseUrl`        | `string`              | `"https://graph.facebook.com"` | Graph API base origin. Overridable for tests.                       |
+| `interruptEventNames` | `ReadonlySet<string>` | `undefined`                    | Custom AG-UI event names treated as interrupts by the run renderer. |
+| `commandPrefix`       | `string`              | `"/"`                          | Prefix for leading-keyword command matching.                        |
+| `historyStore`        | `HistoryStore`        | `new InMemoryHistoryStore()`   | Pluggable conversation-history persistence.                         |
+| `files`               | `FileDeliveryConfig`  | `{}`                           | Inbound media handling configuration.                               |
+
+## JSX → WhatsApp rendering
+
+`renderWhatsAppMessage(ir)` lowers the `@copilotkit/channels-ui` IR to Cloud API
+payloads. The strategy:
+
+- **0 actions** → plain `text` message (markdown converted to WhatsApp formatting).
+- **1–3 button actions** → interactive `button` message (reply buttons).
+- **4–10 actions** → interactive `list` message (list picker).
+- **>10 actions** → numbered text menu (degraded fallback).
+
+Image nodes always emit their own `image` payload. Markdown is translated to
+WhatsApp formatting: `**bold**`, `_italic_`, `~~strikethrough~~`, `` `code` ``, and
+code blocks. Headings, tables, and clickable Markdown links are not supported on
+WhatsApp — links render as plain text.
+
+### Per-element budget
+
+WhatsApp caps interactive elements. Limits live in `WA_LIMITS`:
+
+| Limit               | Value | Element                                          |
+| ------------------- | ----- | ------------------------------------------------ |
+| `bodyText`          | 4096  | text message body chars                          |
+| `replyButtons`      | 3     | reply buttons in an interactive button message   |
+| `buttonTitle`       | 20    | reply-button title chars                         |
+| `interactiveBody`   | 1024  | interactive message body chars                   |
+| `interactiveHeader` | 60    | interactive header chars                         |
+| `interactiveFooter` | 60    | interactive footer chars                         |
+| `listRows`          | 10    | total rows across all sections in a list message |
+| `rowTitle`          | 24    | list-row title chars                             |
+| `rowDescription`    | 72    | list-row description chars                       |
+| `listButton`        | 20    | list open-button label chars                     |
+| `controlId`         | 256   | interactive control id chars                     |
+
+## Persistence
+
+### ActionStore (interaction rehydration)
+
+The engine's `ActionStore` (from `@copilotkit/channels`) stores the minted opaque ids
+that power `Button` / `Select` click handlers. By default it is in-memory: after a
+process restart, clicks on old interactive messages are acknowledged but ignored.
+For persistent interactions, pass a durable `ActionStore` to
+`createBot({ actionStore })`.
+
+### HistoryStore (conversation memory)
+
+Unlike Slack, WhatsApp exposes no readable message history. The adapter maintains
+its own `HistoryStore` and replays it into `agent.messages` on every turn. The
+default is `InMemoryHistoryStore` (up to 100 messages per conversation, drops
+oldest). Swap a durable backend by implementing the `HistoryStore` interface:
+
+```ts
+interface HistoryStore {
+  append(conversationKey: string, message: StoredMessage): Promise<void>;
+  read(conversationKey: string): Promise<StoredMessage[]>;
+}
+```
+
+Pass it as `historyStore` in the adapter options:
+
+```ts
+whatsapp({
+  // ...
+  historyStore: new MyRedisHistoryStore(),
+});
+```
+
+Without a durable `HistoryStore`, conversation history is lost on process restart.
+
+## Commands
+
+Commands are matched by a leading keyword in the message text (default prefix `/`).
+Register handlers with `bot.onCommand`:
+
+```ts
+bot.onCommand("status", async ({ thread, text }) => {
+  await thread.runAgent({ prompt: `Status check: ${text}` });
+});
+```
+
+Unlike Slack, WhatsApp has no native slash-command surface — commands are plain
+text messages that start with the prefix. They are NOT pre-filtered by the adapter
+(the engine matches them), and command messages are not persisted to the
+`HistoryStore` at ingress. Sent commands need to be serialized into the agent prompt
+explicitly if the agent needs to see them as history.
+
+## Built-ins
+
+- `defaultWhatsAppTools` — empty in v1 (WhatsApp exposes no user directory, so
+  there is no `lookup_user` equivalent). Spread into `tools` for future
+  compatibility.
+- `defaultWhatsAppContext` — two context entries: WhatsApp formatting rules
+  (bold/italic/code, no headings or clickable links) and delivery constraints (no
+  streaming, no message editing). Spread into `context`.
+- `whatsAppFormattingContext` / `whatsAppDeliveryContext` — the individual entries
+  if you need to compose them selectively.
+
+## Tool context
+
+Tools receive the single shared `BotToolContext` from `@copilotkit/channels`
+(`{ thread, message?, user?, signal?, platform }`) and reach WhatsApp power through
+capability-gated `thread` methods this adapter backs:
+
+- `thread.getMessages()` — the current conversation's message history (from
+  `HistoryStore`), each a `ThreadMessage` (`{ user?, text, ts?, isBot? }`).
+- `thread.postFile({ bytes, filename, title?, altText? })` — upload and send a
+  file (image → `image` payload; other → `document` payload via the media-upload
+  API).
+
+Note: `thread.lookupUser(query)` is a no-op on WhatsApp — the Cloud API exposes no
+user directory. It always returns `undefined`.
+
+## Running the demo
+
+This package is the **library**. A runnable end-to-end demo wiring everything
+against a real WhatsApp number lives in
+[`examples/whatsapp`](../../examples/whatsapp).
+
+## What's NOT in v1
+
+- No message editing or streaming (WhatsApp messages are immutable)
+- No proactive messaging outside the 24-hour customer-service window — the adapter
+  does not implement template-message sending; the bot can only reply within the
+  24-hour window opened by an inbound user message
+- No user directory (`lookupUser` always returns `undefined`)
+- No OAuth / multi-number install (single access token only)
+- Durable `ActionStore` and `HistoryStore` are in-memory by default; actions and
+  history expire on restart unless you provide durable implementations
+
+## Exports
+
+`whatsapp`, `WhatsAppAdapter`; `WhatsAppAdapterOptions`, `ReplyTarget`,
+`WhatsAppMessageRef` (types); `WhatsAppConversationStore`;
+`InMemoryHistoryStore`, `HistoryStore`, `StoredMessage` (types);
+`renderWhatsAppMessage`, `WhatsAppOutbound` (type); `WA_LIMITS`, `truncateText`,
+`clampArray`; `markdownToWhatsApp`; `decodeInteraction`, `conversationKeyOf`;
+`createRunRenderer`; `WhatsAppClient`, `DownloadedMedia` (type);
+`buildFileContentParts`, `AgentContentPart`, `FileDeliveryConfig` (types);
+`defaultWhatsAppTools`; `defaultWhatsAppContext`, `whatsAppFormattingContext`,
+`whatsAppDeliveryContext`.

package/dist/adapter.d.ts

@@ -0,0 +1,57 @@
+import type { PlatformAdapter, SurfaceCapabilities, IngressSink, InteractionEvent, RunRenderer, ConversationStore, UserQuery } from "@copilotkit/channels";
+import type { BotNode, MessageRef, PlatformUser, ThreadMessage } from "@copilotkit/channels-ui";
+import type { ReplyTarget, WhatsAppAdapterOptions } from "./types.js";
+import { WhatsAppClient } from "./client.js";
+import type { WhatsAppOutbound } from "./render/message.js";
+/** Factory mirroring `slack(opts)`. */
+export declare function whatsapp(opts: WhatsAppAdapterOptions): WhatsAppAdapter;
+export declare class WhatsAppAdapter implements PlatformAdapter {
+    private readonly opts;
+    readonly platform = "whatsapp";
+    readonly capabilities: SurfaceCapabilities;
+    readonly ackDeadlineMs = 5000;
+    readonly conversationStore: ConversationStore;
+    client: WhatsAppClient;
+    private readonly history;
+    private readonly server;
+    private readonly port;
+    private readonly commandPrefix;
+    private readonly interruptEventNames?;
+    private readonly waStore;
+    private sink;
+    constructor(opts: WhatsAppAdapterOptions);
+    start(sink: IngressSink): Promise<void>;
+    stop(): Promise<void>;
+    private onWebhook;
+    render(ir: BotNode[]): WhatsAppOutbound[];
+    post(target: ReplyTarget, ir: BotNode[]): Promise<MessageRef>;
+    update(ref: MessageRef, ir: BotNode[]): Promise<void>;
+    stream(target: ReplyTarget, chunks: AsyncIterable<string>): Promise<MessageRef>;
+    delete(_ref: MessageRef): Promise<void>;
+    createRunRenderer(target: ReplyTarget): RunRenderer;
+    decodeInteraction(raw: unknown): InteractionEvent | undefined;
+    lookupUser(_q: UserQuery): Promise<PlatformUser | undefined>;
+    getMessages(target: ReplyTarget): Promise<ThreadMessage[]>;
+    postFile(target: ReplyTarget, args: {
+        bytes: Uint8Array;
+        filename: string;
+        title?: string;
+        altText?: string;
+    }): Promise<{
+        ok: boolean;
+        fileId?: string;
+        error?: string;
+    }>;
+    /** Send agent/freeform text: convert markdown to WhatsApp formatting, split to ≤bodyText chunks. */
+    private sendText;
+    /**
+     * Record an outbound message in history keyed by its WhatsApp id, so a later
+     * quote-reply to it (the webhook sends only the quoted id) resolves to this
+     * text. Best-effort: no id or no text → skip. Errors are swallowed so a
+     * history write can never break a send.
+     */
+    private recordOutbound;
+}
+/** Split text into chunks no longer than `max` characters. */
+export declare function splitForWhatsApp(text: string, max: number): string[];
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

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

package/dist/adapter.js

@@ -0,0 +1,242 @@
+import { WhatsAppClient } from "./client.js";
+import { WhatsAppConversationStore } from "./conversation-store.js";
+import { InMemoryHistoryStore } from "./history-store.js";
+import { WebhookServer } from "./webhook-server.js";
+import { handleWebhookValue } from "./webhook-listener.js";
+import { createRunRenderer } from "./event-renderer.js";
+import { conversationKeyOf, decodeInteraction } from "./interaction.js";
+import { renderWhatsAppMessage } from "./render/message.js";
+import { markdownToWhatsApp } from "./markdown-to-wa.js";
+import { WA_LIMITS } from "./render/budget.js";
+/** Factory mirroring `slack(opts)`. */
+export function whatsapp(opts) {
+    return new WhatsAppAdapter(opts);
+}
+export class WhatsAppAdapter {
+    opts;
+    platform = "whatsapp";
+    capabilities = {
+        supportsModals: false,
+        supportsTyping: true,
+        supportsReactions: false,
+        supportsStreaming: false,
+    };
+    ackDeadlineMs = 5000;
+    conversationStore;
+    client;
+    history;
+    server;
+    port;
+    commandPrefix;
+    interruptEventNames;
+    waStore;
+    sink;
+    constructor(opts) {
+        this.opts = opts;
+        this.client = new WhatsAppClient({
+            accessToken: opts.accessToken,
+            phoneNumberId: opts.phoneNumberId,
+            apiVersion: opts.apiVersion,
+            graphBaseUrl: opts.graphBaseUrl,
+        });
+        this.history = opts.historyStore ?? new InMemoryHistoryStore();
+        this.waStore = new WhatsAppConversationStore({
+            historyStore: this.history,
+        });
+        this.conversationStore = this.waStore;
+        this.port = opts.port ?? 3000;
+        this.commandPrefix = opts.commandPrefix ?? "/";
+        this.interruptEventNames = opts.interruptEventNames;
+        this.server = new WebhookServer({
+            path: opts.path ?? "/webhook",
+            verifyToken: opts.verifyToken,
+            appSecret: opts.appSecret,
+            onEvent: (body) => this.onWebhook(body),
+        });
+    }
+    async start(sink) {
+        this.sink = sink;
+        await this.server.start(this.port);
+    }
+    async stop() {
+        await this.server.stop();
+    }
+    async onWebhook(body) {
+        if (!this.sink)
+            return;
+        for (const entry of body.entry ?? []) {
+            for (const change of entry.changes ?? []) {
+                if (!change.value)
+                    continue;
+                await handleWebhookValue(change.value, {
+                    sink: this.sink,
+                    history: this.history,
+                    phoneNumberId: this.opts.phoneNumberId,
+                    commandPrefix: this.commandPrefix,
+                    client: this.client,
+                    files: this.opts.files ?? {},
+                });
+            }
+        }
+    }
+    render(ir) {
+        return renderWhatsAppMessage(ir);
+    }
+    async post(target, ir) {
+        const payloads = this.render(ir);
+        let last = {
+            id: "",
+            to: target.to,
+            phoneNumberId: target.phoneNumberId,
+        };
+        for (const p of payloads) {
+            last = await this.client.sendMessage(target.to, p);
+            this.recordOutbound(target.to, outboundText(p), last);
+        }
+        return last;
+    }
+    async update(ref, ir) {
+        // WhatsApp can't edit messages; "update" posts a fresh message instead.
+        const r = ref;
+        await this.post({ to: r.to, phoneNumberId: r.phoneNumberId }, ir);
+    }
+    async stream(target, chunks) {
+        // No live streaming: buffer the whole iterable, then send once.
+        let text = "";
+        for await (const c of chunks)
+            text += c;
+        return this.sendText(target.to, text);
+    }
+    async delete(_ref) {
+        // WhatsApp has no message-delete API for business-sent messages; no-op.
+    }
+    createRunRenderer(target) {
+        // `sendText` records each outbound message in history (with its wamid), so
+        // the renderer doesn't need a separate `onAssistantText` history hook.
+        return createRunRenderer({
+            send: async (text) => {
+                await this.sendText(target.to, text);
+            },
+            interruptEventNames: this.interruptEventNames,
+        });
+    }
+    decodeInteraction(raw) {
+        const r = raw;
+        if (!r?.message || !r.replyTarget)
+            return undefined;
+        return decodeInteraction(r.message, r.replyTarget);
+    }
+    async lookupUser(_q) {
+        return undefined; // WhatsApp exposes no user directory.
+    }
+    async getMessages(target) {
+        return this.waStore.getMessages(target);
+    }
+    async postFile(target, args) {
+        try {
+            const mime = guessMime(args.filename);
+            const mediaId = await this.client.uploadMedia(args.bytes, mime, args.filename);
+            const payload = mime.startsWith("image/")
+                ? {
+                    type: "image",
+                    image: {
+                        id: mediaId,
+                        ...(args.altText ? { caption: args.altText } : {}),
+                    },
+                }
+                : {
+                    type: "document",
+                    document: {
+                        id: mediaId,
+                        filename: args.filename,
+                        ...(args.title ? { caption: args.title } : {}),
+                    },
+                };
+            const ref = await this.client.sendMessage(target.to, payload);
+            this.recordOutbound(target.to, args.title ??
+                args.altText ??
+                (mime.startsWith("image/") ? "[image]" : "[document]"), ref);
+            return { ok: true, fileId: mediaId };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    }
+    /** Send agent/freeform text: convert markdown to WhatsApp formatting, split to ≤bodyText chunks. */
+    async sendText(to, text) {
+        const body = markdownToWhatsApp(text);
+        if (!body)
+            return { id: "", to, phoneNumberId: this.opts.phoneNumberId };
+        const parts = splitForWhatsApp(body, WA_LIMITS.bodyText);
+        let last = {
+            id: "",
+            to,
+            phoneNumberId: this.opts.phoneNumberId,
+        };
+        for (const part of parts) {
+            last = await this.client.sendMessage(to, {
+                type: "text",
+                text: { body: part, preview_url: false },
+            });
+            this.recordOutbound(to, part, last);
+        }
+        return last;
+    }
+    /**
+     * Record an outbound message in history keyed by its WhatsApp id, so a later
+     * quote-reply to it (the webhook sends only the quoted id) resolves to this
+     * text. Best-effort: no id or no text → skip. Errors are swallowed so a
+     * history write can never break a send.
+     */
+    recordOutbound(to, text, ref) {
+        if (!ref.id || !text)
+            return;
+        void this.history
+            .append(conversationKeyOf(to), {
+            role: "assistant",
+            content: text,
+            ts: `${Date.now()}`,
+            id: ref.id,
+        })
+            .catch(() => { });
+    }
+}
+/** A short text representation of an outbound payload, for history/quote-resolution. */
+function outboundText(p) {
+    switch (p.type) {
+        case "text":
+            return p.text.body;
+        case "image":
+            return p.image.caption ?? "[image]";
+        case "document":
+            return p.document.caption ?? p.document.filename ?? "[document]";
+        case "interactive":
+            return p.interactive.body.text;
+    }
+}
+/** Split text into chunks no longer than `max` characters. */
+export function splitForWhatsApp(text, max) {
+    if (text.length <= max)
+        return [text];
+    const parts = [];
+    let i = 0;
+    while (i < text.length) {
+        parts.push(text.slice(i, i + max));
+        i += max;
+    }
+    return parts;
+}
+function guessMime(filename) {
+    const ext = filename.toLowerCase().split(".").pop() ?? "";
+    const map = {
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        pdf: "application/pdf",
+        txt: "text/plain",
+        csv: "text/csv",
+        json: "application/json",
+    };
+    return map[ext] ?? "application/octet-stream";
+}

package/dist/adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.test.d.ts.map

package/dist/adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.test.d.ts","sourceRoot":"","sources":["../src/adapter.test.ts"],"names":[],"mappings":""}