Yuboto Omni API Assistant

Implement, troubleshoot, and generate integrations for Yuboto Omni API (SMS/Viber/messaging endpoints, callbacks, lists/contacts/blacklist, cost/balance/acco...

Security Scan

The skill's requests, scripts, and documented runtime behavior are coherent with its stated purpose (working with the Yuboto/Octapush Omni API) and its only required secret (OCTAPUSH_API_KEY) is appropriate for that purpose.

Purpose & Capability

Name/description ask for Yuboto/Octapush API integration and the skill requires python3 plus OCTAPUSH_API_KEY — both expected and proportional. Declared binaries, env var names, and the provided client/CLI scripts directly implement the described functionality (balance, cost, send, DLR, history, poll).

Instruction Scope

SKILL.md instructs running the included Python scripts, consulting the bundled Swagger JSON, and storing the API key in OpenClaw or an env var. The runtime instructions and helper scripts only access the API host (https://api.yuboto.com by default), documented state/log dirs, and declared env vars. There is no instruction to read unrelated system files or secrets, and scripts explicitly avoid sourcing .env files.

Install Mechanism

There is no install script; the package is script-and-docs based and uses only Python standard library (urllib) and shell. No external download-of-code-from-arbitrary-URLs or package installs are performed by the skill itself.

Credentials

The only required credential is OCTAPUSH_API_KEY (primaryEnv). Optional env vars are documented and relate to runtime behavior (state/log dirs, test number, default sender, base URL, payload storage). No unrelated credentials are requested.

Persistence & Privilege

The skill persists runtime state and logs outside the skill directory by default (XDG_STATE_HOME or ~/.local/state/openclaw/yuboto-omni-api). Defaults are privacy-minimizing (full payload persistence is disabled by default), but the user can enable full payload storage via YUBOTO_STORE_FULL_PAYLOAD=true. The skill does not request always:true and does not modify other skills.

Assessment

This package appears internally consistent for integrating with Yuboto/Octapush. Before installing or running: 1) Only provide an API key issued by Yuboto/Octapush (OCTAPUSH_API_KEY); storing it via OpenClaw config is recommended over exporting it to your shell. 2) Be aware the CLI creates persistent state/log files under $XDG_STATE_HOME or ~/.local/state/openclaw/yuboto-omni-api — full message payload storage is off by default but can be enabled with YUBOTO_STORE_FULL_PAYLOAD. 3) The scripts contact api.yuboto.com (and refresh_swagger.py fetches the live swagger). If you will run poll-pending on a schedule, review poll_pending.sh and confirm the environment it runs under has only the intended API key and permissions. 4) If you plan to override YUBOTO_BASE_URL or provide callback URLs, verify those endpoints are trusted to avoid inadvertent data transmission. If you want higher assurance, inspect/run the scripts in a restricted environment (or review the bundled files) before giving the API key to the skill.

Yuboto Omni API

Use this skill to work with Yuboto Omni API safely and consistently.

Note: This skill requires the OCTAPUSH_API_KEY environment variable.

Getting Started: You need a Yuboto/Octapush account with API access. Register at octapush.yuboto.com and request API access from support.

OpenClaw Integration: This skill supports native OpenClaw credential management. Store your API key in openclaw.json for centralized, secure credential handling.

Source-of-truth order

1. references/swagger_v1.json (live endpoint contract)
2. references/api_quick_reference.md (human-readable endpoint map)
3. references/omni_api_v1_10_raw.md (legacy PDF extract)
4. assets/OMNI_API_DOCUMENTATION_V1_10.pdf (original PDF)

If PDF and Swagger conflict, prefer Swagger for endpoint paths/fields.

Fast workflow

1. Identify the use case (send message, get DLR, contacts, subscriber lists, blacklist, cost/balance).
2. Find matching endpoint(s):
   • Read references/api_quick_reference.md, or
   • Run: python3 scripts/find_endpoints.py --q "<keyword>"
3. Validate request schema directly in references/swagger_v1.json:
   • parameters (path/query/header)
   • requestBody
   • response schema
4. Build implementation code with:
   • clear auth header handling
   • retries + timeout
   • structured error mapping
5. For advanced Viber features, check Swagger first.

Available commands (provided by scripts/yuboto_cli.py)

