Desk phones and softphones

Any standards-based SIP phone — a desk phone or a softphone on a laptop or mobile — can be a ScaiDial extension. Phones register on your tenant's own SIP domain, <label>.sip.scailabs.ai, and from then on they ring when their extension is called and can call other extensions, bots and outside numbers.

Create a phone extension#

Create an extension of type sip_endpoint (admin UI: ScaiDial → Extensions → New, type Desk phone / softphone):

bash
curl -s -X POST $SCAIDIAL/extensions -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"number": "201", "type": "sip_endpoint", "display_name": "Front desk"}'

ScaiDial generates a strong password and creates the phone login. Read it with GET /extensions/{id}/sip-account (admin UI: Phone login):

json
{
  "domain": "example.sip.scailabs.ai",
  "username": "201",
  "password": "…",
  "server": "example.sip.scailabs.ai",
  "outbound_proxy": "sip.scailabs.ai",
  "transports": [
    {"transport": "tls", "port": 5061, "recommended": true},
    {"transport": "tcp", "port": 5060},
    {"transport": "udp", "port": 5060}
  ],
  "srtp": "optional",
  "registrations": [
    {"contact": "…", "received": "…", "user_agent": "Yealink SIP-T54W", "expires_in_s": 287, "transport": "tls"}
  ],
  "registration_error": null
}

Enter domain as the phone's SIP server / domain, username as user and authentication name, and password. Several phones may log in to the same extension; all of them ring.

Endpoint	Does
`GET /extensions/{id}/sip-account`	Login details and the phones registered right now
`POST /extensions/{id}/sip-account/rotate`	New password; registered phones are logged out and must use the new one
`POST /extensions/{id}/sip-account/sync`	Re-create the login on the phones edge (after an error shown on the extension)

Disabling the extension or changing its type removes the login; deleting it removes it for good.

Transports and encryption#

TLS on port 5061 is recommended: the phone's login and calls are encrypted on the way. UDP and TCP on port 5060 work too, for phones without TLS.
Media encryption (SRTP) is offered to every phone; phones that support it encrypt their audio, others fall back to plain RTP. Setting SRTP to optional (or best effort) on the phone is the safe choice.
Phones behind NAT (home routers, mobile networks) work without port forwarding; keep the registration interval at a few minutes.
IPv4 and IPv6 both work.

What a phone can dial#

Dial	Becomes
An extension number (`100`, `201`)	An internal call — it rings that extension like any other call (do-not-disturb, voicemail on no answer)
A national number (`0612345678`)	An outside call through the tenant's trunk, using the trunk's country code
An international number (`+44…` or `0044…`)	An outside call, if the tenant allows international calls

The number the called party sees is the extension's outbound_caller_id_e164 when set (it must be one of your numbers), otherwise the trunk's own number.

Toll-fraud protection#

Phones can be stolen and passwords leak, so outside calls from phones are limited per tenant (PATCH /policy, admin UI: ScaiDial → Settings):

Policy field	Default	Effect
`phones_allow_international`	`false`	Calls to other countries are refused
`phones_allow_premium`	`false`	Premium-rate and personal numbers are refused (Netherlands: 0900, 0906, 0909, 084, 087)
`phones_max_outbound_calls`	`4`	At most this many outside calls from the tenant's phones at once

The phones edge also rate-limits registrations and blocks addresses that keep failing to log in.

Emergency numbers (112, 911, 999) cannot be called from ScaiDial phones. Make sure people have another way to reach emergency services.

Choosing a softphone#

Any SIP client that supports registration with a username and password works. Check that it supports TLS (and ideally SRTP) and set it up with the details above; no vendor-specific provisioning is needed.