Integração Chatwoot

Status: Planejado

O MIDDAG Account será integrado ao Chatwoot para fornecer contexto do cliente durante conversas de suporte ao vivo. O Chatwoot é a ferramenta de chat (widget web e WhatsApp Business). A integração enriquece interações de suporte com dados dos domínios do plugin.

O que fará

Quando um agente de suporte abrir uma conversa no Chatwoot, um painel de visualização do contato exibirá dados relevantes extraídos do MIDDAG Account:

• Organização -- nome da empresa, plano, entidade de faturamento.
• Pedidos ativos -- pedidos atuais e seus status.
• Cotações pendentes -- propostas comerciais em aberto.
• Licenças -- licenças ativas e aquelas próximas da expiração.

Isso fornece ao agente de suporte contexto imediato sem alternar entre ferramentas.

Arquitetura

A integração possui duas partes:

1. Endpoints da REST API (lado do plugin)

A REST API v1 existente do plugin fornece os dados. O portal NextJS monta a visualização do contato chamando estes endpoints:

Dado	Endpoint
Organização (nome, plano)	GET /organizations/{id}
Pedidos ativos	GET /orders?org={id}
Cotações pendentes	GET /quotes?org={id}
Licenças ativas/expirando	GET /licenses?org={id}

2. SDK PHP do Chatwoot (sincronização server-side)

O plugin utilizará o SDK PHP do Chatwoot (ramiroestrella/chatwoot-php-sdk) para operações server-side:

• Criar contatos no Chatwoot quando organizações ou colaboradores são adicionados.
• Atualizar atributos customizados em contatos do Chatwoot quando o status de entitlement muda.
• Associar conversas a organizações.

Essas operações são acionadas por eventos de domínio no plugin.

Autenticação

A visualização do contato utiliza um segredo compartilhado (não JWT por usuário). Tanto o plugin quanto o portal utilizam o mesmo segredo:

Variável	Descrição
CHATWOOT_CONTACT_VIEW_SECRET	Token bearer para a API de visualização de contato

Este segredo é configurado como variável de ambiente tanto no lado WordPress quanto no NextJS.

Plano de configuração

Quando a integração for implementada:

1. Instalar o SDK PHP do Chatwoot via Composer.
2. Configurar CHATWOOT_CONTACT_VIEW_SECRET em ambos os ambientes.
3. Configurar atributos customizados do Chatwoot para receber dados de entitlement.
4. Habilitar o painel de visualização do contato no dashboard do Chatwoot.

Escopo

Funcionalidade	Planejado
Visualização de contato (somente leitura)	Sim
Sincronização de contato (plugin para Chatwoot)	Sim
Vínculo conversa-organização	Sim
Criação de ticket pelo portal	Futuro
Sincronização bidirecional de tickets	Futuro