Call control

Calls in progress are controlled per leg — one party's part in a call (GET /calls/active lists calls with their legs). All routes below need scaidial:calls:observe and act within your tenant. The same operations are available to ScaiWave users and, as MCP tools, to AI agents (MCP tools).

Hang up#

POST /legs/{leg_id}/hangup removes that party. When fewer than two parties are left, the call ends.

Hold#

bash
curl -X POST $SCAIDIAL/legs/$LEG/hold -H "$AUTH"     # put that party on hold
curl -X POST $SCAIDIAL/legs/$LEG/unhold -H "$AUTH"

The held party hears music on hold and nothing of the call; nobody hears them. The music comes from the holding extension's playlist (else the tenant default, else the built-in one). To put the caller on hold, hold the caller's leg.

POST /legs/{leg_id}/transfer with {"to_extension": "+31201234567", "mode": "blind"} asks that party's phone system to call the target itself (SIP REFER). It works only where the far end accepts REFER, which many carriers don't. For transfers that always work, use an attended transfer and complete it straight away, or the ScaiWave transfer.

Attended transfer#

Talk to the target first, then hand the call over.

bash
# 1. Start: LEG is YOUR leg (the transferor). The other parties hear
#    "one moment please", then music on hold, while the target rings.
curl -X POST $SCAIDIAL/legs/$LEG/consult -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"to": "201"}'                       # an extension number or an E.164 number
# → {"consult_id": "…", "state": "ringing", …}

curl $SCAIDIAL/transfers/$CONSULT -H "$AUTH"           # ringing → talking
curl -X POST $SCAIDIAL/transfers/$CONSULT/complete -H "$AUTH"   # hand over: you leave
curl -X POST $SCAIDIAL/transfers/$CONSULT/cancel -H "$AUTH"     # or: drop the target, back to the caller

`state`	Meaning
`ringing`	The target is being rung (an extension rings without falling back to voicemail)
`talking`	The target answered; you talk to them, the caller is on hold
`completed`	The caller and the target are connected; your leg has ended
`cancelled`	Back to you and the caller (`ended_reason`: `cancelled`, `no_answer`, `target_hangup`, `timeout`, `error`)
`ended`	The caller hung up during the consultation (`caller_hangup`); you and the target stay connected

Automatic outcomes: no answer within about 30 seconds — you hear "no answer" and are back with the caller. You hang up while talking to the target — the transfer completes. The target hangs up — you're back with the caller. A consultation left open is cancelled after 15 minutes. One consultation per call at a time.

Merge calls into a conference#

With two calls of your own, merge them: everyone hears everyone.

bash
curl -X POST $SCAIDIAL/calls/merge -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"keep_leg_id": "<your leg in call A>", "merge_leg_id": "<your leg in call B>"}'
# → {"call_id": "<A>", "merged_call_id": "<B>", "bridge_id": "…"}

Everyone on call B joins call A; your leg in call B ends and you carry on in call A; anyone on hold is taken off hold. Up to 8 calls can be merged into one. When someone hangs up, the others stay connected; a call left with one party ends.

Conference controls#

leg_id is your leg in the kept call.

bash
curl $SCAIDIAL/legs/$LEG/conference -H "$AUTH"
# → {"focus": "all", "merged_calls": [{"bridge_id": "…", "call_id": "…", "on_hold": false}], "others_on_hold": false}

curl -X POST $SCAIDIAL/legs/$LEG/conference/focus -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"focus": "kept"}'
curl -X POST $SCAIDIAL/legs/$LEG/conference/drop -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"bridge_id": "…"}'

`focus`	You talk with	On hold (music)
`all` — join	everyone	nobody
`kept` — split	the kept call's parties	the merged calls
`<bridge_id>` — swap	that merged call	the kept call's other parties and the other merged calls
`none` — hold	nobody	everyone

drop hangs up one merged call; the rest carries on. Holds are applied before anyone is reconnected, so a swap never lets the two sides hear each other. If you leave, or the merged call you're talking to hangs up, everyone is joined again. An attended transfer from a split or held conference is refused until it is joined again.

Speak into a call#

bash
curl -X POST $SCAIDIAL/legs/$LEG/speak -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"text": "This call is being transferred to our support team.", "language": "en"}'
# → {"completed": true}

ScaiSpeak synthesises the text (up to 1,000 characters) and everyone on the call hears it; the request returns when it has been spoken (completed: false if that party hung up part-way). voice_id is optional and must be a ScaiSpeak voice your tenant can use. Prompts in the same call queue behind each other.