OpenBSP API: Self-Hostable WhatsApp and Instagram Business Messaging Platform

What OpenBSP API Is and the BSP Model

BSP stands for Business Solution Provider in the WhatsApp API ecosystem. Meta's WhatsApp Business API is not directly available to every developer: businesses typically connect through a BSP that handles the technical integration, compliance requirements and message routing. OpenBSP is an open-source alternative that lets a developer or organization become their own BSP rather than paying a commercial provider. It handles the Meta webhook integration, stores messages in a Supabase-backed PostgreSQL database, and exposes that data through a PostgREST API so any Supabase SDK or plain HTTP client can read and write messages using standard SQL-style operations. The platform supports both individual organizations running their own messaging and service providers who manage multiple client organizations on a single platform.

How Sending and Receiving Messages Works

The API is a PostgREST interface over the database tables, so sending a message means inserting a row into the messages table and receiving messages means registering a webhook that OpenBSP calls when a new row is inserted. To receive incoming messages, register a webhook endpoint:

curl -X POST 'https://nheelwshzbgenpavwhcy.supabase.co/rest/v1/webhooks' \
  -H 'apikey: <PUBLISHABLE_KEY>' -H 'api-key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization_id": "<ORG_ID>",
    "table_name": "messages",
    "operations": ["insert"],
    "url": "https://your-app.com/webhook"
  }'

OpenBSP then POSTs the complete messages table row to your URL whenever a new message arrives. To send a message, insert a row into the messages table:

curl -X POST 'https://nheelwshzbgenpavwhcy.supabase.co/rest/v1/messages' \
  -H 'apikey: <PUBLISHABLE_KEY>' -H 'api-key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization_id": "<ORG_ID>",
    "organization_address": "<PHONE_NUMBER_ID>",
    "conversation_address": "5491155551234",
    "service": "whatsapp",
    "content": {
      "version": "1",
      "type": "text",
      "kind": "text",
      "text": "Hello from OpenBSP!"
    }
  }'

The same insert works through any Supabase SDK by calling supabase.from("messages").insert(...) with the same fields.

Getting Started via the Hosted Version

The quickstart path in the README requires no self-hosting. Sign up at web.openbsp.dev, connect your WhatsApp number through the Integrations panel, and create an API key through Settings. The hosted version uses a Supabase project at nheelwshzbgenpavwhcy.supabase.co as its backend, and every API call sends two headers: apikey (the public Supabase key) and api-key (your secret key). Incoming messages fire webhooks to any URL you register, and outgoing messages dispatch to WhatsApp when you insert into the messages table. Instagram integration follows the same model. The README notes that connecting WhatsApp requires an account that has passed Meta's WhatsApp Business embedded signup, and connecting Instagram requires an Instagram Business account linked to a Facebook Page. App review by Meta may be required for production deployments depending on message volume and the nature of the use case.

n8n Integration, Claude Code Plugin and AI Agent Readiness

The repository ships an official n8n community node package (n8n-nodes-openbsp) that triggers on incoming messages and delivery status changes. Each event can carry the full conversation context, so an AI node in an n8n workflow can reply to a WhatsApp message with complete conversation history available. A companion Claude Code plugin is also included. It is installed with two commands:

/plugin marketplace add matiasbattocchia/open-bsp-api
/plugin install openbsp@matiasbattocchia-open-bsp-api

After signing in with Google, the plugin allows Claude to query contacts, conversations and templates via a query tool and reply to WhatsApp messages via a reply tool. Contacts must be explicitly added with /openbsp:config contacts add before they are forwarded to Claude, and the README describes this as a deliberate security default. The platform is positioned as AI-agent ready in part because the PostgREST interface makes it straightforward for any agent that can execute SQL-like queries to read and write conversation data.

Self-Hosting: Architecture and What It Requires

The self-hosted deployment requires Deno and a Supabase project. The application is built on Deno rather than Node.js, which affects the toolchain. The Supabase backend handles PostgreSQL storage, real-time subscriptions for webhook delivery, and the authentication layer. The repository includes a supabase/ directory with database migrations and an openapi.json describing the full API surface. An architecture diagram (architecture.png) in the repository illustrates how the Deno application sits between Meta's API and the Supabase database. The README points to MIGRATING_FROM_TWILIO.md and INTEGRATING.md for details on media, templates, locations and the credential capture workflow required when onboarding third-party clients as a service provider.

Limitations: WhatsApp Rules, the Unofficial API, and Licensing

The official WhatsApp Business API through Meta has restrictions: the 24-hour message window applies (businesses can only send free-form messages within 24 hours of a user-initiated message; outside that window, only pre-approved templates are permitted). OpenBSP does not change this constraint; your integration must work within Meta's rules regardless. The README mentions a WhatsApp Web integration that uses an unofficial API, listed separately from the official integration. Unofficial API usage violates WhatsApp's terms of service and risks account bans, so the README's mention of it does not mean it is a recommended production path. Slack integration is also listed in the README as a supported channel, with a slack-app-manifest.yaml included in the repository for configuring the Slack app, though the README does not detail its current feature parity with the WhatsApp channel. OpenBSP is licensed under the Unlicense, which places the code in the public domain: there are no restrictions on use, modification or redistribution, and no warranty is provided.

Editorial conclusion

Developers building AI-driven messaging workflows on WhatsApp or Instagram, and businesses that want to avoid vendor lock-in with commercial BSP services, will find OpenBSP useful as a platform foundation. Teams that want a managed service with zero infrastructure responsibility should start with the hosted version at web.openbsp.dev rather than a self-hosted deployment. Before self-hosting, read the Meta App Review requirements described in the app-review/ directory: connecting WhatsApp to a custom platform requires a Meta developer account, a verified business, and sometimes a formal app review depending on the message volume and use case.

Frequently asked questions

Official sources

1. Issues
2. License: Unlicense
3. matiasbattocchia/open-bsp-api on GitHub
4. Project website
5. README