bellinatiperez/mautic-plugin-evolution

There is no license information available for the latest version (1.0.0) of this package.

Evolution API Integration

Installs: 27

Dependents: 1

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

Type:mautic-plugin

pkg:composer/bellinatiperez/mautic-plugin-evolution

1.0.0 2025-10-02 01:03 UTC

This package is auto-updated.

Last update: 2025-10-02 01:04:22 UTC


README

Plugin oficial para integração entre Mautic e Evolution API, permitindo o envio de mensagens WhatsApp através de campanhas automatizadas.

📋 Índice

  1. Estado Atual do Plugin
  2. Requisitos do Sistema
  3. Instalação e Configuração
  4. Exemplos Práticos de Utilização
  5. Funcionalidades Implementadas
  6. Configurações Avançadas
  7. Solução de Problemas
  8. Estrutura do Plugin
  9. Contribuição

🚀 Estado Atual do Plugin

Versão Atual

  • Versão: 1.0.0
  • Status: Estável
  • Última Atualização: 2024

Compatibilidade

  • Mautic: >= 6.0
  • PHP: >= 8.1
  • Evolution API: >= 1.5.0
  • Symfony: >= 6.0

Funcionalidades Implementadas ✅

  • Envio de Mensagens de Texto: Mensagens simples via WhatsApp
  • Envio de Mídia: Imagens, documentos e outros arquivos
  • Templates Dinâmicos: Sistema completo de templates com variáveis
  • Integração com Campanhas: Actions nativas no Campaign Builder
  • Webhooks: Recebimento de status de entrega e leitura
  • Sistema de Logs: Auditoria completa de mensagens enviadas
  • Interface Administrativa: Gerenciamento via painel do Mautic
  • Processamento de Status: Atualização automática de status de mensagens

Funcionalidades em Desenvolvimento 🚧

  • 🚧 Mensagens de Áudio: Envio de mensagens de voz
  • 🚧 Botões Interativos: Suporte a botões e menus
  • 🚧 Relatórios Avançados: Dashboard com métricas detalhadas

🔧 Requisitos do Sistema

Requisitos Obrigatórios

Servidor

  • PHP: 8.1 ou superior
  • Composer: Para gerenciamento de dependências
  • Extensões PHP:
    • curl
    • json
    • mbstring
    • openssl

Mautic

  • Versão: 6.0 ou superior
  • Permissões: Acesso de administrador para configuração
  • Banco de Dados: MySQL/MariaDB com suporte a UTF8MB4

Evolution API

  • Versão: 1.5.0 ou superior
  • Instância WhatsApp: Configurada e conectada
  • API Key: Válida e ativa
  • Webhook Endpoint: Acessível publicamente

Dependências PHP

{
    "php": ">=8.1",
    "guzzlehttp/guzzle": "^7.0",
    "symfony/http-foundation": "^6.0",
    "doctrine/orm": "^2.14"
}

📦 Instalação e Configuração

Passo 1: Instalação do Plugin

Opção A: Via Composer (Recomendado)

cd /caminho/para/mautic
composer require mautic/evolution-bundle

Opção B: Instalação Manual

# Clone o repositório na pasta de plugins
cd plugins/
git clone https://github.com/mautic/MauticEvolutionBundle.git

Passo 2: Ativação no Mautic

# Limpar cache do Mautic
php bin/console cache:clear

# Instalar assets do plugin
php bin/console mautic:assets:generate

# Atualizar schema do banco de dados
php bin/console doctrine:schema:update --force

Passo 3: Configuração da Integração

  1. Acesse o Painel Administrativo:

    • Vá para ConfiguraçõesPlugins
    • Encontre "Mautic Evolution Plugin"
    • Clique em "Configurar"
  2. Configure os Parâmetros Básicos:

Campo Descrição Obrigatório
URL da Evolution API URL base da sua instância Evolution API
API Key Chave de autenticação da Evolution API
Timeout Tempo limite para requisições (segundos)
Habilitar Webhooks Receber atualizações de status
Modo Debug Logs detalhados para desenvolvimento
  1. Exemplo de Configuração:
