Chatwoot Integration

Status: Planned

MIDDAG Account will integrate with Chatwoot to provide customer context during live support conversations. Chatwoot is the chat tool (web widget and WhatsApp Business). The integration enriches support interactions with data from the plugin's domains.

What it will do

When a support agent opens a conversation in Chatwoot, a contact view panel will show relevant data pulled from MIDDAG Account:

• Organization -- company name, plan, billing entity.
• Active orders -- current orders and their status.
• Pending quotes -- open commercial proposals.
• Licenses -- active licenses and those approaching expiration.

This gives the support agent immediate context without switching between tools.

Architecture

The integration has two parts:

1. REST API endpoints (plugin side)

The plugin's existing REST API v1 provides the data. The NextJS portal assembles the contact view by calling these endpoints:

Data	Endpoint
Organization (name, plan)	GET /organizations/{id}
Active orders	GET /orders?org={id}
Pending quotes	GET /quotes?org={id}
Active/expiring licenses	GET /licenses?org={id}

2. Chatwoot PHP SDK (server-side sync)

The plugin will use the Chatwoot PHP SDK (ramiroestrella/chatwoot-php-sdk) for server-side operations:

• Create contacts in Chatwoot when organizations or collaborators are added.
• Update custom attributes on Chatwoot contacts when entitlement status changes.
• Associate conversations with organizations.

These operations are triggered by domain events in the plugin.

Authentication

The contact view uses a shared secret (not per-user JWT). Both the plugin and the portal use the same secret:

Variable	Description
CHATWOOT_CONTACT_VIEW_SECRET	Bearer token for contact view API

This secret is configured as an environment variable on both the WordPress and NextJS sides.

Setup plan

When the integration is implemented:

1. Install the Chatwoot PHP SDK via Composer.
2. Configure CHATWOOT_CONTACT_VIEW_SECRET in both environments.
3. Set up Chatwoot custom attributes to receive entitlement data.
4. Enable the contact view panel in the Chatwoot dashboard.

Scope

Feature	Planned
Contact view (read-only)	Yes
Contact sync (plugin to Chatwoot)	Yes
Conversation to Organization link	Yes
Ticket creation from portal	Future
Bidirectional ticket sync	Future