wakit API

Open-source WhatsApp Business Platform

Self-hostable, multi-tenant, AI-agent ready. Built with Deno 🦕 and Postgres 🐘, powered by Supabase ⚡

wakit is designed for both individual businesses and service providers. You can use it to manage your own WhatsApp messaging, or leverage its features to become a Meta Business Partner and offer WhatsApp messaging services to other organizations.

🚀 Powering production-grade AI agents at Mirlo.com

[!NOTE] This project is now backed by Mirlo.com, where I work, and is undergoing a rebranding. The project name is changing from OpenBSP to wakit.

User Interface

For a complete web-based interface to manage conversations check out the companion project:

🖥️ wakit UI — A modern, responsive web interface built with React and Tailwind.

https://github.com/user-attachments/assets/1ef30dde-9de1-4f5a-856a-db34ca2e3063

Description

wakit API is a multi-tenant platform that connects to the official WhatsApp API to receive and send messages, storing them in a Supabase-backed database.

Core features

• 🤝 Meta Business Partner ready: Built to facilitate the transition to an official solution provider.
• 🔗 WhatsApp account Coexistence: Connect existing WhatsApp Business accounts via Embedded Signup.
• 🏢 Multi-tenant architecture: Native support for multiple organizations with isolated environments.
• 🔌 External integration: Seamlessly connect with external services using webhooks and the API.

AI agents

Create lightweight agents or connect to external, more advanced agents using different protocols like a2a and chat-completions. Lightweight agents can use built-in tools:

• MCP client
• SQL client
• HTTP client
• Calculator

[!IMPORTANT] This project prioritizes a decoupled architecture between communication and agent logic. Advanced agents built with frameworks like the OpenAI SDK or Google ADK should be deployed as external services.

Media processing

Interpret and extract information from media and document files, including:

• Audio
• Images
• Video
• PDF
• Other text-based documents (CSV, HTML, TXT, etc.)

Claude Code plugin

The wakit plugin gives Claude Code full API access and optionally bridges WhatsApp messages in real-time. Claude can query contacts, conversations, templates, and more via the query tool, and reply to WhatsApp messages via the reply tool.

Install the plugin:

/plugin marketplace add matiasbattocchia/wakit-api
/plugin install wakit@matiasbattocchia-wakit-api

On first run, a browser opens for Google sign-in (same account as the web UI). Then configure allowed contacts for the WhatsApp channel:

/wakit:config contacts add 5491155551234

No contacts are forwarded until explicitly added (secure by default). API access works regardless of channel configuration. See plugin/README.md for full documentation.

MCP server

The mcp Edge Function exposes an MCP server over SSE, giving agentic access to the WhatsApp API from clients like Claude Desktop or other agent platforms.

For the hosted version at app.wakit.ai, the MCP server URL is:

https://api.wakit.ai/functions/v1/mcp

Authentication uses the Authorization: Bearer <API_KEY> header. Get it from wakit > Settings > API Keys.