// Configuração via interface ou arquivo local.php
$config = [
    'evolution_api_url' => 'https://sua-evolution-api.com',
    'evolution_api_key' => 'sua-api-key-aqui',
    'evolution_timeout' => 30,
    'evolution_webhook_enabled' => true,
    'evolution_debug_mode' => false
];

Passo 4: Configuração de Webhooks

  1. Configure o Webhook na Evolution API:
curl -X POST "https://sua-evolution-api.com/external-webhook/create" \
  -H "Content-Type: application/json" \
  -H "apikey: sua-api-key" \
  -d '{
    "name": "Update event send",
    "url": "http://seu.mautic/webhook/evolution/receive",
    "enabled": true,
    "events": ["messages.update"],
    "description": "Webhook para testar evento MESSAGES_UPDATE"
  }'
  1. Teste a Conectividade:
# Verificar health check
curl https://seu-mautic.com/webhook/evolution/health

# Resposta esperada:
# {"status": "ok", "timestamp": "2024-01-01T12:00:00Z"}

💡 Exemplos Práticos de Utilização

1. Envio de Mensagem Simples em Campanha

  1. Criar Nova Campanha:

    • Vá para CampanhasNova Campanha
    • Configure os critérios de entrada
  2. Adicionar Action Evolution:

    • No Campaign Builder, clique em "+"
    • Selecione "Actions" → "Enviar Mensagem WhatsApp"
    • Configure a mensagem:
Olá {contactfield=firstname}!

Temos uma oferta especial para você:
🎯 {contactfield=custom_offer}

Válida até: {contactfield=offer_expiry}

Responda QUERO para mais informações!

2. Envio de Template Personalizado

  1. Criar Template:

    • Vá para EvolutionTemplates
    • Clique em "Novo Template"
  2. Configurar Template:

{
  "name": "Boas-vindas",
  "content": "Bem-vindo(a) {contactfield=firstname}!\n\nSua conta foi criada com sucesso.\nID: {contactfield=id}\nE-mail: {contactfield=email}",
  "variables": ["firstname", "id", "email"]
}
  1. Usar em Campanha:
    • Action: "Enviar Template WhatsApp"
    • Selecionar template criado
    • Configurar campo do telefone (padrão: mobile)

3. Envio de Mídia com Caption

// Exemplo via API Service
$evolutionApi = $this->get('mautic.evolution.api.service');

$result = $evolutionApi->sendMediaMessage(
    '+5511999999999',
    'https://exemplo.com/imagem.jpg',
    'Confira nossa nova promoção! 🎉',
    $contact,
    $event
);

4. Configuração de Webhook Personalizado

// No seu EventListener personalizado
public function onWebhookReceived(WebhookEvent $event): void
{
    $data = $event->getData();
    
    if ($data['event'] === 'MESSAGES_UPDATE') {
        $messageId = $data['data']['key']['id'];
        $status = $data['data']['status'];
        
        // Processar atualização de status
        $this->updateMessageStatus($messageId, $status);
    }
}

🔧 Funcionalidades Implementadas

Sistema de Mensagens

Tipos de Mensagem Suportados

  • Texto Simples: Mensagens de texto com suporte a emojis
  • Mídia: Imagens, documentos, áudios e vídeos
  • Templates: Mensagens padronizadas com variáveis dinâmicas

Variáveis Disponíveis

Todas as variáveis de contato do Mautic podem ser utilizadas:

  • {contactfield=firstname} - Nome
  • {contactfield=lastname} - Sobrenome
  • {contactfield=email} - E-mail
  • {contactfield=mobile} - Telefone
  • {contactfield=company} - Empresa
  • Campos personalizados: {contactfield=nome_do_campo}

Sistema de Templates

Gerenciamento de Templates

  • CRUD Completo: Criar, editar, visualizar e excluir templates
  • Preview: Visualização prévia com dados de exemplo
  • Clonagem: Duplicar templates existentes
  • Ativação/Desativação: Controle de status dos templates

Estrutura de Template

{
  "id": 1,
  "name": "Nome do Template",
  "content": "Conteúdo com {contactfield=variavel}",
  "isPublished": true,
  "dateAdded": "2024-01-01T12:00:00Z",
  "dateModified": "2024-01-01T12:00:00Z"
}

