Troubleshooting
The trunk doesn't register#
Check GET /trunks/{id} and GET /trunks/{id}/registration (the Trunks page shows both).
| What you see | Likely cause | Fix |
|---|---|---|
sync_status: "error" |
The trunk couldn't be set up on the SBC | Read sync_last_error, fix the field it names, POST /trunks/{id}/resync |
registration failed |
The carrier rejected the registration — almost always the username or password | Correct them with PATCH /trunks/{id}; the SBC re-registers immediately |
registration failed, credentials correct |
The carrier only accepts known source addresses | Give the carrier the addresses from GET /network-info |
pending / registering for more than a minute |
The carrier doesn't answer: wrong server, port or transport | Check sip_server_address, port and transport against the carrier's documentation |
not_applicable |
sip_auth_mode: "ip_whitelist" trunks don't register |
Expected; the carrier sends calls to the SBC's address |
Called people see "private" or the wrong number#
The caller ID is the extension's outbound_caller_id_e164, otherwise the trunk's default_caller_id_e164, otherwise the trunk's first number. Check carrier.preview on GET /trunks (the Trunks page shows it in the trunk form): it's what the carrier receives.
| Preview shows | Fix |
|---|---|
Your account username in From |
The carrier reads the caller ID from From. Set from_mode to cli (override on the trunk, or ask ScaiLabs to correct the carrier's profile) |
| A number in the wrong format | Set number_format to what the carrier expects. Some carriers show a number they don't recognise as private rather than rejecting it, e.g. 0031… where they want 31… |
| The right number, still shown as private | The number isn't registered as yours with the carrier, or caller-ID presentation is off in your carrier account |
Inbound calls don't arrive#
- The number must be on the trunk (
sip_inbound_numbers) and have a DID pointing at a dialplan. - The DID or the dialplan rule may be disabled.
- Calls only arrive from the carrier's own addresses. A carrier that moved its servers needs the trunk updated.
A desk phone or softphone won't log in#
- Use the
domainfromGET /extensions/{id}/sip-accountas server and domain, the extension number as user and authentication name. - After a password rotation, every phone needs the new password.
- Repeated failed logins block the phone's address for a while. Fix the password, wait a few minutes, try again.
- TLS (5061) needs a phone that trusts public certificates; if an old phone fails on TLS, try TCP or UDP on 5060.
- The extension must be enabled and of type
sip_endpoint. A login error shows on the extension (sip_error);POST /extensions/{id}/sip-account/syncre-creates it.
A phone can't call out#
| Phone hears / call ends with | Cause |
|---|---|
| Rejected immediately for a foreign number | phones_allow_international is off |
| Rejected for 0900 / 0906 / 0909 / 084 / 087 | phones_allow_premium is off |
| Rejected while other calls are going | More than phones_max_outbound_calls outside calls at once |
Rejected immediately for one number (scaidial.invalid_number in apps) |
The number isn't valid in its country, usually a digit missing or extra |
| Rejected for 112 / 911 / 999 | Emergency calls aren't supported from ScaiDial phones |
| Rejected for everything outside | The tenant has no registered trunk |
One-way or no audio#
- Desk phone: set the phone's NAT traversal to keep-alives / rport and a registration interval of a few minutes; don't use a SIP ALG on the router. If SRTP is set to mandatory on the phone, set it to optional.
- Browser (ScaiWave,
/my/dial): allow microphone access; if your network blocks UDP entirely, WebRTC needs a TURN server reachable over TCP or TLS. - Calls through the carrier: audio passes through the SBC's media relay; carriers that filter by source must allow the RTP range from
GET /network-info.
The IVR menu ignores keypresses#
- The caller's phone must send DTMF as RFC 2833 / 4733 events (the default almost everywhere). Phones set to SIP INFO or in-band only won't work.
- Check the option keys in the rule: only
0–9,*and#. - A key pressed before the menu starts (during a welcome
play_message) is not kept.
Voicemail has no transcript or summary#
- Transcripts are off: turn on
voicemail_transcript_enabledin ScaiDial → Settings. It applies to new messages only. - The message was very short or unclear: the transcript can be empty, and then there's no summary either.
- A transcript without a summary means the summary step failed; the message and transcript are kept.
A call isn't recorded#
| What you see | Cause |
|---|---|
409 scaidial.recording_not_allowed |
Recording is off for the tenant, or an extension in the call is set to never record |
503 scaidial.recording_announcement_unavailable |
The announcement couldn't be played, so nothing is recorded. Try again; if it persists, contact support |
403 scaidial.recording_stop_not_allowed |
The tenant records every call and users may only pause |
always, but an internal call isn't recorded |
Turn on Record internal calls too |
A gap marked recorder_restart |
The service restarted during the call; about 20–30 s is missing, and recording carried on |
409 scaidial.captions_not_allowed |
Live captions are off for the tenant, captions without recording aren't allowed (start a recording first), or an extension in the call never records |
| Captions don't show in ScaiWave | Only app participants who can hear the speaker get them, a second or two after the speaker pauses; check the app listens for text streams on lk.transcription |
| An outside caller's voice is missing | With Announce and ask outside callers, they didn't press 1 within 10 s (consent: declined on the recording). Their phone must send key presses as RFC 2833 / 4733 events |
POST /recordings/erase kept some recordings |
They're on legal hold or still running (legal_hold_ids, live_ids); lift the hold or wait for the call to end and erase again |
The recording stays processing |
It's still being written; a long call takes a few seconds. After a few minutes it becomes ready or failed |
Transfers#
- Blind transfer returns 409 "REFER … rejected": the far end doesn't accept SIP REFER (many carriers don't). Use an attended transfer (
POST /legs/{id}/consult) and complete it. - Attended transfer returns 409: a consultation is already running on that call, the conference is split or held (join it first), or your leg isn't in the call anymore.
- The target never rings:
tomust be an extension number of your tenant or an E.164 number, and E.164 targets need a registered trunk.
403 on admin routes#
Every admin route needs its module permission (permissions). Ordinary tenant users get 403 scaidial:… required; give them the permission, or use the portal (/me/…) for their own extensions. A 403 module not enabled means ScaiDial isn't enabled for the tenant.
Following one call#
Every call has an id, and its legs have end_reasons (ring_timeout, caller_hangup, transferred:…, merged:…, room_finished). GET /calls/{id} shows them for a live call, GET /calls/history afterwards. Quote the call id when you contact support.