Mass Communication Pipelines: High-Deliverability Messaging Infrastructure

SMSExpress API Integration (MEO)

Português | English

---

Licença / License

This project is licensed under the GNU GPLv3. See the LICENSE file for details.

---

Português

Esta é uma aplicação web interativa desenvolvida em Python com Streamlit, concebida como uma interface direta para o envio de mensagens em massa. A ferramenta integra-se com a API SMSExpress da MEO, utilizando autenticação por Utilizador, Palavra-passe e Entidade para processar um ficheiro CSV de contactos e disparar uma frase fixa personalizada para cada registo.

Requisito Obrigatório (Subscrição do Serviço)

Para conseguir utilizar esta aplicação, é estritamente necessário contratar previamente o serviço SMSExpress junto da MEO. A aplicação funciona como um integrador técnico da API oficial, pelo que necessitará das suas credenciais comerciais ativas para efetuar os envios.

Funcionalidades e Engenharia Central

UI/UX & Layout de Estado Inicial

Para proporcionar uma experiência profissional e limpa, o painel inclui um Modo de Estado Inicial que renderiza um wireframe estruturado com 3 colunas simétricas (Estabilidade do Pipeline, Validação do CSV e Rácio de Entregabilidade) juntamente com um cartão informativo que indica "Awaiting Execution...". A interface faz a transição para os resultados finais assim que o processamento do ficheiro é concluído.

Fluxo do Sistema

A aplicação foca-se na simplicidade e na execução direta do fluxo de envio através das seguintes camadas:

• Autenticação Nativa MEO: Integração direta através de pedidos HTTP seguros para a API SMSExpress utilizando as credenciais de Utilizador, Palavra-passe e Nome da Entidade inseridas na interface.
• Processamento de Ficheiros CSV: Leitura da lista de contactos diretamente de um ficheiro CSV carregado pelo utilizador na interface gráfica.
• Disparo Estruturado: Processamento sequencial que associa a frase configurada a cada um dos contactos importados, garantindo o envio correto de cada mensagem.

Pré-requisitos (Ubuntu)

Antes de começar, certifique-se de que tem as dependências essenciais do sistema instaladas:

sudo apt update
sudo apt install python3-pip python3-venv python3-tk git -y

1. Configurar o Ambiente Virtual (venv)

Execute estes comandos no terminal para clonar o repositório e preparar o ambiente:

# Criar o ambiente virtual
python3 -m venv venv

# Ativar o ambiente virtual
source venv/bin/activate

# Atualizar o gerenciador de pacotes e instalar os requisitos
pip install --upgrade pip
pip install -r requirements.txt

2. Executar a Aplicação em Desenvolvimento

Com o ambiente virtual (venv) ativo, inicie a aplicação:

Via Streamlit direto:

streamlit run app.py

Via Script Wrapper (utilizado pelo executável):

python run_app.py

3. Como Gerar o Executável (Ubuntu)

Para compilar esta aplicação num único executável nativo do Linux utilizando o PyInstaller, execute:

# Limpar caches de compilações anteriores
rm -rf build dist

# Compilar utilizando as configurações do ficheiro .spec
pyinstaller --clean app.spec

O binário final será gerado na pasta dist/. Para o iniciar, utilize:

./dist/app

---

English

This is an interactive web application built with Streamlit in Python, engineered as a straightforward messaging infrastructure for mass broadcasting. The tool integrates with MEO's SMSExpress API, utilizing direct authentication via User, Password, and Entity name to parse a contact list from a CSV file and dispatch a customized single-phrase message to each entry.

Mandatory Requirement (Service Subscription)

To use this application, it is strictly required to subscribe to the SMSExpress service directly with MEO first. The application acts as a technical integrator for the official API, meaning you will need your active commercial credentials to perform any broadcasts.

Features & Core Components

UI/UX & Initial State Layout

To deliver a clean user experience, the dashboard features an Initial State Mode that renders a structured wireframe with 3 symmetrical columns (Pipeline Stability, CSV Validation, and Deliverability Ratio) alongside an info card stating "Awaiting Execution...". It transitions to show the final results as soon as the file processing completes.

Workflow Execution

The app focuses on simplicity and reliable execution through the following core components:

• Native MEO Authentication: Driven directly via secure HTTP requests targeting the SMSExpress API endpoints using the User, Password, and Entity Name credentials typed into the UI.
• CSV File Processing: Parses the contact list straight from a user-uploaded CSV file directly inside the graphical interface.
• Structured Dispatch: A sequential processing engine that pairs the text phrase configured in the UI with each imported contact, ensuring accurate delivery.

Prerequisites (Ubuntu)

Before starting, ensure you have the essential system dependencies installed:

sudo apt update
sudo apt install python3-pip python3-venv python3-tk git -y

1. Setting Up the Virtual Environment (venv)

Run these commands in your terminal to set up the isolated project environment:

# Create the virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Upgrade pip and install requirements
pip install --upgrade pip
pip install -r requirements.txt

2. Running the Application in Development

With the virtual environment (venv) active, launch the dashboard:

Via direct Streamlit command:

streamlit run app.py

Via Wrapper Script (used by the executable):

python run_app.py

3. How to Generate the Executable (Ubuntu)

To compile the Streamlit application into a standalone Linux binary using PyInstaller, run:

# Clear previous build caches
rm -rf build dist

# Compile using the configuration from the .spec file
pyinstaller --clean app.spec

The final standalone binary will be generated inside the dist/ folder. To run it, use:

./dist/app