• balance — get account balance
• cost --channel sms --iso2 gr --phonenumber +30... — estimate sending cost
• send-sms --sender <approved_sender> --text "..." --to +30... --batch-size 200 --sms-encoding auto — send SMS (auto-batched + auto Unicode/GSM)
• dlr --id <messageGuid> — check delivery status for one message
• send-csv --file contacts.csv --phone-col phonenumber --text-col text --sender-col sender — bulk send from CSV
• poll-pending — refresh statuses for all pending messages
• history --last 20 — show recent send records
• status / status --id <messageGuid> — inspect tracked message state

Output requirements

When generating code or integration instructions:

• Include exact method + path.
• Include required auth headers.
• Include minimal working request example.
• Include expected response shape.
• Include 1 failure case and handling.

Environment Variables

Required Credential

• OCTAPUSH_API_KEY — Your Yuboto/Octapush API key (already base64 encoded from Octapush)

Note: This is the only credential required.

Optional Variables (for testing/overrides)

• TEST_PHONENUMBER — Phone number for testing (international format: +3069XXXXXXXX)
• SMS_SENDER — Default sender ID for SMS messages (must be approved)
• YUBOTO_BASE_URL — Override API base URL (default: https://api.yuboto.com)

Getting an API Key

To use this skill, you need a Yuboto/Octapush API key:

1. Register for an account at octapush.yuboto.com
2. Contact Yuboto support to request API access
3. Get your API key from your Octapush dashboard or via support

The API key is used for authentication with all Yuboto Omni API endpoints.

Setup Instructions

Option 1: OpenClaw Config (✅ Recommended)

Add to your openclaw.json config file:

"skills": {
  "entries": {
    "yuboto-omni-api": {
      "enabled": true,
      "env": {
        "OCTAPUSH_API_KEY": "your_base64_api_key_here"
      }
    }
  }
}

Option 2: Environment Variable

export OCTAPUSH_API_KEY="your_base64_api_key_here"

Note: .env files are not supported. Use OpenClaw config for secure, centralized credential management.

Security + Ops Notes

• Store API key in environment variable OCTAPUSH_API_KEY, not in source files.
• Prefer env vars over CLI --api-key to avoid leaking credentials in shell history.
• poll_pending.sh reads OCTAPUSH_API_KEY from the process environment only (it does not source .env).
• Always use an account-approved sender ID for SMS. If sender is not approved, API returns 108 - Sms Sender is not valid.
• Bulk safety defaults are enabled:
  • send-sms defaults to --batch-size 200 (hard cap 1000 recipients/request)
  • send-sms defaults to --batch-delay-ms 250
  • send-csv defaults to --delay-ms 100
• Encoding defaults:
  • --sms-encoding auto detects non-GSM text and sends as Unicode
  • Force Unicode with --sms-encoding unicode for scripts like Greek/Arabic/Chinese
  • Force GSM-7 with --sms-encoding gsm when needed
• Local state retention is enabled by default:
  • Sent log rotates to last 5000 lines (YUBOTO_MAX_SENT_LOG_LINES)
  • State index keeps up to 5000 tracked IDs (YUBOTO_MAX_STATE_RECORDS)
• Runtime data location default is outside the skill folder:
  • CLI state default: $XDG_STATE_HOME/openclaw/yuboto-omni-api (fallback ~/.local/state/openclaw/yuboto-omni-api)
  • Poll logs/state default under the same base (YUBOTO_LOG_DIR/YUBOTO_STATE_DIR override supported)
• Privacy-by-default storage:
  • Stored state/log keeps minimal metadata (messageGuid, timestamps, status, recipient count)
  • Full payload/text/recipient persistence is off by default
  • Enable full persistence only if needed via YUBOTO_STORE_FULL_PAYLOAD=true
• Runtime dependency model: Python standard library only (no requests install required).
• Helper scripts are also stdlib-only: scripts/refresh_swagger.py uses urllib (no pip installs).
• Treat local runtime logs/state as sensitive even in minimized mode.

Notes

• Swagger URL: https://api.yuboto.com/scalar/#description/introduction
• Swagger JSON: https://api.yuboto.com/swagger/v1/swagger.json
• More product/account info: https://messaging.yuboto.com
• Keep generated examples language-neutral unless user requests GR/EN copy.