yuboto-omni-api

# 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](https://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
- `histo...