@flink-app/whatsapp-plugin

Bi-directional WhatsApp messaging plugin for Flink via the WhatsApp Cloud API. No external SDK — uses native fetch.

Features

• Auto-discovered WhatsappHandler files via Flink's compiler extension
• Route matching by message type, sender, text pattern, and connection
• Send text, templates, images, documents, interactive buttons/lists, locations, reactions
• Multi-connection support (multiple WhatsApp Business phone numbers)
• Webhook signature verification (HMAC-SHA256)
• Message status tracking (sent, delivered, read, failed)
• 24-hour conversation window awareness with template message support
• Markdown to WhatsApp formatting converter
• CLI tool for sending test messages

Quick Start

pnpm add @flink-app/whatsapp-plugin

// flink.config.js
const { compilerPlugin } = require("@flink-app/whatsapp-plugin/compiler");
module.exports = { compilerPlugins: [compilerPlugin()] };

// src/index.ts
import { whatsappPlugin } from "@flink-app/whatsapp-plugin";

new FlinkApp<Ctx>({
    plugins: [
        whatsappPlugin<Ctx>({
            connection: {
                accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
                phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
                verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
                appSecret: process.env.WHATSAPP_APP_SECRET!,
            },
        }),
    ],
});

// src/whatsapp-handlers/HandleText.ts
import { WhatsappHandler, WhatsappRouteProps } from "@flink-app/whatsapp-plugin";

export const Route: WhatsappRouteProps = { type: "text" };

const handler: WhatsappHandler<Ctx> = async ({ message, whatsapp }) => {
    await whatsapp.reply(message, `Echo: ${message.text}`);
};

export default handler;

Documentation

See the skill documentation for complete usage guide including routing, multi-connection setup, template messages, interactive messages, media handling, and more.

Meta App Setup

1. Create a Meta App at developers.facebook.com
2. Add the WhatsApp product
3. Configure webhook URL to https://your-domain.com/webhooks/whatsapp
4. Subscribe to the messages webhook field
5. Generate a permanent access token via a System User

CLI

pnpm exec flink-whatsapp send --token <token> --phone-id <id> --to <number> "Hello!"

License

MIT