Sistema de Webhooks

Eventos Suportados

  • MESSAGES_UPSERT: Nova mensagem recebida
  • MESSAGES_UPDATE: Atualização de status de mensagem
  • SEND_MESSAGE: Confirmação de envio

Status de Mensagem

  • PENDING: Aguardando envio
  • SENT: Enviada
  • DELIVERY_ACK: Entregue
  • READ: Lida
  • FAILED: Falha no envio

Integração com Campanhas

Actions Disponíveis

  1. Enviar Mensagem WhatsApp

    • Mensagem de texto personalizada
    • Suporte a variáveis de contato
    • Configuração de campo de telefone
  2. Enviar Template WhatsApp

    • Seleção de template pré-configurado
    • Substituição automática de variáveis
    • Validação de campos obrigatórios

Configurações de Action

// Configuração de envio de mensagem
[
    'message' => 'Sua mensagem aqui com {contactfield=firstname}',
    'phone_field' => 'mobile', // Campo que contém o telefone
    'media_url' => '', // URL da mídia (opcional)
    'media_caption' => '' // Legenda da mídia (opcional)
]

⚙️ Configurações Avançadas

Configuração de Timeout

// config/local.php
return [
    'parameters' => [
        'evolution_timeout' => 60, // 60 segundos
        'evolution_retry_attempts' => 3,
        'evolution_retry_delay' => 5 // 5 segundos entre tentativas
    ]
];

Configuração de Logs

// Habilitar logs detalhados
'evolution_debug_mode' => true,
'evolution_log_level' => 'debug', // debug, info, warning, error
'evolution_log_file' => 'var/logs/evolution.log'

Configuração de Webhook Personalizado

// EventListener personalizado
class CustomWebhookListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            'mautic.evolution.webhook.received' => 'onWebhookReceived'
        ];
    }
    
    public function onWebhookReceived(WebhookEvent $event): void
    {
        // Sua lógica personalizada aqui
    }
}

🔍 Solução de Problemas

Problemas Comuns

1. Erro de Conexão com Evolution API

Sintoma: Connection timeout ou Connection refused

Soluções:

# Verificar conectividade
curl -I https://sua-evolution-api.com

# Testar API Key
curl -H "apikey: sua-key" https://sua-evolution-api.com/instance/connectionState/sua-instancia

# Verificar logs do Mautic
tail -f var/logs/mautic_prod.log | grep evolution

2. Mensagens Não Enviadas

Sintoma: Status permanece como PENDING

Verificações:

  1. Instância WhatsApp Conectada:
curl -H "apikey: sua-key" \
  https://sua-evolution-api.com/instance/connectionState/sua-instancia
  1. Formato do Número:
// Formato correto: +5511999999999
// Formato incorreto: 11999999999, (11) 99999-9999
  1. Logs de Erro:
# Verificar logs específicos do Evolution
grep -i "evolution" var/logs/mautic_prod.log

# Verificar logs de campanha
grep -i "campaign" var/logs/mautic_prod.log

3. Webhooks Não Funcionando

Sintoma: Status de mensagens não atualizam

Verificações:

  1. URL do Webhook Acessível:
curl -X POST https://seu-mautic.com/webhook/evolution/receive \
  -H "Content-Type: application/json" \
  -d '{"test": true}'
  1. Configuração na Evolution API:
curl -H "apikey: sua-key" \
  https://sua-evolution-api.com/webhook/find/sua-instancia
  1. Logs de Webhook:
tail -f var/logs/mautic_prod.log | grep webhook

4. Erro de Banco de Dados

Sintoma: Table 'evolution_messages' doesn't exist

Solução:

# Atualizar schema do banco
php bin/console doctrine:schema:update --force

# Verificar se as tabelas foram criadas
php bin/console doctrine:schema:validate

5. Problemas de Permissão

Sintoma: Access denied ou Permission denied

Verificações:

  1. Permissões de Arquivo:
# Definir permissões corretas
chmod -R 755 plugins/MauticEvolutionBundle/
chown -R www-data:www-data plugins/MauticEvolutionBundle/
  1. Permissões do Usuário no Mautic:
    • Verificar se o usuário tem permissão para gerenciar plugins
    • Verificar permissões de campanha