Optionally, Allowed-Contacts and Allowed-Accounts headers restrict which phone numbers the key can access.

Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "wakit": {
      "url": "https://api.wakit.ai/functions/v1/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

Available tools:

Demo

A managed instance is available at app.wakit.ai — same codebase as this repo, running on Supabase. Sign up with a Google or GitHub account.

Quotas

AI Credits apply only when agents use the built-in LLM gateway. Configuring an agent with your own provider API key (AgentExtra.api_key) bypasses credit consumption.

Data portability

Your data is yours. You can export your organization's data from the hosted instance and load it into a self-hosted deployment — both run the same schema, and all data is scoped by organization with no cross-org dependencies.

Self-host deployment

[!NOTE] Deploy your own instance in under 15 minutes — no local environment required.

1. Fork this repo (1 min)
2. Create a Supabase project (5 min)
3. Connect the project to your fork via the Supabase GitHub Integration (5 min)

You are live! 🚀 Pushes to your default branch will automatically deploy database migrations and Edge Functions.

Connect via Supabase GitHub Integration

In the Supabase Dashboard:

1. Go to Project Settings > Integrations
2. Under GitHub Integration, click Authorize GitHub
3. On the GitHub authorization page, click Authorize Supabase
4. Back on the Integrations page, choose your forked wakit-api repository
5. Set the Working directory to . (the supabase/ folder lives at the repo root)
6. Set the Production branch to main
7. Configure the remaining options as needed
8. Click Enable integration

WhatsApp integration

To connect your wakit project to the WhatsApp API, you'll need to setup a Meta App with the WhatsApp product and configure the following Edge Functions secrets. You can set these up in two ways:

• Direct configuration: Add them directly in your Supabase dashboard at Supabase > Project > Edge Functions > Secrets.
• GitHub Actions: Set them as GitHub Actions secrets in your repository settings and re-run the Release action to automatically deploy them.

Secrets

• META_SYSTEM_USER_ID
• META_SYSTEM_USER_ACCESS_TOKEN
• META_APP_ID
• META_APP_SECRET
• WHATSAPP_VERIFY_TOKEN

Follow these steps to obtain the required credentials.

insert into public.organizations (name, extra) values
  ('Default', '{ "response_delay_seconds": 0 }')
;

insert into public.organizations_addresses (address, organization_id, service, extra) values
  ('<Phone number ID>', '<Organization ID>', 'whatsapp', '{ "waba_id": "<WhatsApp Business Account ID>", "phone_number": "<Phone number>" }')
;

Architecture

New to Supabase? In one sentence: it's a hosted Postgres platform that auto-exposes your tables over a REST and realtime API, runs Deno-based Edge Functions for server-side logic, and handles auth and file storage on top. wakit leans heavily on those primitives — most business logic lives as SQL triggers and Edge Functions, and clients (the web UI, the Claude Code plugin, custom integrations) talk to Postgres directly through a Supabase client library rather than through a separate backend layer.

In the image, green boxes are external services, red are Edge Functions and blue, database tables. White boxes are clients.

The system uses a reactive, function-based architecture:

1. A request from the WhatsApp API is received by the whatsapp-webhook function.
2. whatsapp-webhook processes the incoming message and stores it in the messages table.
3. An insert trigger on the messages table forwards the message to the agent-client function (incoming trigger).
4. agent-client builds the conversation context and sends a request to an agent API using the Chat Completions format.
5. agent-client waits for the agent's response and saves it back to the messages table.
6. An outgoing trigger on the messages table forwards the new message to the whatsapp-dispatcher function.
7. whatsapp-dispatcher processes the message and sends a request to the WhatsApp API to deliver it.

This event-driven flow ensures that each component is decoupled and scalable.

Edge Functions

WhatsApp

• whatsapp-webhook: Handles incoming webhook events from the WhatsApp Cloud API.
• whatsapp-dispatcher: Sends outbound messages to the WhatsApp Cloud API.
• whatsapp-manager: Integrates with the WhatsApp Business Management API for business and phone number management.

Agent

• agent-client: Orchestrates agent interactions, builds conversation context, and communicates with external agent APIs over Chat Completions or A2A protocols.

Database models

• users: Registered user in the application (mapped to Supabase Auth).
• organizations: Tenant entity; holds organization metadata.
• organizations_addresses: An organization's connected addresses per service — e.g. a WhatsApp phone number. Belongs to an organization.
• contacts: People associated with an organization — the address-book entry that groups one or more addresses under a name.
• contacts_addresses: Addresses a contact can be reached at (e.g. a phone number for WhatsApp). An address can exist unlinked to any contact, so addresses and contacts have independent lifecycles — the sync triggers in this table manage linking/unlinking and orphan cleanup.
• conversations: A conversation between an organization_address and a contact_address (or group_address) for a given service; belongs to an organization.
• messages: Messages within a conversation; carry direction, type, payload, status, and timestamps.
• agents: Human or AI agents for an organization; optionally linked to an auth user.
• api_keys: API access keys scoped to an organization.
• webhooks: Outbound webhook subscriptions per organization.
• quick_replies: Reusable response snippets scoped to an organization.
• logs: Application-level log entries (errors, warnings) written by Edge Functions.

Configuration

Organizations

export type OrganizationExtra = {
  response_delay_seconds?: number; // default: 3
  welcome_message?: string;
  authorized_contacts_only?: boolean;
  default_agent_id?: string;
  media_preprocessing?: {
    mode?: "active" | "inactive";
    model?: "gemini-2.5-pro" | "gemini-2.5-flash"; // default: gemini-2.5-flash
    api_key: string; // default GOOGLE_API_KEY env var
    language?: string;
    extra_prompt?: string;
  };
  error_messages_direction?: "internal" | "outgoing";
};

Agents

The spirit of this project has been to equiparate the experience of human and AI agents.

Human

Roles and privileges

• Owner — full control: manage organizations, manage integrations, invite/remove anyone
• Admin — operational control: manage conversations, create AI agents
• Member — standard usage: create conversations, use the chat features

AI

export type AgentExtra = {
  mode?: "active" | "draft" | "inactive";
  description?: string;
  api_url?: "openai" | "anthropic" | "google" | "groq" | string; // default: openai
  api_key?: string; // default: provider env var, i.e. OPENAI_API_KEY
  model?: string; // default: gpt-5-mini
  // TODO: Add responses (openai), messages (anthropic), generate-content (gemini).
  protocol?: "chat_completions" | "a2a"; // default: chat_completions
  assistant_id?: string;
  max_messages?: number;
  temperature?: number;
  max_tokens?: number;
  thinking?: "minimal" | "low" | "medium" | "high";
  instructions?: string;
  send_inline_files_up_to_size_mb?: number;
  tools?: ToolConfig[];
};

Local development

Requires Node 🐢 and Docker 🐋.

Database

npx supabase start

After editing the schema files, generate a migration

npx supabase db diff -f <migration_name>

Apply the migration to the local database

npx supabase migration up

Finally, update the types

npx supabase gen types typescript --local > supabase/functions/_shared/db_types.ts

Edge Functions

npx supabase functions serve

REST API docs

Fetch the OpenAPI spec from PostgREST (requires the service role key):

curl "https://<project-id>.supabase.co/rest/v1/" -H "apikey: <service_role_key>" > openapi.json

Acknowledgments

• @diegoparma — for years of feedback, design input, and being one of the project's earliest power users.
• @rolox05 — first UI, PoC and kickstart partner.

Community

Questions, ideas, or feedback? Join our WhatsApp Community or open an issue. We'd love to hear from you.