Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

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#

json
1
{"action_type": "ring_extension", "action_params": {"extension_id": "…"}}

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#

json
1
{"action_type": "ring_bot", "action_params": {"bot_id": "…"}}

Puts a ScaiBot voice agent on the call without creating an extension for it. Only voice-enabled bots can answer.

voicemail#

json
1
{"action_type": "voicemail", "action_params": {"voicemail_box": "100"}}

Records a message for the extension with that number. Without voicemail_box, the message goes to the last extension that rang. See voicemail.

forward#

json
1
{"action_type": "forward", "action_params": {"forward_to": "+31201234567"}}

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#

json
1
2
3
4
5
6
7
8
{
  "action_type": "play_message",
  "action_params": {
    "text": "Welcome to Example. Calls may be recorded for training.",
    "voice_id": "…",
    "after": "continue"
  }
}

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#

json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "action_type": "ivr_menu",
  "action_params": {
    "prompt": "Press 1 for sales, 2 for support, or stay on the line.",
    "options": {
      "1": {"action_type": "ring_extension", "action_params": {"extension_id": "…"}},
      "2": {"action_type": "ring_bot", "action_params": {"bot_id": "…"}},
      "9": {"action_type": "voicemail", "action_params": {}}
    },
    "default": {"action_type": "ring_extension", "action_params": {"extension_id": "…"}},
    "timeout_s": 6,
    "repeats": 2
  }
}

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 — keys 0–9, *, #; each runs any action except another menu. For a play_message option, 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#

json
1
{"action_type": "hangup", "action_params": {}}

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.

Updated 2026-10-14 00:46:57 View source (.md) rev 12