OpenBSP API

Open-source WhatsApp Business Platform

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

OpenBSP 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.

User Interface

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

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

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

Description

OpenBSP 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 OpenBSP 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/open-bsp-api
/plugin install openbsp@matiasbattocchia-open-bsp-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:

/openbsp: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 web.openbsp.dev, the MCP
server URL is:

https://nheelwshzbgenpavwhcy.supabase.co/functions/v1/mcp

Authentication uses the Authorization: Bearer <API_KEY> header. Get it from
OpenBSP > 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": {
    "openbsp": {
      "url": "https://nheelwshzbgenpavwhcy.supabase.co/functions/v1/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

Available tools:

Demo

A managed instance is available at
web.openbsp.dev — 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 open-bsp-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

The repository also ships with a Release GitHub Actions workflow that performs
the same deployment from inside CI. The workflow is set to workflow_dispatch:
only — it does not run on push. This path is optional and useful if you
mirror this repo to another host (e.g. GitLab) or prefer keeping deployments
self-contained in GitHub Actions instead of relying on Supabase's integration.

Secrets

[!TIP]
Create the secrets at GitHub > Repository > Settings ⚙️ > Secrets and
variables *️⃣ > Actions > Secrets

• SUPABASE_ACCESS_TOKEN: A
  personal access token
• SUPABASE_DB_PASSWORD
• SUPABASE_SERVICE_ROLE_KEY: you can use a secret key instead of the legacy
  service role key

Variables

[!TIP]
Create the variables at GitHub > Repository > Settings ⚙️ > Secrets and
variables *️⃣ > Actions > Variables

• SUPABASE_PROJECT_ID
• SUPABASE_SESSION_POOLER_HOST: it is like
  aws-0-us-east-1.pooler.supabase.com

Release

[!TIP]
Go to GitHub > Repository > Actions ▶️ > Release

1. Click Run workflow

WhatsApp integration

To connect your OpenBSP 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.

There is quiet a Meta nomenclature of entities that you might want to get in
order to not to get lost in the platform.

• Business profile - This is the top-level entity, represents a business.
  Has users and assets.
• User - Real or system users. System users can have access tokens. Users
  belong to a business portfolio and can have assigned assets.
• Asset - WhatsApp accounts, Instagram accounts, Meta apps, among others.
  Assets belong to a business portfolio and are assigned to users.
• App - An asset that integrates Meta products such as the WhatsApp Cloud
  API.
• WhatsApp Business Account (WABA) - A WhatsApp account asset, can have many
  phone numbers.
• Phone number - A registered phone number within the WhatsApp Cloud API.
  Belongs to a WABA.

For more details, refer to
Cloud API overview.

1. Navigate to My Apps
2. Click Create App
3. Select the following options:
   • Use case: Other
   • App type: Business
4. Add the WhatsApp product to your app
5. Click Add API
6. Disregard the screen that appears next and proceed to the next step

1. Get into the Meta Business Suite. If you
   have multiple portfolios, select the one associated with your app
2. Go to Settings > Users > System users
3. Add an admin system user
4. Copy the ID → META_SYSTEM_USER_ID
5. Assign your app to the user with full control permissions
6. Generate a token with these permissions:
   • business_management
   • whatsapp_business_messaging
   • whatsapp_business_management
7. Copy the Access Token → META_SYSTEM_USER_ACCESS_TOKEN

For detailed instructions on system user setup, refer to the
WhatsApp Business Management API documentation.

1. Navigate to My Apps > App Dashboard
2. Go to App settings > Basic
3. Copy the following values:
   • App ID → META_APP_ID
   • App secret → META_APP_SECRET

Multiple Meta apps are supported by separating values with | (pipe)
characters. For example: META_APP_ID=app_id_1|app_id_2 and
META_APP_SECRET=app_secret_1|app_secret_2.

Part A

1. Within the App Dashboard
2. Go to WhatsApp > Configuration
3. Set the Callback URL to:
   https://{SUPABASE_PROJECT_ID}.supabase.co/functions/v1/whatsapp-webhook
4. Choose a secure token for WHATSAPP_VERIFY_TOKEN → Set it as the Verify
   token, but do not click Verify and save yet!
5. Ensure your Edge Functions environment variables are up-to-date
   • If you configured secrets directly in your Supabase dashboard, no further
     action is needed at this point
   • If you set secrets via GitHub Actions, re-run the Release action now to
     deploy them to your Edge Functions
6. Click Verify and save
7. Disregard the screen that appears next and proceed to the next step

Multiple Meta apps are supported by appending the query param
?app_id={META_APP_ID} to the callback URL. For example:
https://{SUPABASE_PROJECT_ID}.supabase.co/functions/v1/whatsapp-webhook?app_id=app_id_2.

Part B

1. Within the App Dashboard
2. Go to WhatsApp > Configuration
3. Subscribe to the following Webhook fields:
   • account_update
   • messages
   • history
   • smb_app_state_sync
   • smb_message_echoes

Optionally, test the configuration so far. In the messages subscription
section, click Test. You should see the request in Supabase > Project >
Edge Functions > Functions > whatsapp-webhook > Logs.

You might observe an error in the logs. This is an expected outcome at this
stage; the simple fact that a log entry appears confirms that the webhook is
successfully receiving events.

If you decide to add the test number,

1. Within the App Dashboard
2. Go to WhatsApp > API Setup
3. Click Generate access token (you can't use the one you got from step 2
   here)
4. Copy these values:
   • Phone number ID
   • WhatsApp Business Account ID
5. Select a recipient phone number
6. Send messages with the API > Send message

The test number doesn't seem to fully activate to receive messages unless you
send a test message at least once.

In order to add a production number,

1. Click Add phone number
2. Follow the flow
3. Navigate to
   WhatsApp Manager
4. Go to Account tools > Phone numbers
5. Copy these values:
   • Phone number ID
   • WhatsApp Business Account ID

For any number you add

Create an organization if you haven't done that already.

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

Note the organization ID.

Register the phone number with your organization in the system.

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.
OpenBSP 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.