bellinatiperez / mautic-plugin-evolution
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
README
Plugin oficial para integração entre Mautic e Evolution API, permitindo o envio de mensagens WhatsApp através de campanhas automatizadas.
📋 Índice
- Estado Atual do Plugin
- Requisitos do Sistema
- Instalação e Configuração
- Exemplos Práticos de Utilização
- Funcionalidades Implementadas
- Configurações Avançadas
- Solução de Problemas
- Estrutura do Plugin
- 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
-
Acesse o Painel Administrativo:
- Vá para
Configurações
→Plugins
- Encontre "Mautic Evolution Plugin"
- Clique em "Configurar"
- Vá para
-
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 | ❌ |
- 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
- 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" }'
- 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
-
Criar Nova Campanha:
- Vá para
Campanhas
→Nova Campanha
- Configure os critérios de entrada
- Vá para
-
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
-
Criar Template:
- Vá para
Evolution
→Templates
- Clique em "Novo Template"
- Vá para
-
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"] }
- 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 recebidaMESSAGES_UPDATE
: Atualização de status de mensagemSEND_MESSAGE
: Confirmação de envio
Status de Mensagem
PENDING
: Aguardando envioSENT
: EnviadaDELIVERY_ACK
: EntregueREAD
: LidaFAILED
: Falha no envio
Integração com Campanhas
Actions Disponíveis
-
Enviar Mensagem WhatsApp
- Mensagem de texto personalizada
- Suporte a variáveis de contato
- Configuração de campo de telefone
-
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:
- Instância WhatsApp Conectada:
curl -H "apikey: sua-key" \
https://sua-evolution-api.com/instance/connectionState/sua-instancia
- Formato do Número:
// Formato correto: +5511999999999 // Formato incorreto: 11999999999, (11) 99999-9999
- 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:
- URL do Webhook Acessível:
curl -X POST https://seu-mautic.com/webhook/evolution/receive \ -H "Content-Type: application/json" \ -d '{"test": true}'
- Configuração na Evolution API:
curl -H "apikey: sua-key" \
https://sua-evolution-api.com/webhook/find/sua-instancia
- 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:
- Permissões de Arquivo:
# Definir permissões corretas
chmod -R 755 plugins/MauticEvolutionBundle/
chown -R www-data:www-data plugins/MauticEvolutionBundle/
- 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
- Fork do Repositório
- Criar Branch de Feature:
git checkout -b feature/nova-funcionalidade
- Implementar Mudanças
- Executar Testes:
php bin/console mautic:test:evolution
- Commit e Push:
git commit -m "feat: adiciona nova funcionalidade"
git push origin feature/nova-funcionalidade
- 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