# Phones and devices

Apply the [authorization policy](../SKILL.md#authorization-and-working-style) to every step,
including local files, sends, paid features and test calls. Proceed within existing authority;
ask only for missing decisions or authority, or report blocked steps when unattended.

A **device** is something that can ring: a SIP desk phone, a softphone app, or a cell phone
the call is forwarded to. A device usually has an `owner_id` (a user). Calling that user's
extension rings all of their devices at once.

For an external PBX or SIP application used as a trunk, see [SIP trunks](trunks.md).
Use that workflow instead of creating an employee device.

## Types

| `device_type` | What it is | Registers over SIP? |
|---|---|---|
| `sip_device` | Desk phone or ATA (Yealink, Poly, Grandstream, Cisco, …) | yes |
| `softphone` | Desktop/mobile SIP app (Zoiper, MicroSIP, Linphone, Bria, …) | yes |
| `cellphone` | An outside number that rings via call forwarding | no (uses outbound minutes) |
| `landline` | Same as cellphone, for a landline | no |

Rinzo also has a **browser softphone** in the Control panel (app "Rinzo Softphone"). It creates
its own device for each user the first time they open it (`device_type: "softphone"`,
`ui_flags.source: "topaz-softphone"`, WebRTC). Nothing needs configuring. Preserve those devices
unless authorized changes specifically cover them. A new employee only needs a Control panel login to use it.
For device ownership changes or credential rotation, keep within the specific devices, users and
effects covered by the task or standing approval; never expand to unrelated devices.

## Create

```sh
rinzo devices create --name "Jane desk phone" --owner USER_ID --type sip_device
rinzo devices create --name "Jane laptop" --owner USER_ID --type softphone
rinzo devices create --name "Jane cell" --owner USER_ID --type cellphone --number +16045551234
```

SIP devices get a generated username (`user_` + 10 letters/digits) and a 16-character password. SIP usernames must not contain `-` (Rinzo rejects such URIs on outbound calls).
For `cellphone` the CLI sets SmartPBX's forwarding block:

```json
{"call_forward": {"enabled": true, "number": "+16045551234", "require_keypress": true, "keep_caller_id": true},
 "contact_list": {"exclude": true}}
```

`require_keypress: true` makes the cell owner press 1 to accept, so the cell's own voicemail
can't swallow the call. Every forwarded call is also an outbound call: it uses the plan's
included minutes, then prepaid credit.

Hand-built SIP device (equivalent shape):
```json
{"name": "Front desk", "device_type": "sip_device", "owner_id": "USER_ID", "enabled": true,
 "sip": {"username": "user_k3j9x0aq2w", "password": "Xk3...12chars"},
 "media": {"encryption": {"enforce_security": true, "methods": ["srtp"]}}}
```

## Configure the phone

```sh
rinzo devices credentials DEVICE_ID
```
returns `username`, `password`, `sip_domain` (the account realm, for example
`acme-dental-e72ea3.sip.rinzo.tel`; accounts from before the rename keep their `.sip.topaz.tel`
realm, which works the same), `outbound_proxy` (`sip.rinzo.tel`) and transports. Phone settings:

| Setting | Value |
|---|---|
| SIP server / domain / registrar | the account realm (`sip_domain`) |
| Outbound proxy | `sip.rinzo.tel` |
| Transport, port | **TLS 5061** (recommended) or UDP/TCP 5060 |
| Auth username / password | from `devices credentials` |
| User ID / display name | the same username; any display name |
| Registration expiry | 300 s (Rinzo default) |
| SRTP | with TLS: **mandatory, SDES keys** (`RTP/SAVP`, AES_CM_128_HMAC_SHA1_80) |
| ZRTP | off (not supported) |

The TLS certificate names `sip.rinzo.tel` and `*.sip.rinzo.tel`, so TLS works through the outbound
proxy and also straight to a realm ending in `.sip.rinzo.tel`. A realm ending in `.sip.topaz.tel`
(accounts from before the rename) needs the `sip.rinzo.tel` outbound proxy for TLS. Either way the
realm is the SIP domain. DNS SRV records exist for `sip.rinzo.tel` (`_sips._tcp`, `_sip._tcp`,
`_sip._udp`).

Encryption pairing (tested live). Set the device to match the phone:

| Rinzo device `media.encryption` | Phone setting | Result |
|---|---|---|
| `{"enforce_security": true, "methods": ["srtp"]}` | TLS + SRTP mandatory (SDES) | encrypted both ways (recommended) |
| `{"enforce_security": true, "methods": ["srtp"]}` | SRTP disabled | calls **to** the phone fail (488); keep them aligned |
| `{"enforce_security": false}` (SmartPBX default) | SRTP disabled or optional | plain RTP; works everywhere |
| none | SRTP mandatory | calls to the phone refused (488) |

Turn SRTP on for an existing device:
`rinzo devices update DEVICE_ID --set media.encryption.enforce_security:=true --set 'media.encryption.methods:=["srtp"]'`

Media (RTP) comes from Rinzo's media server on UDP 16384–32768. Most home and office routers
work without changes. Turn off SIP ALG on the router if calls connect with no audio.

## Check registration

```sh
rinzo devices status       # every device: registered true/false, user agent, source IP
rinzo registrations        # raw list of current registrations
```

If a phone won't register: check the username/password/domain, check that the proxy is
`sip.rinzo.tel`, check the transport and port (5061 needs TLS), and check `enabled` is true. Then
reboot the phone if authorized and accessible; otherwise report that a human reboot is pending
(or ask when interactive). A phone that keeps retrying a wrong password floods the registrar,
so unplug it or fix it promptly within authority.

## Other device fields you may change

- `enabled: false`: stop ringing it without deleting it.
- `call_restriction`: per-device outbound limits (the account's restrictions apply anyway).
- `suppress_unregister_notifications: true`: no "device lost registration" emails (useful for
  laptops and softphones that go offline often).
- `caller_id.external`: per-device outbound caller ID (must be an account number).