Comandos de Diagnóstico

Verificar Status do Plugin

# Listar plugins instalados
php bin/console mautic:plugins:list

# Verificar status específico
php bin/console mautic:plugins:install --plugin=MauticEvolutionBundle

Testar Conectividade

# Script de teste de conectividade
php bin/console mautic:evolution:test-connection

Limpar Cache

# Limpar todos os caches
php bin/console cache:clear

# Limpar cache específico do plugin
php bin/console cache:clear --env=prod

Logs Importantes

Localização dos Logs

  • Logs Gerais: var/logs/mautic_prod.log
  • Logs de Desenvolvimento: var/logs/mautic_dev.log
  • Logs de Campanha: Filtrar por campaign nos logs gerais

Exemplos de Logs

Envio Bem-sucedido:

[2024-01-01 12:00:00] mautic.INFO: Evolution message sent successfully 
{"messageId": "ABC123", "contact": 123, "phone": "+5511999999999"}

Erro de Envio:

[2024-01-01 12:00:00] mautic.ERROR: Evolution API error 
{"error": "Instance not connected", "phone": "+5511999999999"}

Webhook Recebido:

[2024-01-01 12:00:00] mautic.INFO: Evolution webhook received 
{"event": "MESSAGES_UPDATE", "messageId": "ABC123", "status": "READ"}

📁 Estrutura do Plugin

MauticEvolutionBundle/
├── Assets/                     # Recursos estáticos
│   ├── css/evolution.css      # Estilos do plugin
│   ├── js/evolution.js        # Scripts JavaScript
│   └── images/                # Imagens e ícones
├── Config/                     # Configurações
│   ├── config.php             # Configuração principal
│   └── services.php           # Definição de serviços
├── Controller/                 # Controladores
│   ├── TemplateController.php # Gerenciamento de templates
│   └── WebhookController.php  # Recebimento de webhooks
├── Entity/                     # Entidades do banco
│   ├── EvolutionMessage.php   # Entidade de mensagens
│   ├── EvolutionMessageRepository.php
│   ├── EvolutionTemplate.php  # Entidade de templates
│   └── EvolutionTemplateRepository.php
├── EventListener/              # Event Listeners
│   ├── CampaignSubscriber.php # Integração com campanhas
│   ├── LeadSubscriber.php     # Eventos de contatos
│   └── PluginSubscriber.php   # Eventos do plugin
├── Form/                       # Formulários
│   └── Type/                  # Tipos de formulário
│       ├── EvolutionConfigType.php
│       ├── SendMessageActionType.php
│       └── SendTemplateActionType.php
├── Integration/                # Integração principal
│   └── MauticEvolutionIntegration.php
├── Model/                      # Modelos de negócio
│   ├── MessageModel.php       # Modelo de mensagens
│   └── TemplateModel.php      # Modelo de templates
├── Service/                    # Serviços
│   ├── EvolutionApiService.php # Comunicação com API
│   ├── MessageService.php     # Processamento de mensagens
│   └── WebhookService.php     # Processamento de webhooks
├── Resources/                  # Recursos de visualização
│   ├── translations/          # Traduções
│   └── views/                 # Templates Twig
├── composer.json              # Dependências
├── MauticEvolutionBundle.php  # Classe principal
└── README.md                  # Esta documentação

🤝 Contribuição

Como Contribuir

  1. Fork do Repositório
  2. Criar Branch de Feature:
git checkout -b feature/nova-funcionalidade
  1. Implementar Mudanças
  2. Executar Testes:
php bin/console mautic:test:evolution
  1. Commit e Push:
git commit -m "feat: adiciona nova funcionalidade"
git push origin feature/nova-funcionalidade
  1. Criar Pull Request

Padrões de Código

  • PSR-12: Padrão de codificação PHP
  • Symfony Best Practices: Convenções do Symfony
  • Mautic Coding Standards: Padrões específicos do Mautic

Testes

# Executar todos os testes
php bin/console test

# Testes específicos do plugin
php bin/console test plugins/MauticEvolutionBundle/Tests/

**Desenvolvido com ❤️ pela equipe Soluções Digitais