Dialplans
A dialplan is an ordered list of rules. Each rule has a match (does this rule apply to the call?) and an action (what to do). Every DID points at one dialplan; calls to that number walk its rules from the lowest priority up.
- The first matching rule runs. If its action connects the call (someone answers) or ends it, the walk stops.
- If the action doesn't connect — the extension doesn't answer, an announcement set to continue has played, an IVR caller pressed nothing — the walk carries on with the next matching rule.
- When the rules run out, the call goes to the voicemail of the last extension that rang. If no extension rang, the call ends.
The admin UI (ScaiDial → Dialplans) builds rules with pickers; the wire shapes below are what the API stores.
Match types#
match_type |
match_params |
Matches when |
|---|---|---|
always |
{} |
always — use it for catch-all rules |
did |
{"did_id": "…"} |
the call came in on that number (when one dialplan serves several numbers) |
caller_prefix |
{"prefix": "+44"} |
the caller's number starts with the prefix (+ and 1–15 digits) |
time_window |
{"days": [0,1,2,3,4], "start": "09:00", "end": "17:30", "tz": "Europe/Amsterdam"} |
the call arrives on one of those days (Monday = 0) between start and end in that time zone. An end before start is an overnight window (22:00–06:00) belonging to the listed day. |
extension |
{"extension_id": "…"} |
the call is for that extension (internal routing only; calls from the phone network don't have one) |
Actions#
ring_extension#
1 | |
Rings the extension the way its type rings (a ScaiWave user's devices, every desk phone registered on it, a bot, an outside number, or straight to its voicemail) for its ring timeout. Do-not-disturb sends the call to the extension's voicemail. When nobody answers, the walk carries on with the next rule — and ends in this extension's voicemail if no later rule connects. ScaiWave extensions can instead set their own timeout_action (voicemail, forward or hang up).
ring_bot#
1 | |
Puts a ScaiBot voice agent on the call without creating an extension for it. Only voice-enabled bots can answer.
voicemail#
1 | |
Records a message for the extension with that number. Without voicemail_box, the message goes to the last extension that rang. See voicemail.
forward#
1 | |
Dials the number through the trunk the call came in on and connects the caller. Use an E.164 number. (For a forward that is part of a person's settings, give them an external extension or a forward rule instead.)
play_message#
1 2 3 4 5 6 7 8 | |
Speaks text to the caller with ScaiSpeak (voice_id optional; the tenant's prompt voice by default), then either carries on with the next matching rule ("after": "continue", the default) or hangs up ("after": "hangup"). Typical uses: a welcome before the menu, or "we're closed" + hang up after hours.
ivr_menu#
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
Speaks the prompt and waits for one key. A key pressed during the prompt interrupts it. A key that isn't an option gets "That is not a valid choice" and the prompt again.
options— keys0–9,*,#; each runs any action except another menu. For aplay_messageoption, set"after": "hangup"to end the call after it (the admin UI does this for you); otherwise the walk continues.default— runs when the caller presses nothing (optional; without it the walk carries on with the next rule).timeout_s— seconds to wait after the prompt (2–30, default 6).repeats— how often the menu is asked (1–5, default 2).- If the chosen option doesn't connect (the extension doesn't answer), the walk carries on with the next rule.
Keypresses work from the phone network (RFC 2833 / RFC 4733 DTMF), desk phones and softphones.
hangup#
1 | |
Ends the call — for example for a caller-prefix blocklist rule at priority 1.
Priority#
Lower numbers run first. Leave gaps (100, 200, 300) so you can insert rules later. Give every rule its own priority; ties run in creation order.
Example: a small office#
| Priority | Match | Action |
|---|---|---|
| 10 | caller_prefix +44900 |
hangup |
| 50 | always |
play_message "Welcome to Example." (continue) |
| 100 | time_window Mon–Fri 09:00–17:30 |
ivr_menu 1 → sales, 2 → support bot, default → reception |
| 900 | always |
play_message "We're closed. Leave a message after the tone." (continue) |
| 999 | always |
voicemail → reception |
Calls from the blocked prefix end. Everyone else hears the welcome. During office hours they get the menu; if the person they chose doesn't answer, the walk continues to the closed message and voicemail. Outside hours they go straight to the closed message and voicemail.
To ring a person and fall back to a bot, keep the dialplan simple and put it on the extension: a no_answer forward rule to the bot's extension.