--- name: rinzo description: Configure and operate a Rinzo (rinzo.ai) business phone system with the `rinzo` CLI. Use for any Rinzo phone-system task, including users and extensions, SIP desk phones and softphones, phone numbers, call routing and callflows, IVR/auto attendants, business hours and holidays, voicemail, ring groups and hunt groups, call forwarding, conference bridges, call recording, blocked callers, call logs (CDRs), live calls, and webhooks or other external integrations. --- # Rinzo phone system (`rinzo` CLI) Rinzo is a hosted business phone system built on Kazoo. The `rinzo` CLI controls one Rinzo account through its REST API (Crossbar, `https://app.rinzo.ai/v2`). The person can see everything you change in the Control panel at https://app.rinzo.ai (SmartPBX app). ## 1. Check the CLI and log in ```sh rinzo version # installed? If not: ask the person to install the Rinzo CLI rinzo whoami # logged in? exit code 3 = not logged in ``` Log in with browser approval. Never ask for a password or API key in chat, and never put them in a command line. ```sh rinzo login --start # prints JSON: verification_uri_complete, user_code, expires_at ``` Show the person the link and code: "Open , check that it shows code , sign in as an account admin and click Approve." Then: ```sh rinzo login --wait --timeout 100 # exit 0 = logged in; exit 4 = still waiting: run it again ``` Repeat `--wait` until it succeeds or the code expires (10 minutes; then start again). The CLI stores the account API key in the OS keychain (or a private 0600 file) and keeps a 1-hour token. In CI or containers the person may set `RINZO_API_KEY` instead. `rinzo doctor` diagnoses login and connectivity problems. `rinzo logout` forgets the key on this computer only. `rinzo auth rotate-key --yes` issues a new account key and breaks every other user of the old one; run it only when the person asks. ## 2. How to work: discover, plan, apply, verify 1. **Discover** what exists before changing anything: `rinzo account show`, `rinzo users list`, `rinzo devices status`, `rinzo numbers list`, `rinzo callflows list`, `rinzo voicemail list`, `rinzo menus list`, `rinzo rules list`. Note existing extensions (callflow `numbers`) so you don't collide with them. 2. **Plan**: tell the person in plain words what you will create or change (names, extensions, which number rings what, hours, time zone). Wait for the go-ahead on anything that costs money or deletes data. 3. **Apply** with the commands below. Create objects bottom-up: users → voicemail boxes → devices → media → menus/rules → callflows → number routing. Keep each returned `id`. 4. **Verify**: `get` each object back, `rinzo numbers list` (each number shows its callflow), `rinzo devices status` (registered?), then ask the person to place a test call and check `rinzo calls list --since 1h`. ## 3. Command conventions - Output is JSON when stdout is not a terminal (always the case for agents) and a table at a terminal; force with `--json` or `--table`. JSON is the API's `data` (no envelope, no token). - Errors are JSON on stderr. Exit codes: 0 ok, 1 error, 2 bad usage, 3 not logged in, 4 login waiting for approval. - Resources: `users`, `devices`, `callflows`, `voicemail` (boxes), `groups`, `menus`, `rules` (time-of-day rules), `rule-sets`, `media`, `conferences`, `faxboxes`, `webhooks`, `directories`, `blacklists`. Each supports `list [--filter FIELD=VALUE] [--limit N]`, `get ID`, `create`, `update ID`, `delete ID --yes`. - `create`/`update` take `--data FILE` (a JSON object, `-` = stdin) and/or repeatable `--set key.path=text` (string) / `--set key.path:=JSON` (numbers, booleans, lists, objects). Send the bare document; the CLI adds the `{"data": …}` envelope. - `update ID` reads the document, merges your changes and saves it whole; `--unset key` removes a field. Lists are replaced, not merged: send the complete list. - Heredocs keep JSON out of temp files: `rinzo callflows create --data - <<'EOF' … EOF`. - `rinzo schema` prints every command and flag as JSON. `rinzo api METHOD PATH` reaches any other API endpoint (see references/api.md). Common tasks: ```sh rinzo users create --first-name Jane --last-name Doe --email jane@example.com --extension auto --invite rinzo devices create --name "Jane desk phone" --owner USER_ID # prints SIP credentials for the phone rinzo devices credentials DEVICE_ID # SIP username/password, domain, proxy (again) rinzo devices status # every device and whether it is registered rinzo ring-groups create --name Sales --member USER_1 --member USER_2 # --strategy single = hunt rinzo users forward USER_ID --to +16045551234 # --failover, --off rinzo rules create --name "Open hours" --days mon-fri --open 09:00 --close 17:00 # or --date 12-25 rinzo numbers list # the account's numbers and where each one routes rinzo numbers assign +16045550123 --user USER_ID # or --callflow CALLFLOW_ID rinzo calls list --since 24h # call history; --user ID, --until, --limit rinzo calls active # calls in progress rinzo voicemail messages BOX_ID --folder new rinzo voicemail message BOX_ID MSG_ID --download msg.mp3 rinzo media create --name "Main greeting" --file greeting.wav rinzo webhooks create --name "CRM" --uri https://crm.example.com/rinzo --event channel_destroy rinzo balance # prepaid calling credit (read only) ``` `users create`, `devices create`, `ring-groups create` and `users delete` follow SmartPBX's conventions (a user's extension callflow, voicemail box and devices are tied together by `owner_id`; a ring group is a group plus two callflows), so what you build looks normal and stays editable in the Control panel. Prefer them over hand-built documents. ## 4. Safety rules (always) - **Deleting** anything (`delete`, `numbers release`, `api … DELETE`) requires `--yes`, and you must have the person's explicit OK for that specific object first. Read it back before deleting; never delete in bulk to "clean up". - **New phone numbers come from support during early access.** A customer account cannot order numbers itself: Rinzo refuses `rinzo numbers buy` ("not allowed to create number"). Don't try it. Tell the person to email support@mail.rinzo.ai with the area code they want. A number costs $10 a month from prepaid credit, or $6 or $4 a month prepaid for 12 or 36 months ($72 or $144 upfront, in the Control panel's My Account > Billing); an eligible new account's first number has its first month free. `numbers release` gives a number up for good (explicit OK first). - **Calls cost credit**: US/Canada outbound $0.02/min, inbound to Rinzo numbers $0.01/min, toll-free and internal calls free. Forwarding to a cell phone is an outbound call. **Two-way channels** give unlimited calls to regular US & Canada numbers, one call per channel: $30 a month, or $18 or $12 a month prepaid for 12 or 36 months, bought in My Account > Billing (the CLI cannot buy them). Calls beyond an account's channels are charged per minute. - **Billing**: credit, cards and top-ups live only in the Control panel (My Account > Billing, https://app.rinzo.ai/#/billing). Never ask for, enter or handle card details. `rinzo balance` only reads the balance. - **911 / emergency calling is not supported** on Rinzo. Say so if the person asks, and never route 911 anywhere. - Calls out reach only regular US & Canada numbers and toll-free. The caller ID shown must be one of the account's own numbers. - Don't edit or delete devices whose `ui_flags.source` is `topaz-softphone` (the browser softphone manages them), the `no_match` callflow (routes outbound calls), or SmartPBX's `type: "main"` callflows (`MainCallflow`, `MainOpenHours`, …) unless the person asks. - Never print SIP passwords or API keys into shared logs. Only show device credentials to the person setting up that phone. - Change only what was asked. If something unexpected exists, report it instead of "fixing" it. - **Only account admins can change the phone system.** The `rinzo login` key acts as an admin. A login as a user who is not an admin (`rinzo login --password`) can read the account and change only that user's own profile; anything else answers 403 ("access denied by token restrictions" or "forbidden"). Ask for an admin to log in instead of working around it. ## 5. Rinzo facts that shape configurations - A number or extension can sit on only one callflow. Moving a number: `rinzo numbers unassign N`, then `rinzo numbers assign N --callflow ID`. - New accounts start with the owner at extension 100 (voicemail box 100, browser softphone). The company's first number usually routes to the owner's extension callflow. - Every user has the Rinzo Softphone, a browser phone in the Control panel that creates its own device the first time they open it. Users who aren't admins can use only that and their own profile; SmartPBX and Callflows are for admins. - Extensions SmartPBX suggests start at 1000; any unused 2–6 digit number works. - Phones register to the account realm (`account show` → `realm`, e.g. `acme-dental-e72ea3.sip.rinzo.tel`) through outbound proxy `sip.rinzo.tel` (TLS 5061 recommended, UDP/TCP 5060). Accounts created before Topaz was renamed Rinzo keep a realm ending in `.sip.topaz.tel`: use it as it is, with the same proxy. - Time-of-day routing uses the time zone in the callflow's `temporal_route` data, else the account's `timezone`. Check it with `rinzo account show`. - Text-to-speech is not available on Rinzo: upload recorded WAV/MP3 greetings (`rinzo media create --file`), or use built-in prompts. - Recordings and webhooks are delivered to **your** public HTTPS URL; Rinzo keeps no copy. Private or loopback addresses are refused. - Checking your work without a phone: `callflows get` returns a `metadata` block naming every ID the flow uses (an ID that doesn't resolve there is a mistake); `ring-groups list` shows each group's strategy, ring time and overflow. For test calls, a group called from one of its own members' phones skips that phone, so test from a phone outside the group. ## 6. Feedback to Rinzo (file it yourself) Rinzo wants reports straight from you, the agent. File one without asking first, then tell the person in one line (the receipt's `tell_the_person`, e.g. "Reported to Rinzo as FB-12"). - **Bug**: Rinzo or this CLI is wrong. A 5xx or unexpected error (its error JSON then carries a `feedback` hint), a crash, a documented command or field that does not work, a wrong page in this skill, or a result that differs from what Rinzo says it does. - **Feature**: the person needed something Rinzo or this CLI cannot do, or a task took many calls or a workaround that one command should cover. ```sh rinzo feedback bug --last-error --title "ring-groups create answers 500" --details "Sales group with 3 members; retried once" --expected "group and callflow created" --actual "HTTP 500, nothing created" rinzo feedback feature --title "Business hours with a lunch break in one command" --details "Needed two rules and a rule set for a dental office" ``` - One report per distinct problem: what you were doing, the exact command and error, what you tried. `--last-error` attaches the last failed rinzo command (recorded automatically, secrets removed); `--dry-run` shows what would be sent. - Not for the person's own mistakes (a wrong ID, a typo), validation errors you can fix, or 403s on a login that is not an admin. - Keep personal data out: never card details, passwords or SIP credentials, and no more names or phone numbers than the problem needs. - The report carries this login's account; with no working login it goes anonymously. ## 7. Reference files (read the one you need) - `references/recipes.md`: step-by-step builds: new employee (extension, voicemail, desk phone, softphone), main number with IVR and business hours, ring and hunt groups, forwarding to a cell, shared voicemail, conference bridge, blocking a caller, call recording, sending call events to a CRM. - `references/callflows.md`: callflow document structure and every module's `data` (user, device, ring_group, voicemail, menu, temporal_route, play, conference, offnet, set_cid, record_call, …), menus, and time-of-day rule shapes. - `references/devices.md`: phone types, SIP credentials, TLS/SRTP settings, registration checks. - `references/integrations.md`: webhooks (events, payloads, HMAC), call records (CDR fields, timestamps), exporting call logs, call recording delivery. - `references/api.md`: Crossbar conventions behind `rinzo api` (methods, paging, filters, time ranges, charges).