retarus-sms4a

# Retarus SMS4A ## Overview Use this skill for operational work with the Retarus SMS for Applications API: prepare or validate SMS job payloads, send jobs, and fetch per-recipient status for a `jobId`. Prefer the helper script in `scripts/sms4a_api.py` instead of hand-writing HTTP calls. It already handles Basic Auth, simple payload construction, full-payload file input, datacenter selection, and the `eu` status fallback across `de2` and `de1`. ## Quick Start 1. Resolve credentials from the secret store into one of these supported inputs: - `RETARUS_SMS4A_USERNAME` and `RETARUS_SMS4A_PASSWORD` - `RETARUS_SMS4A_SECRET_FILE` pointing to a JSON or `.env`-style file with `username` and `password` - The default local secret file path `~/.openclaw/secrets/retarus-sms4a.env` or `~/.openclaw/secrets/retarus-sms4a.json` - Explicit `--username` and `--password` flags only for local testing 2. Send a simple SMS job: ```bash python3 scripts/sms4a_api.py send \ --datacenter eu \ --text "Your access code is 123456" \ --recipient +4917600000000 \ --status-requested ``` 3. Check recipient status for a job: ```bash python3 scripts/sms4a_api.py status --job-id J.20221116-102407.583-0lajfsfmoXIZJO93PQ ``` ## Datacenter Rules - Use `eu` as the default send endpoint unless the user explicitly wants `de1` or `de2`. - Do not rely on the `eu` hostname for status lookups. The `eu` endpoint is DNS-balanced across `de1` and `de2`, so a status lookup must try both datacenters. - The `status` command defaults to `--datacenter auto`, which tries `de2` first and then `de1`. - If the user explicitly prefers `de1` or `de2`, still try both datacenters and use the chosen one only as the first lookup target. ## Sending Workflow - For common one-message jobs, pass `--text` and one or more `--recipient` values. - For advanced jobs, pass `--payload-file` with a JSON body matching the OpenAPI `JobRequest` schema. - Use `--dry-run` first if you want to validate payload assembly without sending anything. - Return the created `jobId` and the datacenter that accepted the job. ## Status Workflow - Use `status --job-id ...` to query `GET /sms?jobId=...`. - Return the successful datacenter together with the recipient reports. - If one datacenter returns `404` or `500`, continue with the next datacenter. - If both datacenters fail, report both attempts and their response codes. ## Credential Handling - Never hardcode credentials into the skill files. - Prefer secret-store backed environment injection. - Prefer the standard local secret path `~/.openclaw/secrets/retarus-sms4a.env` for operator-managed credentials on an OpenClaw host. - If a secret file is used, support either: - JSON: `{"username":"...","password":"..."}` - `.env` style: ```dotenv RETARUS_SMS4A_USERNAME=... RETARUS_SMS4A_PASSWORD=... ``` ## Reference - Read `references/api.md` for the server aliases, supported helper-script options, and the subset of the OpenAPI schema this skill uses most often.