Integrations Overview

open-wa provides several ways to connect WhatsApp to other services. This guide helps you choose the right pattern for your use case.

Decision TreeCopy Anchor Link

Start HereCopy Anchor Link

Ask yourself:

1. Do you want to push events to an existing service? Use webhooks
2. Do you want a full inbox experience? Use Chatwoot or a CRM integration
3. Do you want to build custom logic? Use plugins or SocketClient
4. Do you want AI agents to control WhatsApp? Use MCP

Integration PatternsCopy Anchor Link

Data Flow: WhatsApp to Your ServiceCopy Anchor Link

Webhook FlowCopy Anchor Link

WhatsApp → open-wa → HTTP POST → Your Service

Messages and events are pushed to your endpoint as JSON payloads.

Plugin FlowCopy Anchor Link

WhatsApp → open-wa → Plugin → External API → Response

Plugins run inside the open-wa process and can call external services directly.

Chatwoot FlowCopy Anchor Link

WhatsApp → open-wa → Chatwoot API → Agent Inbox
Agent Reply → Chatwoot API → open-wa → WhatsApp

Bidirectional sync between WhatsApp and Chatwoot.

Contact and Message SyncCopy Anchor Link

How Contacts WorkCopy Anchor Link

When a message arrives, open-wa has access to:

• The sender's phone number (in message.from)
• The sender's display name (if available)
• Group membership information

Message SynchronizationCopy Anchor Link

• Incoming messages: Delivered to your integration in real-time
• Outgoing messages: Sent through your integration's API
• Message status: Delivery receipts, read receipts, and typing indicators

Security and ComplianceCopy Anchor Link

Data StorageCopy Anchor Link

• open-wa stores session data locally (authentication tokens, browser state)
• Messages are not stored by open-wa unless your integration saves them
• Media is decrypted on demand and not persisted

GDPR ConsiderationsCopy Anchor Link

• You are responsible for handling personal data in messages
• Consider implementing message retention policies
• Document what data your integration stores and why

Data RetentionCopy Anchor Link

Implement retention policies in your integration:

• Delete old messages after a set period
• Allow users to request data deletion
• Log only what is necessary for operation

Licensing for IntegrationsCopy Anchor Link

Licensing follows the methods and runtime behavior that an integration uses, not only its wrapper name. Each integration can call different parts of the API surface. Examine the pricing page and method reference before you promise a workflow to a customer.

Choosing Your PathCopy Anchor Link

For Quick IntegrationsCopy Anchor Link

Start with webhooks:

1. Add @open-wa/integration-webhook to plugins in wa.config.*
2. Point pluginConfig.webhook.url at your service endpoint
3. Handle incoming JSON payloads

For Custom LogicCopy Anchor Link

Use plugins:

1. Install the plugin SDK
2. Build your integration as a plugin
3. Load it via wa.config.js

For Full InboxCopy Anchor Link

Use Chatwoot:

1. Set up Chatwoot
2. Configure the Chatwoot plugin
3. Connect your WhatsApp session

For AI AgentsCopy Anchor Link

Use MCP:

1. Enable MCP in config with mcp: { enabled: true } and keep apiKey configured
2. Verify whether your installed build mounts the configured /mcp route
3. If /mcp is mounted, point your AI client at that endpoint so it can discover and call WhatsApp methods
4. If your build does not mount /mcp, give the agent the HTTP API docs or OpenAPI schema. You can also give it the Postman collection.

RelatedCopy Anchor Link

• Webhooks for business - Webhook setup and payloads
• MCP Integration - AI agent integration
• Chatwoot integration - Full inbox setup
• Plugin getting started - Build custom integrations