ScaiWave connector

The connector lets ScaiWave users own and use ScaiDial extensions. Their phones ring in ScaiWave, they answer, place calls, transfer, put calls on hold, change their settings and read their voicemail. A Python client is available: ScaiWave connector client.

1. Architecture#

1
2
3
4
5
6
7
8
9

 caller (PSTN / extension)                         ScaiWave clients (browser, desktop)
        │                                                    ▲ join room with our token
        ▼                                                    │
  SBC → LiveKit room  ◄──────────── audio, always ───────────┘
        │                         wss://rtc.scailabs.ai
        ▼
  ScaiGrid / ScaiDial ── signed webhooks ──► ScaiWave server
        ▲                                         │
        └──── REST /v1/public/scaidial/wave ◄──────┘  (Bearer token + X-ScaiDial-User)

• Server to server only. ScaiWave's backend talks to ScaiGrid, and its clients never call ScaiGrid directly.
• Audio always goes through a LiveKit room. ScaiGrid mints a LiveKit token for the user (accept, dial-out, rejoin). ScaiWave hands the token to the client, which joins at the livekit_url returned (wss://rtc.scailabs.ai).
• Publish the microphone as soon as you join. A caller on a phone or the carrier is only answered (their phone stops ringing) once the room has an audio track they can hear. Publish the mic track right after connecting. If no audio track from the accepting user appears within 10 seconds of the accept, ScaiGrid removes that participant from the room, sends call.ended with reason answer_no_audio, and treats the call as unanswered (the extension's no_answer forward or timeout action, by default voicemail). If the microphone isn't available, tell the user rather than letting the call fall through silently.
• No SIP between ScaiWave and ScaiGrid.

2. Authentication and access#

Every request carries:

• ScaiWave has already authenticated the user, and ScaiGrid trusts the assertion. Keep the token server-side only.
• Tenant allowlist. The user must be active and their tenant enabled for the connector, otherwise 403 scaidial.wave_tenant_not_allowed. The connector is enabled for all tenants. A tenant only has something to show once ScaiDial is set up for it (an admin creates wave extensions for its users, plus numbers and a trunk for outside calls); until then its users get an empty GET /me and no rings or events.
• Who may act on an extension:
  • owner: the user a wave extension belongs to (extension.target_ref).
  • owner / manage / answer: users given one of these roles on the extension by an admin.

Group grants count: a grant to a group (ScaiGrid or ScaiKey group id) applies to its direct members, and ring.user_ids lists them. Nested groups are not expanded.

Credentials:

• The connector token and the webhook signing secret go through ScaiVault, never chat or email.
• To rotate, ask ScaiGrid ops. Both values change together, with a short cut-over.

3. Responses and errors#

Success: {"status":"success","data":{…},"meta":{"request_id":…}}. 204 endpoints have no body.

Error: {"status":"error","error":{"code":"scaidial.…","message":"…"},"meta":{…}}. Exception: a request that fails body or query validation gets HTTP 422 as {"detail":[…]}, FastAPI's own shape. The client maps that to code validation_error.

4. Events (webhooks)#

ScaiGrid POSTs each event as JSON to your webhook URL:

1
2

{ "id": "1791622220244-0", "type": "ring", "tenant_id": "tnt_…",
  "created_at": "2026-10-10T08:50:20.244Z", "data": { … } }

Verifying:

• Compare the signature in constant time over the raw bytes.
• Reject timestamps more than 5 minutes off.
• verify_webhook() in the client does both.
• Answer with any 2xx within 3 s, and do slow work after responding.

Delivery is best-effort: one attempt, no retries. Every event is also written to a replay stream, so reconcile:

• GET /events?after=<last id you processed>, on startup and periodically. This returns the same envelopes, oldest first. Ids sort in time order.
• GET /rings for rings still waiting for an answer.

5. Ring lifecycle#

1. A call reaches a wave extension: from a DID through the dialplan, from another extension, or by transfer.
2. Before anything rings, ScaiGrid applies the extension's own policy:
   • DND on (and dnd_until not passed): straight to voicemail, and no ring is sent.
   • Forward rule always: forwards to that extension, and no ring is sent.
3. ScaiGrid sends ring, and ring_timeout_s is your deadline. Fan out to every session and device of every user in user_ids; ScaiGrid doesn't know about devices.
4. One of these happens:
   • Accept: POST /rings/{leg_id}/accept returns the room and token. Join immediately and publish the microphone (see Audio above): the caller is answered only when your audio track appears. The first accept wins; a later accept or decline gets 409. ring.cancelled(claimed) follows right away, so you can stop ringing other devices; call.answered follows once your audio track is in the room, or call.ended(answer_no_audio) after 10 s without it.
   • Decline: POST /rings/{leg_id}/decline with fallback:
     • voicemail (default): this extension's voicemail.
     • forward + forward_to: rings that extension number.
     • next: continue the tenant's dialplan.
   • Timeout: ring.cancelled(ring_timeout). If the extension has a no_answer forward rule, that applies; otherwise its timeout_action applies: voicemail (default), forward to timeout_forward_to, or hangup.
   • Caller hangs up: ring.cancelled(caller_hangup).
5. An unknown or expired ring returns 404 (scaidial.ring_not_found).

Assistant pickup:

• assistant_pickup_after_s is stored on the extension and returned with it. The timer and the assistant are ScaiWave's.
• To ScaiGrid, an assistant pickup is an ordinary accept: call accept and put the assistant into the room with the returned token. You can accept again later with the same identity through POST /calls/{call_id}/token, for example so the user can take over.

6. Endpoints#

Base URL: https://scaigrid.scailabs.ai/v1/public/scaidial/wave. "U" means X-ScaiDial-User is required.

Rings and events#

User, extensions and settings#

Extension object:

• Identity and access: id, number, type, display_name, enabled, role (the user's role).
• Availability: dnd, dnd_until.
• Ringing: ring_timeout_s, timeout_action, timeout_forward_to, assistant_pickup_after_s.
• Voicemail and caller ID: voicemail_greeting_text, outbound_caller_id_e164.

PATCH fields (all optional; send only what changes):

Forward rules: forward_to must be another extension number in the tenant. To forward to a phone number, the admin creates an external extension for it.

Calls#

Call object:

• Who and what: id, direction, state (ringing | active | ended), from_e164, from_display, from_user_id, livekit_room.
• What was called: to_number (the E.164 number dialled, the extension number for internal calls, our DID for inbound calls) and to_display (the extension's name or the DID's label, when known).
• Recording: recording ({id, state} while the call is being recorded or paused, else null), recording_ids (every recording of the call that still exists, oldest first) and captions (live captions running).
• The other party, as the requesting user sees the call: peer_number and peer_display. For a call the user placed (from the app or their desk phone) this is what they dialled; otherwise it is the caller (E.164, or the caller's extension number for internal calls). peer_number can be passed straight to POST /calls to redial. Calls from before 2026-10-13 have no to_number, so peer_* is null for calls the user placed.
• Timing and outcome: started_at, ended_at, duration_ms, end_reason.
• legs: each leg has id, role (caller | answerer | callee), extension_id, extension_type, state, participant_identity, answered_at, ended_at.

Semantics:

• Dial-out (POST /calls):

  • The user must be owner or manage on from_extension_id. The limit is 30 calls per minute per tenant (429 when exceeded).
  • E.164: dials out through the tenant's trunk. 422 scaidial.invalid_number if the number isn't valid in its country (e.g. a digit missing; show the message to the user); 422 scaidial.no_outbound_trunk if the tenant has no trunk; 502 if the originate fails. Transfers to an E.164 number get the same scaidial.invalid_number check.
  • Extension number: an internal call. The callee rings exactly as in §5, and on no answer the caller reaches the callee's voicemail.
  • Join the room right away. The far end is added when it answers.

• Hold puts the given leg's party on hold: nobody hears them and they hear music on hold instead of the call. To put the caller on hold, hold their leg; unhold lifts it.

• Transfer is blind, and leg_id is the user's own leg:

  • The other party stays in the room, and the target is added.
  • An extension target rings like §5, with voicemail on no answer. An E.164 target is dialled out through the tenant trunk and gets its own leg (xfer-…), so it can be held or hung up like any other party.
  • Then the user's leg ends.

• Attended transfer (mode: "attended"): the user talks to the target first. leg_id is the user's own leg; only that user can complete, cancel or read the consultation.

  • The other party hears "one moment please" (in the tenant's call language), then music on hold (the user's extension's playlist), and nobody hears them, until the consultation ends.
  • The target rings: an extension number (like §5, but no voicemail on no answer) or an E.164 number through the tenant trunk. The user hears ringback for E.164 targets.
  • transfer.consult reports ringing → talking when the target answers. If nobody answers (about 30 s) the user hears "no answer" and is connected to the caller again (cancelled, no_answer).
  • complete (only while talking): the caller and the target are connected, and the user's leg ends (transferred:<to>).
  • cancel (while ringing or talking): the target is dropped and the user is back with the caller.
  • If the user hangs up while talking, the transfer completes. If the target hangs up, the user is back with the caller. If the caller hangs up, the consultation ends (ended, caller_hangup) and the user and the target stay connected.
  • One consultation per call at a time (409 scaidial.transfer_declined otherwise). An unanswered consultation is cancelled after 15 minutes.

• Merge calls (POST /calls/merge): a three-way (or bigger) call from two of the user's calls. Both legs are the user's own legs in two different calls.

  • Everyone on merge_leg_id's call joins keep_leg_id's call: all parties hear each other. The user continues in the kept call only, so their merge_leg_id leg ends (merged:<call_id>); legs on hold in either call are taken off hold.
  • The calls keep their own rooms, joined by a bridge (participants bridge-… and sip_scaidial-bridge-<n>); keep using the kept call's room and token. Further calls can be merged into the same call (up to 8).
  • When someone hangs up, the others stay connected (conference rules). A side with no one left closes, and a call left with one party ends.
  • Refused with 409 scaidial.transfer_declined if either call has an attended transfer in progress, or the calls are already merged.

• Conference controls (leg_id = the user's leg in the kept call). focus decides who talks to whom:

  Button	focus	User talks with	On hold
  Join	all	everyone	nobody
  Split	kept	the kept call's parties	the merged calls
  Swap / talk to one call	<bridge_id>	that merged call	the kept call's other parties and other merged calls
  Hold	none	nobody	everyone

  • Held parties hear "one moment please" (tenant call language), then music on hold (the user's extension's playlist, see below), and nobody hears them. Holds are applied before anyone is reconnected, so a swap never lets the two sides hear each other.
  • Drop (conference/drop) hangs up one merged call; the rest carries on.
  • Automatic: if the user leaves, or the merged call they were talking to hangs up, everyone is joined again. Merging another call also joins everyone first. Attended transfer from a split or held conference is refused until it is joined again.

• Hangup ends one leg:

  • Fewer than two parties left (e.g. the PSTN caller alone in the room): the room is closed and the call ends for everyone.
  • Hanging up the caller leg while extensions are still ringing cancels those rings.

• Rejoin returns a fresh token with the user's existing participant identity, so on reconnect LiveKit replaces the old connection instead of adding a duplicate.

Music on hold#

Held parties (plain hold, a caller waiting during an attended transfer, the parts of a conference that are split off) hear music. It comes from the holding extension's playlist (moh_playlist_id), else the tenant default (set by tenant admins in ScaiGrid), else the built-in public-domain classics. Users can keep personal playlists and upload their own music:

• Playlist: id, name, scope (platform | tenant | personal), owner_user_id, shuffle, is_default, track_count, duration_ms, editable.
• Track: id, playlist_id, title, artist, duration_ms, size_bytes, position, license, source_url, created_at.
• Uploads: MP3, WAV, FLAC, OGG/Opus, M4A/AAC; up to 40 MB and 15 minutes, at least 5 seconds, 50 tracks per playlist. Tracks are converted to 16 kHz mono and levelled to a calm volume. The uploader must confirm they may use the music (rights_confirmed); it is recorded with their user id. Errors are 400 with a readable message.
• Choosing: PATCH /extensions/{id} with moh_playlist_id (a built-in, tenant or the user's own playlist; "" = tenant default).
• Shuffle plays the playlist in random order, otherwise in position order; it loops.

Voicemail (read: owner / manage / answer / observe; delete: owner / manage)#

Voicemail object: id, extension_id, call_id, from_e164, from_user_id, from_display, duration_ms, transcript, summary, listened_at, created_at.

How messages are recorded:

• The caller hears the greeting: voicemail_greeting_text, or a default naming the extension.
• A tone follows, then recording. Recording stops when the caller hangs up, after about 6 s of silence following speech, or after 3 minutes.
• A message is only stored if the caller spoke for at least 1 s.
• transcript is filled only when the tenant has opted in to voicemail transcription; otherwise it is null.
• summary is a one- or two-sentence summary of the transcript, in its language: who called, what they want, any call-back number or time, and urgency. It is generated on ScaiLabs-hosted models and only when there is a transcript; otherwise it is null.

Call recording#

Recording policy is set by tenant admins in ScaiGrid: off, on request, or every call, with per-extension overrides. Every party hears an announcement before anything is recorded; parties who join later hear it on their own. Full behaviour: call recording.

Who may do what:

• Control: the user who placed the call, or owner / manage / answer on an extension in the call. observe also works when the tenant enables it.
• List, get, play: placed the call, or any role on an extension in the call.
• Delete: owner / manage.
• Recordings the user may not see return 404.
• Every play and delete is logged with the user id.

Live captions (tenant recording_live_captions_enabled): while a recording runs, each person's words are sent into the LiveKit room about 1–2 s after they pause.

• They arrive as text streams on topic lk.transcription, the standard LiveKit transcription topic: room.registerTextStreamHandler('lk.transcription', …) in the JS SDK.
• Attributes:
  • lk.transcribed_track_id: the speaker's audio track;
  • lk.segment_id;
  • lk.transcription_final: always true, with no interim results;
  • scaidial.participant_identity, scaidial.speaker_label, scaidial.start_ms and scaidial.end_ms (time in the recording).
• The sender is ScaiGrid's hidden recorder, so the stream's sender identity is empty; use the attributes.
• Only app participants who can hear the speaker get captions: never a party on hold, or the caller waiting during a consultation.
• captions on the call object says whether they're on.
• With tenant recording_captions_without_recording, captions/start works on an unrecorded call: everyone hears "this call is being transcribed" and nothing is stored.

Errors:

• 409 scaidial.captions_not_allowed: captions are off, captions without recording aren't allowed, or an extension in the call never records.
• 409 scaidial.recording_not_allowed: off by policy.
• 409 scaidial.recording_state: already recording, not recording, or the call ended.
• 403 scaidial.recording_stop_not_allowed: the tenant requires recording; pause instead.
• 503 scaidial.recording_announcement_unavailable: nothing is recorded.
• 504 scaidial.recording_timeout.
• 409 scaidial.recording_legal_hold on delete.

Recording object:

• Identity: id, call_id, state (recording | paused | processing | ready | failed), trigger (user | policy), started_by_user_id.
• Timing: started_at, ended_at, end_reason, duration_ms (audio captured; pauses excluded).
• Media: format (ogg_opus), size_bytes.
• Who was in it: participants: participant_identity, kind (phone | app | bot | bridge), display, e164, extension_id, extension_number, leg_id, consent, joined_at_ms, left_at_ms.
  • consent is announced, confirmed, declined or not_asked.
  • When the tenant asks outside callers to press 1, declined and not_asked parties were never recorded; show that in the UI rather than implying the whole call is on tape.
• Gaps: gaps: at_ms on the recording's timeline, wall_ms (how long), reason (paused | recorder_restart).
• Retention: retention_until, legal_hold.
• Merges: merged_into_recording_id.
• Transcripts: transcript_state (off | pending | ready | failed) and summary (two sentences, or null). The turns come from /transcript. Every turn is labelled with its speaker, because each party is recorded separately. Reading the transcript is logged like a play.

Lifecycle:

• started → (paused ↔ resumed)* → stopped → ready, usually a few seconds after the stop or the hang-up. Then transcript.ready follows, when transcripts are on.
• The recording is deleted at retention_until (tenant setting, default 90 days), and you receive recording.deleted.

7. Participant identities in LiveKit rooms#

8. Getting started#

1. Get the connector token and webhook secret from ScaiVault.
2. Give us your webhook URL.
3. Use the Python client:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from scaidial_wave_client import ScaiDialWaveClient, verify_webhook

async with ScaiDialWaveClient("https://scaigrid.scailabs.ai", token) as dial:
    me = await dial.me("usr_…")                      # extensions + roles
    async for ev in dial.iter_events(after=last_id):  # catch up
        ...

# in your webhook handler
event = verify_webhook(raw_body, request.headers, secret)  # raises on bad signature / stale
if event["type"] == "ring":
    for uid in event["data"]["scaikey_user_ids"]:
        ...  # notify that user's devices
    # on a device's "answer":
    ans = await dial.accept_ring("usr_…", event["data"]["leg_id"], device="desktop")
    # → client joins ans["livekit_url"] with ans["livekit_token"]

9. Known limits#

• Server-side "speak text into a call" is available to bots and agents through the ScaiGrid MCP tool scaidial.call.speak, not through this connector API.
• No per-device ringing in ScaiGrid: ScaiWave fans out to devices.
• Webhooks are single-attempt. Reconcile with /events and /rings.