Hub de Integrações flwchat

Inspirado no construtor multi-action da Pluga, entregue agora como receitas simples (gatilho → ação) com tratamento nativo das regras da API oficial do WhatsApp.

1. Modelo conceitual

App: sistema externo (Perseus, Bigin, Sponte, flwchat).
Conexão: credencial de um app para um workspace (OAuth tokens, API keys).
Gatilho: evento vindo do app externo via webhook ou polling.
Ação: operação no flwchat (mensagem livre / template / criar contato / mover etapa).
Receita: {gatilho, ação, mapeamento, filtros}.
Template: HSM aprovado + snippets de mensagens livres.

2. Camadas técnicas

Connector SDK interno com interface uniforme: authenticate(), listTriggers(), listActions(), subscribeWebhook(), poll(), executeAction(). Cada sistema implementa um adaptador.
Engine de execução: fila de eventos → resolve mapeamento → chama ação → registra log/retry com backoff exponencial.
Gestor de tokens: refresh automático (OAuth Bigin), rotação e alerta de expiração.
Camada WhatsApp: decide automaticamente entre mensagem livre (janela 24h aberta) e template HSM (conversa nova). Templates sincronizam status com BSP.
Webhooks de entrada: rota pública /api/public/webhooks/$provider com verificação de assinatura por provedor.

3. Estudo das APIs

Perseus

Gestão Escolar

Token

Conecte o Perseus ao flwchat para notificar matrículas, mensalidades, presenças e respostas dos alunos via WhatsApp.

Gatilhos

· Nova matrícula
· Mensalidade vencida
· Falta registrada

Ações

· Criar/atualizar aluno
· Registrar ocorrência

Documentação oficial →

Bigin

CRM

OAuth 2.0

OAuth 2.0 com Zoho Bigin. Sincronize leads, deals e estágios do pipeline com conversas no WhatsApp.

Gatilhos

· Novo contato
· Deal mudou de estágio
· Deal ganho

Ações

· Criar/atualizar contato
· Mover deal de estágio
· Registrar atividade

Documentação oficial →

Sponte

ERP

Token

Integração com Sponte por token de aplicação. Notifique leads, matrículas, contratos e financeiro via WhatsApp.

Gatilhos

· Novo lead
· Contrato gerado
· Financeiro vencido

Ações

· Criar lead
· Atualizar matrícula
· Registrar contato

Documentação oficial →

ClaudiaCRM

CRM

Token

CRM com Clientes, Propostas, Contratos (assinatura digital via Docsales), Cobranças (Asaas) e Calculadoras de Preço. Já possui camada flwchat nativa para envio via WhatsApp.

Gatilhos

· Proposta enviada
· Proposta aceita
· Proposta recusada
· Contrato pronto para assinatura
· Contrato assinado
· Cobrança vencida

Ações

· Criar/atualizar cliente
· Criar proposta
· Registrar interação
· Reenviar contrato

Documentação oficial →

4. Templates WhatsApp

Template HSM (obrigatório fora da janela 24h): nome, idioma, categoria (MARKETING / UTILITY / AUTHENTICATION), corpo com placeholders {{1}}, botões opcionais e status de aprovação.

Mensagem livre (dentro da janela 24h): texto + mídia + botões interativos, com mapeamento de variáveis do gatilho.

O construtor escolhe o modo automaticamente conforme o gatilho. Ex.: “Nova matrícula” → conversa nova → exige HSM; “Resposta de aluno” → janela aberta → mensagem livre.

5. Mapeamento de variáveis

Cada gatilho expõe um schema de campos (ex.: Perseus “Nova matrícula” → aluno.nome, aluno.telefone, curso.nome, responsavel.nome). No construtor esses campos viram chips arrastáveis que preenchem {{1}}, {{2}} do template ou variáveis da mensagem livre.

6. Diagrama de arquitetura

7. Roadmap após esta entrega

Piloto bidirecional com ClaudiaCRM aproveitando sua camada flwchat nativa — caminho mais curto para a primeira integração end-to-end.
Implementar adaptador real do Bigin (OAuth + webhooks) como piloto.
Adicionar Perseus (token simples, polling + webhooks onde houver).
Adicionar Sponte.
Evoluir o construtor de receita simples para multi-action (canvas com vários passos, estilo novo Pluga).
Sincronização real de templates com BSP e fila de aprovação.