open-bsp-api

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

Table of contents

• Quickstart
• User interface
• n8n
• Claude Code plugin
• Description

Platforms

• Hosted version
• Migrating from another platform
• Self-host deployment

Channels

• WhatsApp integration
• Instagram integration
• App review
• WhatsApp Web integration (unofficial API)
• Slack integration

Development

• Architecture
• Local development

Community

• Related open-source projects
• Acknowledgments
• Community

Quickstart

Receive and send WhatsApp messages in two steps. Before you start (once): sign up at web.openbsp.dev, connect your WhatsApp number (Integrations → WhatsApp), and create an API key (Settings → API Keys). Every call below sends two headers: apikey (the public Supabase key) and api-key (your secret key).

The API is PostgREST over the database, every table is an endpoint, so you can use plain REST or any Supabase SDK (JS, Python, Dart, …).

1. Receive messages — register a webhook; OpenBSP POSTs every new message to your URL:

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"
  }'

Your endpoint receives the messages table row as is, wrapped in a thin envelope:

{
  "entity": "messages",
  "action": "insert",
  "data": {
    // the row, exactly as stored
    "id": "9b2d…",
    "organization_id": "…",
    "conversation_id": "…",
    "external_id": "wamid.…",
    "service": "whatsapp",
    "organization_address": "<PHONE_NUMBER_ID>",
    "conversation_address": "5491155551234",
    "sender_address": "5491155551234",
    "content": {
      "version": "1",
      "type": "text",
      "kind": "text",
      "text": "Hi!"
    },
    "status": { "delivered": "2026-07-17T12:00:00Z" },
    "timestamp": "2026-07-17T12:00:00Z"
  }
}

Reply when data.sender_address is set — the contact authored it; it is null on your own outgoing rows, which the webhook also fires for (and, with "update", for status changes).

2. Send a message — insert a row; OpenBSP dispatches it to WhatsApp:

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 through the Supabase JS SDK:

import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  "https://nheelwshzbgenpavwhcy.supabase.co",
  "<PUBLISHABLE_KEY>",
  { global: { headers: { "api-key": "<API_KEY>" } } },
);

await supabase.from("messages").insert({
  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!",
  },
});

That's it. Media, templates, locations and the full message schema are covered in MIGRATING_FROM_TWILIO.md; third-party onboarding and credential capture in INTEGRATING.md.

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

n8n

Trigger on incoming messages and delivery-status changes. Every event can carry the full conversation context, so your AI node replies with history.

Send text, media, templates, locations, and contacts; read conversations, contacts, and templates.

🔌 OpenBSP n8n nodes — The official n8n community node package for OpenBSP.

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

Sign in with Google (same account as the web UI) — Claude walks you through it in the terminal:

/openbsp:config login

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.

Description

OpenBSP API is a multi-tenant platform that connects to the official WhatsApp and Instagram APIs 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 chat-completions and responses. 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.)

MCP server

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

For the hosted version at web.openbsp.dev, the MCP server URL is:

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

Two authentication methods:

• OAuth (humans, recommended) — just add the server URL; the MCP client discovers Supabase Auth's OAuth 2.1 server (dynamic client registration), opens the browser, and you sign in with your OpenBSP account and approve on the consent page. Access is scoped to your user via RLS.
• API key (servers and bots) — send an api-key: <API_KEY> header (Authorization: Bearer <API_KEY> also works). Get it from OpenBSP > Settings

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

Claude Code (then authenticate from the /mcp panel):

claude mcp add --transport http openbsp https://nheelwshzbgenpavwhcy.supabase.co/functions/v1/mcp

In Claude Desktop or ChatGPT, add it as a custom connector with the same URL — OAuth kicks in automatically. For headless clients, use an API key instead (claude_desktop_config.json shown as an example):

{
  "mcpServers": {
    "openbsp": {
      "url": "https://nheelwshzbgenpavwhcy.supabase.co/functions/v1/mcp",
      "headers": {
        "api-key": "<API_KEY>"
      }
    }
  }
}

Available tools:

Tool	Description
list_accounts	List connected WhatsApp accounts
list_conversations	Get recent active conversations
fetch_conversation	Fetch messages and service window status for a contact
search_contacts	Find contacts by name or phone number
send_message	Send a text or template message (enforces 24h service window)
list_templates	List available WhatsApp templates
fetch_template	Fetch details of a specific template

Hosted version

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.

The hosted instance is operated by Matías Battocchia, a registered Meta Tech Partner.

Quotas

Resource	Included
Messages	5,000 / month
Conversations	Unlimited
Storage	1 GB
AI Credits	$1.00 (one-time)

Need higher limits or a special feature? Get in touch.

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,