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

Quickstart

From nothing configured to "my number rings my phone" in one sitting. Every step can also be done in the admin UI under ScaiDial; the API calls are shown so you can automate it.

Prerequisites#

  • A ScaiGrid API key with scaidial:trunks:manage, scaidial:extensions:manage and scaidial:dialplan:manage (tenant admins have all three). See permissions.
  • A SIP trunk from a carrier (or your own PBX): server name, username and password, and at least one phone number (DID) on it.
bash
1
2
export SCAIDIAL=https://scaigrid.scailabs.ai/v1/modules/scaidial
export AUTH="Authorization: Bearer $SCAIGRID_API_KEY"

1. Add the trunk#

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
TRUNK_ID=$(curl -s -X POST $SCAIDIAL/trunks -H "$AUTH" -H "Content-Type: application/json" -d '{
    "name": "primary",
    "sip_server_address": "sip.example-carrier.com",
    "sip_server_port": 5060,
    "sip_transport": "udp",
    "sip_auth_mode": "credentials",
    "sip_auth_username": "your-trunk-user",
    "sip_auth_password": "your-trunk-secret",
    "sip_inbound_numbers": ["+31201234567"],
    "sip_media_encryption": "disabled"
  }' | jq -r .data.id)
python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import httpx, os

api = httpx.Client(
    base_url="https://scaigrid.scailabs.ai/v1/modules/scaidial",
    headers={"Authorization": f"Bearer {os.environ['SCAIGRID_API_KEY']}"},
)
trunk = api.post("/trunks", json={
    "name": "primary",
    "sip_server_address": "sip.example-carrier.com",
    "sip_server_port": 5060,
    "sip_transport": "udp",
    "sip_auth_mode": "credentials",
    "sip_auth_username": "your-trunk-user",
    "sip_auth_password": "your-trunk-secret",
    "sip_inbound_numbers": ["+31201234567"],
    "sip_media_encryption": "disabled",
}).json()["data"]
typescript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const api = (path: string, init: RequestInit = {}) =>
  fetch(`https://scaigrid.scailabs.ai/v1/modules/scaidial${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.SCAIGRID_API_KEY}`,
      "Content-Type": "application/json",
    },
  }).then((r) => r.json());

const trunk = (await api("/trunks", {
  method: "POST",
  body: JSON.stringify({
    name: "primary",
    sip_server_address: "sip.example-carrier.com",
    sip_server_port: 5060,
    sip_transport: "udp",
    sip_auth_mode: "credentials",
    sip_auth_username: "your-trunk-user",
    sip_auth_password: "your-trunk-secret",
    sip_inbound_numbers: ["+31201234567"],
    sip_media_encryption: "disabled",
  }),
})).data;

ScaiDial sets the trunk up on the ScaiLabs SBC, which registers with your carrier. Two things to check:

  • sync_status on the trunk becomes synced when the configuration is in place (error + sync_last_error otherwise; fix and POST /trunks/{id}/resync).
  • GET /trunks/{id}/registration reports whether the carrier accepted the registration: {"state": "registered", "registrar": "sip.example-carrier.com", "next_attempt_at": "…"}. failed means the carrier rejected or didn't answer — usually the username or password.

Carriers that authenticate by source address ("sip_auth_mode": "ip_whitelist") need the SBC's addresses: GET /network-info returns them with the SIP ports and the RTP range.

Check the caller ID too: the trunk's carrier.preview.from is what the carrier will receive on outbound calls. If your carrier isn't recognised automatically, the trunk uses generic settings (E.164 numbers, caller ID in From); see carrier profiles to adjust them. IP-authenticated trunks also need the carrier's source addresses in carrier_overrides.allowed_ips.

2. Create an extension and a dialplan#

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# A ScaiWave user's extension. For a bot: "type": "bot", "target_ref": "<bot id>".
EXT_ID=$(curl -s -X POST $SCAIDIAL/extensions -H "$AUTH" -H "Content-Type: application/json" -d '{
    "number": "100",
    "type": "wave",
    "target_ref": "<ScaiGrid user id>",
    "display_name": "Reception",
    "ring_timeout_s": 25
  }' | jq -r .data.id)

DPLAN_ID=$(curl -s -X POST $SCAIDIAL/dialplans -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "main"}' | jq -r .data.id)

curl -s -X POST $SCAIDIAL/dialplans/$DPLAN_ID/rules -H "$AUTH" -H "Content-Type: application/json" -d "{
    \"priority\": 100,
    \"match_type\": \"always\",
    \"action_type\": \"ring_extension\",
    \"action_params\": {\"extension_id\": \"$EXT_ID\"}
  }"

If nobody answers within the ring timeout, the call goes to the extension's voicemail.

3. Point your number at the dialplan#

bash
1
2
3
4
5
curl -s -X POST $SCAIDIAL/dids -H "$AUTH" -H "Content-Type: application/json" -d "{
    \"e164\": \"+31201234567\",
    \"trunk_id\": \"$TRUNK_ID\",
    \"dialplan_id\": \"$DPLAN_ID\"
  }"

Call the number from your mobile. The call appears on ScaiDial → Active Calls as ringing, then active when answered; afterwards it is in Call History.

4. Add a desk phone or softphone#

bash
1
2
3
4
5
6
7
PHONE_ID=$(curl -s -X POST $SCAIDIAL/extensions -H "$AUTH" -H "Content-Type: application/json" -d '{
    "number": "201",
    "type": "sip_endpoint",
    "display_name": "Front desk phone"
  }' | jq -r .data.id)

curl -s $SCAIDIAL/extensions/$PHONE_ID/sip-account -H "$AUTH"

The response holds the phone's login: domain (your tenant's <label>.sip.scailabs.ai), username (the extension number), password and the transports. Enter them in the phone — TLS on port 5061 is recommended. Once registered, the phone shows up under registrations, can call other extensions by number and outside numbers in national or international format, and rings when its extension is called. See desk phones and softphones.

Next steps#

  • IVR menu: "press 1 for sales, 2 for support" — see dialplans.
  • Bots: an extension of type bot puts a ScaiBot voice agent on a number.
  • After-hours: a time_window rule plus an announcement or voicemail.
  • Forward to a mobile: an external extension with "target_ref": "+31612345678".
  • Voicemail transcripts and summaries: turn them on with PATCH /policy {"voicemail_transcript_enabled": true}.
  • Music on hold: upload your own on ScaiDial → Music on hold (music on hold).
Updated 2026-10-14 00:46:56 View source (.md) rev 12