matrix-wacloud 0.1.0__tar.gz

matrix_wacloud-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allan dos Santos Magalhães de Sousa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matrix_wacloud-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: matrix-wacloud
+Version: 0.1.0
+Summary: Matrix application service that forwards room messages to WhatsApp via the official WhatsApp Business Cloud API (template messages, opt-in subscribers, delivery/read receipts).
+Author: Allan dos Santos Magalhães de Sousa
+License-Expression: MIT
+Project-URL: Source, https://github.com/allanmagalhaes/matrix-wacloud
+Keywords: matrix,whatsapp,bridge,appservice,notifications,cloud-api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mautrix<0.22,>=0.20
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-aiohttp>=1.0; extra == "dev"
+Dynamic: license-file
+
+# matrix-wacloud
+
+*Matrix application service that forwards messages posted in Matrix rooms to WhatsApp subscribers through the **official WhatsApp Business Cloud API** — template messages, opt-in subscriber lists, delivery/read receipts and opt-out handling.*
+
+Conector (*bridge*) de notificação entre o [Matrix](https://matrix.org) e a WhatsApp Business Cloud API, desenvolvido como Trabalho de Conclusão de Curso do Bacharelado em Sistemas de Informação da UNIRIO.
+
+Diferente de pontes como o mautrix-whatsapp, que emulam o WhatsApp Web num número pessoal, este pacote usa somente a API oficial da Meta. Por isso ele **não** replica conversas: ele converte avisos publicados numa sala Matrix em **mensagens por template** para os inscritos daquela sala. Essa é a forma permitida pela Meta para mensagens iniciadas pela organização.
+
+```
+ sala Matrix ──(appservice)──▶ matrix-wacloud ──(Cloud API)──▶ WhatsApp dos inscritos
+      ▲                              │  ▲
+      └──── !wa status ◀── SQLite ◀──┘  └──(webhooks: sent/delivered/read/failed)── Meta
+```
+
+## Funcionalidades
+
+- Vínculo de salas Matrix a um template aprovado (`!wa vincular`).
+- Inscritos por sala, com registro da origem e da data do consentimento (LGPD). Importação de CSV, inclusive do Google Forms.
+- Envio concorrente com repetição automática nos erros temporários da API.
+- Recepção dos webhooks da Meta com **validação da assinatura `X-Hub-Signature-256`**.
+- Acompanhamento de entregas e leituras por aviso (`!wa status`).
+- Descadastro: o inscrito responde **SAIR** no WhatsApp e é removido de todas as salas.
+- Números mascarados nos logs e nas mensagens do bot.
+
+## Instalação
+
+```bash
+pip install matrix-wacloud
+```
+
+Requer Python 3.10+ e um homeserver Matrix onde você possa registrar um *application service* (por exemplo, Synapse).
+
+## Configuração rápida
+
+1. Copie `config.example.yaml` para `config.yaml` e `.env.example` para `.env`. Os segredos ficam no `.env`; o YAML os referencia como `${NOME}`.
+2. Gere os tokens do appservice e cole no `.env`:
+   ```bash
+   matrix-wacloud generate-tokens
+   ```
+3. Preencha no `.env` os dados do painel da Meta: `WA_PHONE_NUMBER_ID`, `WA_ACCESS_TOKEN` (token permanente), `WA_APP_SECRET` (Configurações do app → Básico → Chave secreta) e `WA_VERIFY_TOKEN` (uma senha inventada por você).
+4. Gere o registro e adicione-o ao homeserver (`app_service_config_files` no `homeserver.yaml`):
+   ```bash
+   matrix-wacloud generate-registration -c config.yaml -o registration.yaml
+   ```
+5. Teste as credenciais da Meta sem passar pelo Matrix:
+   ```bash
+   matrix-wacloud send-test -c config.yaml --to 5521999999999
+   ```
+6. Execute:
+   ```bash
+   matrix-wacloud run -c config.yaml
+   ```
+7. No painel da Meta (WhatsApp → Configuração → Webhooks), use `https://SEU_DOMINIO/whatsapp/webhook` como URL de callback, informe o mesmo `WA_VERIFY_TOKEN` e assine o campo **messages**. Ative também "Assinar webhooks" na conta do número que envia.
+
+## Uso na sala
+
+Convide `@wacloud:SEU_DOMINIO` para uma sala. Só administradores listados em `admins` podem convidar, comandar e disparar avisos.
+
+| Comando | Efeito |
+|---|---|
+| `!wa vincular <rótulo> [template] [idioma]` | liga a sala ao WhatsApp |
+| `!wa inscrever <telefone> [origem]` | inscreve um número (ex.: `(21) 99999-1234`) |
+| `!wa remover <telefone>` | remove um número |
+| `!wa inscritos` | quantidade de números ativos |
+| `!wa status` | entregas, leituras e falhas do último aviso |
+| `!wa desvincular` | desliga a sala |
+
+Qualquer outra mensagem de texto de um administrador numa sala vinculada é enviada aos inscritos.
+
+Para importar inscritos de um formulário:
+
+```bash
+matrix-wacloud import-csv -c config.yaml --room '!idDaSala:dominio' respostas.csv \
+    --phone-column Telefone --consent-column "Carimbo de data/hora"
+```
+
+### Templates
+
+O conteúdo do aviso entra nos parâmetros `{{1}}`, `{{2}}`... do template. A ordem é definida em `template_params`, com os valores possíveis `label` (rótulo da sala), `text` (mensagem) e `sender` (nome de quem postou). Exemplo de template **Utility** em pt_BR:
+
+> Aviso UNIRIO ({{1}}): {{2}}
+
+```yaml
+template_params:
+  aviso_unirio: [label, text]
+```
+
+Quebras de linha viram ` | `, porque a Meta rejeita parâmetros com quebra de linha. Textos longos são truncados.
+
+## Implantação (VPS com Docker)
+
+O `docker-compose.yml` sobe Synapse, Postgres, Caddy (HTTPS automático via Let's Encrypt) e o bridge. Do bridge, só o caminho `/whatsapp/*` fica exposto à internet.
+
+Pré-requisitos: uma VPS com Docker e um domínio com registro DNS do tipo A apontando para ela (ex.: `avisos.seudominio.com`).
+
+```bash
+git clone https://github.com/allanmagalhaes/matrix-wacloud && cd matrix-wacloud
+cp .env.example .env                      # preencha MATRIX_DOMAIN, POSTGRES_PASSWORD, WA_*...
+docker compose build bridge
+docker compose run --rm --no-deps bridge matrix-wacloud generate-tokens   # cole no .env
+
+mkdir -p data/bridge && cp config.example.yaml data/bridge/config.yaml
+docker compose run --rm --no-deps bridge \
+    matrix-wacloud generate-registration -c /data/config.yaml -o /data/registration.yaml
+
+# gera o homeserver.yaml do Synapse e ajusta para Postgres + appservice
+docker compose run --rm --no-deps -e SYNAPSE_SERVER_NAME=$(grep ^MATRIX_DOMAIN .env | cut -d= -f2) \
+    -e SYNAPSE_REPORT_STATS=no synapse generate
+docker compose run --rm --no-deps -v ./data/synapse:/synapse bridge \
+    python /app/deploy/patch_homeserver.py /synapse/homeserver.yaml
+
+docker compose up -d
+docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml -u allan --admin http://localhost:8008
+docker compose logs -f bridge
+```
+
+Depois, entre em <https://app.element.io> com o servidor `https://SEU_DOMINIO` e o usuário criado.
+
+## Desenvolvimento
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+Para o teste de integração ponta a ponta (Synapse real + bridge + uma Graph API falsa que devolve webhooks assinados):
+
+```bash
+pip install matrix-synapse
+bash scripts/e2e/run_e2e.sh
+```
+
+## Limitações conhecidas
+
+- Mensagens iniciadas pela organização exigem template aprovado pela Meta e consentimento prévio do destinatário.
+- Contas sem verificação empresarial têm limite diário de destinatários e podem sofrer restrições para outros países (erro 130497). Use um número de remetente do mesmo país dos destinatários.
+- Respostas dos usuários não são repassadas às salas; apenas SAIR/PARAR/STOP é tratado.
+
+## Licença
+
+MIT

matrix_wacloud-0.1.0/README.md

@@ -0,0 +1,142 @@
+# matrix-wacloud
+
+*Matrix application service that forwards messages posted in Matrix rooms to WhatsApp subscribers through the **official WhatsApp Business Cloud API** — template messages, opt-in subscriber lists, delivery/read receipts and opt-out handling.*
+
+Conector (*bridge*) de notificação entre o [Matrix](https://matrix.org) e a WhatsApp Business Cloud API, desenvolvido como Trabalho de Conclusão de Curso do Bacharelado em Sistemas de Informação da UNIRIO.
+
+Diferente de pontes como o mautrix-whatsapp, que emulam o WhatsApp Web num número pessoal, este pacote usa somente a API oficial da Meta. Por isso ele **não** replica conversas: ele converte avisos publicados numa sala Matrix em **mensagens por template** para os inscritos daquela sala. Essa é a forma permitida pela Meta para mensagens iniciadas pela organização.
+
+```
+ sala Matrix ──(appservice)──▶ matrix-wacloud ──(Cloud API)──▶ WhatsApp dos inscritos
+      ▲                              │  ▲
+      └──── !wa status ◀── SQLite ◀──┘  └──(webhooks: sent/delivered/read/failed)── Meta
+```
+
+## Funcionalidades
+
+- Vínculo de salas Matrix a um template aprovado (`!wa vincular`).
+- Inscritos por sala, com registro da origem e da data do consentimento (LGPD). Importação de CSV, inclusive do Google Forms.
+- Envio concorrente com repetição automática nos erros temporários da API.
+- Recepção dos webhooks da Meta com **validação da assinatura `X-Hub-Signature-256`**.
+- Acompanhamento de entregas e leituras por aviso (`!wa status`).
+- Descadastro: o inscrito responde **SAIR** no WhatsApp e é removido de todas as salas.
+- Números mascarados nos logs e nas mensagens do bot.
+
+## Instalação
+
+```bash
+pip install matrix-wacloud
+```
+
+Requer Python 3.10+ e um homeserver Matrix onde você possa registrar um *application service* (por exemplo, Synapse).
+
+## Configuração rápida
+
+1. Copie `config.example.yaml` para `config.yaml` e `.env.example` para `.env`. Os segredos ficam no `.env`; o YAML os referencia como `${NOME}`.
+2. Gere os tokens do appservice e cole no `.env`:
+   ```bash
+   matrix-wacloud generate-tokens
+   ```
+3. Preencha no `.env` os dados do painel da Meta: `WA_PHONE_NUMBER_ID`, `WA_ACCESS_TOKEN` (token permanente), `WA_APP_SECRET` (Configurações do app → Básico → Chave secreta) e `WA_VERIFY_TOKEN` (uma senha inventada por você).
+4. Gere o registro e adicione-o ao homeserver (`app_service_config_files` no `homeserver.yaml`):
+   ```bash
+   matrix-wacloud generate-registration -c config.yaml -o registration.yaml
+   ```
+5. Teste as credenciais da Meta sem passar pelo Matrix:
+   ```bash
+   matrix-wacloud send-test -c config.yaml --to 5521999999999
+   ```
+6. Execute:
+   ```bash
+   matrix-wacloud run -c config.yaml
+   ```
+7. No painel da Meta (WhatsApp → Configuração → Webhooks), use `https://SEU_DOMINIO/whatsapp/webhook` como URL de callback, informe o mesmo `WA_VERIFY_TOKEN` e assine o campo **messages**. Ative também "Assinar webhooks" na conta do número que envia.
+
+## Uso na sala
+
+Convide `@wacloud:SEU_DOMINIO` para uma sala. Só administradores listados em `admins` podem convidar, comandar e disparar avisos.
+
+| Comando | Efeito |
+|---|---|
+| `!wa vincular <rótulo> [template] [idioma]` | liga a sala ao WhatsApp |
+| `!wa inscrever <telefone> [origem]` | inscreve um número (ex.: `(21) 99999-1234`) |
+| `!wa remover <telefone>` | remove um número |
+| `!wa inscritos` | quantidade de números ativos |
+| `!wa status` | entregas, leituras e falhas do último aviso |
+| `!wa desvincular` | desliga a sala |
+
+Qualquer outra mensagem de texto de um administrador numa sala vinculada é enviada aos inscritos.
+
+Para importar inscritos de um formulário:
+
+```bash
+matrix-wacloud import-csv -c config.yaml --room '!idDaSala:dominio' respostas.csv \
+    --phone-column Telefone --consent-column "Carimbo de data/hora"
+```
+
+### Templates
+
+O conteúdo do aviso entra nos parâmetros `{{1}}`, `{{2}}`... do template. A ordem é definida em `template_params`, com os valores possíveis `label` (rótulo da sala), `text` (mensagem) e `sender` (nome de quem postou). Exemplo de template **Utility** em pt_BR:
+
+> Aviso UNIRIO ({{1}}): {{2}}
+
+```yaml
+template_params:
+  aviso_unirio: [label, text]
+```
+
+Quebras de linha viram ` | `, porque a Meta rejeita parâmetros com quebra de linha. Textos longos são truncados.
+
+## Implantação (VPS com Docker)
+
+O `docker-compose.yml` sobe Synapse, Postgres, Caddy (HTTPS automático via Let's Encrypt) e o bridge. Do bridge, só o caminho `/whatsapp/*` fica exposto à internet.
+
+Pré-requisitos: uma VPS com Docker e um domínio com registro DNS do tipo A apontando para ela (ex.: `avisos.seudominio.com`).
+
+```bash
+git clone https://github.com/allanmagalhaes/matrix-wacloud && cd matrix-wacloud
+cp .env.example .env                      # preencha MATRIX_DOMAIN, POSTGRES_PASSWORD, WA_*...
+docker compose build bridge
+docker compose run --rm --no-deps bridge matrix-wacloud generate-tokens   # cole no .env
+
+mkdir -p data/bridge && cp config.example.yaml data/bridge/config.yaml
+docker compose run --rm --no-deps bridge \
+    matrix-wacloud generate-registration -c /data/config.yaml -o /data/registration.yaml
+
+# gera o homeserver.yaml do Synapse e ajusta para Postgres + appservice
+docker compose run --rm --no-deps -e SYNAPSE_SERVER_NAME=$(grep ^MATRIX_DOMAIN .env | cut -d= -f2) \
+    -e SYNAPSE_REPORT_STATS=no synapse generate
+docker compose run --rm --no-deps -v ./data/synapse:/synapse bridge \
+    python /app/deploy/patch_homeserver.py /synapse/homeserver.yaml
+
+docker compose up -d
+docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml -u allan --admin http://localhost:8008
+docker compose logs -f bridge
+```
+
+Depois, entre em <https://app.element.io> com o servidor `https://SEU_DOMINIO` e o usuário criado.
+
+## Desenvolvimento
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+Para o teste de integração ponta a ponta (Synapse real + bridge + uma Graph API falsa que devolve webhooks assinados):
+
+```bash
+pip install matrix-synapse
+bash scripts/e2e/run_e2e.sh
+```
+
+## Limitações conhecidas
+
+- Mensagens iniciadas pela organização exigem template aprovado pela Meta e consentimento prévio do destinatário.
+- Contas sem verificação empresarial têm limite diário de destinatários e podem sofrer restrições para outros países (erro 130497). Use um número de remetente do mesmo país dos destinatários.
+- Respostas dos usuários não são repassadas às salas; apenas SAIR/PARAR/STOP é tratado.
+
+## Licença
+
+MIT

matrix_wacloud-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "matrix-wacloud"
+version = "0.1.0"
+description = "Matrix application service that forwards room messages to WhatsApp via the official WhatsApp Business Cloud API (template messages, opt-in subscribers, delivery/read receipts)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Allan dos Santos Magalhães de Sousa" }]
+keywords = ["matrix", "whatsapp", "bridge", "appservice", "notifications", "cloud-api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Programming Language :: Python :: 3",
+  "Topic :: Communications :: Chat",
+]
+dependencies = [
+  "mautrix>=0.20,<0.22",
+  "aiohttp>=3.9",
+  "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-aiohttp>=1.0"]
+
+[project.scripts]
+matrix-wacloud = "matrix_wacloud.__main__:main"
+
+[project.urls]
+Source = "https://github.com/allanmagalhaes/matrix-wacloud"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = ["ignore:loop argument is deprecated:DeprecationWarning"]

matrix_wacloud-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matrix_wacloud-0.1.0/src/matrix_wacloud/__init__.py

@@ -0,0 +1,3 @@
+"""matrix-wacloud: Matrix -> WhatsApp Business Cloud API notification bridge."""
+
+__version__ = "0.1.0"

matrix_wacloud-0.1.0/src/matrix_wacloud/__main__.py

@@ -0,0 +1,203 @@
+"""Command line interface.
+
+    matrix-wacloud generate-tokens
+    matrix-wacloud generate-registration -c config.yaml -o registration.yaml
+    matrix-wacloud run -c config.yaml
+    matrix-wacloud import-csv -c config.yaml --room '!sala:dominio' inscritos.csv
+    matrix-wacloud send-test -c config.yaml --to 5521999999999
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import csv
+import logging
+import re
+import secrets
+import signal
+import sys
+from datetime import datetime
+
+import aiohttp
+import yaml
+
+from . import __version__
+from .config import ConfigError, load_config
+
+
+def cmd_generate_tokens(_args) -> int:
+    print(f"MWC_AS_TOKEN={secrets.token_urlsafe(48)}")
+    print(f"MWC_HS_TOKEN={secrets.token_urlsafe(48)}")
+    print("# Cole estas linhas no seu .env (nunca no git).")
+    return 0
+
+
+def build_registration(cfg) -> dict:
+    asc, domain = cfg.appservice, cfg.homeserver.domain
+    return {
+        "id": asc.id,
+        "url": asc.address,
+        "as_token": asc.as_token,
+        "hs_token": asc.hs_token,
+        "sender_localpart": asc.bot_localpart,
+        "rate_limited": False,
+        "namespaces": {
+            "users": [{"exclusive": True, "regex": f"@{re.escape(asc.bot_localpart)}:{re.escape(domain)}"}],
+            "aliases": [],
+            "rooms": [],
+        },
+    }
+
+
+def cmd_generate_registration(args) -> int:
+    cfg = load_config(args.config)
+    with open(args.output, "w", encoding="utf-8") as f:
+        yaml.safe_dump(build_registration(cfg), f, sort_keys=False, allow_unicode=True)
+    print(f"Registro gravado em {args.output}. Adicione-o a 'app_service_config_files' no homeserver.yaml.")
+    return 0
+
+
+def cmd_run(args) -> int:
+    cfg = load_config(args.config)
+    logging.basicConfig(level=cfg.log_level, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    if cfg.log_level != "DEBUG":
+        logging.getLogger("aiohttp.access").setLevel(logging.WARNING)
+    from .bridge import Bridge  # imported late so other commands don't need mautrix loaded
+
+    async def main() -> None:
+        bridge = Bridge(cfg)
+        stop = asyncio.Event()
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.add_signal_handler(sig, stop.set)
+            except NotImplementedError:
+                pass
+        await bridge.start()
+        await stop.wait()
+        await bridge.stop()
+
+    asyncio.run(main())
+    return 0
+
+
+def _parse_consent_ts(value: str | None) -> int | None:
+    if not value:
+        return None
+    for fmt in ("%d/%m/%Y %H:%M:%S", "%d/%m/%Y %H:%M", "%Y-%m-%d %H:%M:%S", "%Y/%m/%d %H:%M:%S", "%d/%m/%Y", "%Y-%m-%d"):
+        try:
+            return int(datetime.strptime(value.strip(), fmt).timestamp())
+        except ValueError:
+            continue
+    return None
+
+
+def cmd_import_csv(args) -> int:
+    from .store import Store
+    from .util import InvalidPhone, normalize_phone
+
+    cfg = load_config(args.config)
+    store = Store(cfg.database)
+    if not store.get_link(args.room):
+        print(f"A sala {args.room} não está vinculada. Rode '!wa vincular' nela antes.", file=sys.stderr)
+        return 2
+    added = updated = skipped = 0
+    with open(args.file, newline="", encoding="utf-8-sig") as f:
+        sample = f.read(4096)
+        f.seek(0)
+        dialect = csv.Sniffer().sniff(sample, delimiters=",;\t")
+        reader = csv.DictReader(f, dialect=dialect)
+        cols = {c.lower().strip(): c for c in (reader.fieldnames or [])}
+        phone_col = cols.get(args.phone_column.lower())
+        if phone_col is None:
+            print(f"Coluna '{args.phone_column}' não encontrada. Colunas: {reader.fieldnames}", file=sys.stderr)
+            return 2
+        consent_col = cols.get(args.consent_column.lower()) if args.consent_column else None
+        for row in reader:
+            raw = (row.get(phone_col) or "").strip()
+            if not raw:
+                skipped += 1
+                continue
+            try:
+                phone = normalize_phone(raw)
+            except InvalidPhone:
+                print(f"Ignorado (telefone inválido): {raw}", file=sys.stderr)
+                skipped += 1
+                continue
+            ts = _parse_consent_ts(row.get(consent_col)) if consent_col else None
+            if store.add_subscriber(args.room, phone, f"csv:{args.source}", ts):
+                added += 1
+            else:
+                updated += 1
+    print(f"{added} novo(s), {updated} reativado(s)/atualizado(s), {skipped} ignorado(s).")
+    return 0
+
+
+def cmd_send_test(args) -> int:
+    cfg = load_config(args.config)
+    from .cloudapi import CloudAPIClient, CloudAPIError
+    from .util import normalize_phone
+
+    async def main() -> int:
+        wa = cfg.whatsapp
+        async with aiohttp.ClientSession() as session:
+            client = CloudAPIClient(session, wa.phone_number_id, wa.access_token,
+                                    api_base=wa.api_base, api_version=wa.api_version, max_retries=0)
+            try:
+                wamid = await client.send_template(normalize_phone(args.to), args.template, args.language,
+                                                   args.param or None)
+            except CloudAPIError as e:
+                print(f"Falhou: {e}", file=sys.stderr)
+                return 1
+        print(f"Aceito pela API: {wamid}\nVeja o resultado final (delivered/read/failed) no webhook.")
+        return 0
+
+    return asyncio.run(main())
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="matrix-wacloud", description="Matrix → WhatsApp Cloud API bridge")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("generate-tokens", help="gera as_token/hs_token aleatórios")
+    s.set_defaults(func=cmd_generate_tokens)
+
+    s = sub.add_parser("generate-registration", help="gera o registration.yaml para o homeserver")
+    s.add_argument("-c", "--config", required=True)
+    s.add_argument("-o", "--output", default="registration.yaml")
+    s.set_defaults(func=cmd_generate_registration)
+
+    s = sub.add_parser("run", help="executa o bridge")
+    s.add_argument("-c", "--config", required=True)
+    s.set_defaults(func=cmd_run)
+
+    s = sub.add_parser("import-csv", help="importa inscritos (com consentimento) de um CSV")
+    s.add_argument("-c", "--config", required=True)
+    s.add_argument("--room", required=True, help="ID da sala Matrix (!abc:dominio)")
+    s.add_argument("--phone-column", default="telefone")
+    s.add_argument("--consent-column", default="Carimbo de data/hora",
+                   help="coluna com data/hora do consentimento (padrão do Google Forms)")
+    s.add_argument("--source", default="formulario", help="descrição da origem do consentimento")
+    s.add_argument("file")
+    s.set_defaults(func=cmd_import_csv)
+
+    s = sub.add_parser("send-test", help="envia um template direto (sem Matrix) para testar credenciais")
+    s.add_argument("-c", "--config", required=True)
+    s.add_argument("--to", required=True)
+    s.add_argument("--template", default="hello_world")
+    s.add_argument("--language", default="en_US")
+    s.add_argument("--param", action="append", help="parâmetro do corpo (repita para vários)")
+    s.set_defaults(func=cmd_send_test)
+
+    args = p.parse_args(argv)
+    try:
+        return args.func(args)
+    except ConfigError as e:
+        print(f"Erro de configuração: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())