Usage

Users and phones

A user is an extension with a password. Phones register with it; desk phones can be given one address and fetch everything else, including a password of their own.

Users

$ api -d '{"username":"1001","password":"a-long-random-password","display_name":"Alice"}' localhost:8080/v1/users

Leave username and password out, or send "auto", and the server takes the next free extension and makes up the password; "portal_password":"auto" does the same for the console login. The answer carries them once, as generated_password and generated_portal_password; only hashes are kept. The console's New user does this by default and ends with what to put into the phone.

Ring groups, menus, queues and business hours are numbered the same way: leave the extension out and each kind continues from its own highest number, starting at 600 for groups, 700 for menus, 800 for queues, 500 for business hours and 1001 for users. There are no ranges to configure: give the first of a kind the number you want and the rest follow.

Point a phone at the server with the username and password. display_name and caller_id are what other people see; the server sets them, a phone cannot fake them. PATCH /v1/users/{id} changes any field: a new password applies to the next request, and deleting a user drops their registrations.

Per user there is also voicemail (on by default), email for voicemail notifications, greeting (an uploaded sound), srtp to require encrypted audio, and the dialling rules allow_prefixes and deny_prefixes; see toll fraud.

Desk phones that set themselves up

Yealink phones are provisioned from the server (Desk phones in the console). Register the phone's hardware address and the user it belongs to:

$ api -d '{"mac":"00:15:65:1a:2b:3c","username":"1001","label":"Reception"}' localhost:8080/v1/devices
{"success":true,"data":{"id":1,"provisioning_path":"/provision/k7hw3m2p/001565…","…":"…"},"error":null}

Put the server's address in front of the path and paste it into the phone's web page under Settings → Auto Provision → Server URL, then Auto Provision Now. The phone fetches its extension, the server's address and port, the phonebook, its busy-lamp keys, its clock settings, and a password of its own.

• Its own password. The phone authenticates as phone-<mac>, never with the user's password. The password is generated, kept as hashes, and handed over once: the first fetch has it, later ones do not, and a Yealink keeps what a later file does not mention. A phone that was factory-reset needs New password (POST /v1/devices/{id}/password), and so does one that did not come for its password within three days: it is taken away, so that it does not sit in the database and its backups.
• Its web page. Each phone also gets a password for its own web page and menus, for both accounts it shows, admin and user, so that a new phone stops asking whoever plugs it in to choose one. Web password on the Desk phones page reads it; it is in the phone's file at every fetch, so whoever holds that phone's address can read it.
• What it may dial without the send key: the extensions that exist here, the parking slots, *97, *8 and the emergency numbers, as exact numbers rather than a pattern, so a phone never dials into thin air. A new extension becomes dialable when the phone next looks, within a day.
• Its clock. Settings → Desk phones → Timezone (timezone, an IANA name) becomes the phone's time zone, summer time included. The phone still needs a time source of its own.

An address that keeps asking for what is not there is told to wait. Deleting the phone shuts it out at once without touching the user's other phones. The phone looks again daily.

For a roll-out, provisioning_shared (Settings → Desk phones) opens one address for all phones (GET /v1/provisioning has it), to hand out by DHCP option 66. A phone is then known by its hardware address alone, so anybody on that network who knows one can fetch that phone's settings: trusted networks only, and off afterwards. -phones-addr 0.0.0.0:8081 gives the phones a listener that serves these files and the phonebook and nothing else, so that the API can stay on localhost.

Softphones

The browser phone and the desktop app are devices of the user's too, with credentials of their own, which the user gets by adding one from the Phone page. Each shows on the Desk phones page as a softphone, where an administrator can remove it; the user lists and removes their own under /v1/me/softphones. Five per user. Their credentials work over WebSocket only: taken to a desk phone they are refused.

The shared phonebook

$ api -d '{"name":"Acme Ltd","number":"+441234567890"}' localhost:8080/v1/contacts

A call from that number then arrives as "Acme Ltd", whatever the network calls it. The phones fetch the whole phonebook, users, ring groups, queues and contacts, from an address with a secret in it (GET /v1/phonebook gives it; Yealink: Directory → Remote Phone Book), since a phone cannot send a token. POST /v1/phonebook/address replaces the secret. The name follows the number your provider asserts, which, like caller ID anywhere, can be forged upstream: it is a label, not proof of who is calling.

Who is online

GET /v1/registrations lists every phone that is registered and from where; DELETE /v1/registrations/1001 kicks one, which may register again. The console shows the same under Registrations.

Forwarding, do not disturb, pickup

A single tone confirms "you can be reached here", a falling pair "you cannot", the error tone that nothing changed. Users can set the same on their own console pages.

A call forwarded to an outside number is that user's call: their dialling rules decide whether it may go there, the provider sees their caller ID, and it counts against their call limit, so a stolen password cannot forward calls anywhere its owner could not dial, and an inbound number forwarded to a mobile cannot be used from outside to run up calls. "Not answered" means forward_no_answer_seconds (20), or no phone switched on; without a destination the caller gets voicemail. Do not disturb counts as busy. Dialling your own extension rings your other phones, if you have any; with only the one, you get your own voicemail.

Call parking

Slots 71 to 75 (park_first, park_count; 0 switches parking off). To park a call, transfer it to a free slot: a blind transfer to 71. The caller hears music, your phone is free, and whoever dials 71, from any phone, has the call. A slot that holds a call refuses a second one. After park_timeout seconds (120) the phone that parked it rings again; unanswered, the call ends. The Wallboard lists who is parked, and a busy-lamp key for a slot is lit while a call waits in it: press it during a call to park, when it is lit to fetch.

Busy lamps

A key on one phone that shows a colleague: dark when free, blinking while their phone rings, lit while they are on a call. Phones subscribe with Event: dialog (on a Yealink: a line key of type BLF with the extension as its value); any user may watch any other. For provisioned phones give the device its keys (Desk phones → Busy-lamp keys, or "keys":["1002","1003"]) and they arrive with the phone's settings, set up so that pressing a blinking key picks the call up. A ring group or queue among the keys becomes a key that dials it. Keys given this way start at the phone's second key and replace whatever was put on those keys by hand.