Pause a voice AI agent mid-call and bring it back

AI AgentsAI agent hold and resume

Put the caller on hold with a spoken line, take them off it, or end the AI on a call that keeps running, each with one REST command.

rest

The claim

An agent waiting on something slow has two bad options. It can talk through the wait, or sit silent while the model tries to fill the gap. This is the third: your backend holds the caller, does the work, and takes them off hold.

Why it holds

The vendored REST spec, tools/openapi/rest.json, is the authority.

calling.ai_hold takes a prompt, which the spec describes as “a system message added to the AI conversation before placing the caller on hold. The AI will speak this message to the caller before hold music begins.“ It also takes a timeout.
calling.ai_unhold takes no params at all.
calling.ai.stop documents one param, control_id, and calls it “Reserved field … currently ignored”, so this recipe does not send it.

*The timeout is a string.* The spec types it as one and says so twice: “must be sent as a string” and “integer payloads are rejected”. A number here is a 400, so the recipe converts, and refuses a fractional value rather than rounding one silently.

How it works

def hold(call_id, seconds=90, prompt=HOLD_PROMPT):
    if int(seconds) != float(seconds):
        raise ValueError(...)
    return client.calling.ai_hold(call_id, timeout=str(int(seconds)), prompt=prompt)

def stop(call_id):
    # the method is ai_stop; the command on the wire is calling.ai.stop
    return client.calling.ai_stop(call_id)

What the platform receives for hold:

{"command": "calling.ai_hold",
 "id": "6d3f4a0e-2b1c-4e7a-9f0d-1c2b3a4d5e6f",
 "params": {"timeout": "90",
            "prompt": "Let me check that for you. One moment."}}

The method name and the command are not the same word. ai_stop() sends calling.ai.stop, with a dot, in both SDKs. That is the usual rule here: the key the platform receives is what a verifier asserts, never the name of the method that produced it.

Limitations

The verifier proves the requests, not the hold. What the caller hears while held, and how the agent picks the conversation back up, are live behaviour.

calling.ai.stop ends the AI, not the call. Whatever is left in the document after the ai verb is what happens next. On a document that was only an agent, that is the end of the call.

What to change first

Pass timeout=90 instead of timeout=str(90) in hold and run the verifier. The string assertion fails, which is the point: this is the one param in the recipe where the JSON type is the whole rule.

Where this sits

Before this

Route a call to an AI agent

Inject a message into a live AI call Keep per-call state server-side, keyed by call id End or transfer a live call over REST

python/app.py

"""Pause a voice AI agent mid-call and bring it back.

`calling.ai_hold` puts the caller on hold and stops the agent listening;
`calling.ai_unhold` brings it back; `calling.ai.stop` ends the AI on the call
and leaves the call itself up. Each is one POST to /api/calling/calls addressed
to the call id.

The spec is explicit that `ai_hold`'s `timeout` is a numeric string, and that
an integer payload is rejected, so this converts it and refuses anything that
is not a whole number of seconds.

Written against signalwire-sdk 3.0.1 (RestClient.calling).

    python app.py hold <call_id> [seconds]
    python app.py unhold <call_id>
    python app.py stop <call_id>
"""
import sys

from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()

# what the agent says before the hold music starts
HOLD_PROMPT = "Let me check that for you. One moment."


def hold(call_id, seconds=90, prompt=HOLD_PROMPT):
    """Hold the caller for `seconds`, after the agent says `prompt`."""
    if int(seconds) != float(seconds):
        raise ValueError(f"seconds must be a whole number, not {seconds!r}")
    # the spec: a numeric string. An integer payload is rejected
    return client.calling.ai_hold(call_id, timeout=str(int(seconds)), prompt=prompt)


def unhold(call_id):
    """Take the caller off hold. The agent is listening again."""
    return client.calling.ai_unhold(call_id)


def stop(call_id):
    """End the AI on this call. The call itself stays up."""
    # the method is ai_stop; the command on the wire is calling.ai.stop
    return client.calling.ai_stop(call_id)


if __name__ == "__main__":
    args = sys.argv[1:]
    cmd = args[0] if args else "help"
    call_id = args[1] if len(args) > 1 else ""
    rest = args[2:]
    if not call_id:
        print(__doc__)
    elif cmd == "hold":
        print(hold(call_id, *(int(x) for x in rest)))
    elif cmd == "unhold":
        print(unhold(call_id))
    elif cmd == "stop":
        print(stop(call_id))
    else:
        print(__doc__)

/**
 * Pause a voice AI agent mid-call and bring it back.
 *
 * `calling.ai_hold` puts the caller on hold and stops the agent listening;
 * `calling.ai_unhold` brings it back; `calling.ai.stop` ends the AI on the call
 * and leaves the call itself up.
 *
 * The spec is explicit that `ai_hold`'s `timeout` is a numeric string, and that
 * an integer payload is rejected, so this converts it and refuses anything that
 * is not a whole number of seconds.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient.calling).
 *
 *     npm start hold <call_id> [seconds]
 *     npm start unhold <call_id>
 *     npm start stop <call_id>
 */
import "dotenv/config";
import { RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();

// what the agent says before the hold music starts
export const HOLD_PROMPT = "Let me check that for you. One moment.";

/** Hold the caller for `seconds`, after the agent says `prompt`. */
export function hold(callId: string, seconds = 90, prompt = HOLD_PROMPT) {
  if (!Number.isInteger(seconds)) {
    throw new Error(`seconds must be a whole number, not ${seconds}`);
  }
  // the spec: a numeric string. An integer payload is rejected
  return client.calling.aiHold(callId, { timeout: String(seconds), prompt });
}

/** Take the caller off hold. The agent is listening again. */
export function unhold(callId: string) {
  return client.calling.aiUnhold(callId);
}

/** End the AI on this call. The call itself stays up. */
export function stop(callId: string) {
  // the method is aiStop; the command on the wire is calling.ai.stop
  return client.calling.aiStop(callId);
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, callId, seconds] = process.argv.slice(2);
  if (!callId) {
    console.log("usage: npm start <hold|unhold|stop> <call_id> [seconds]");
  } else if (cmd === "hold") {
    console.log(await hold(callId, seconds ? Number(seconds) : undefined));
  } else if (cmd === "unhold") {
    console.log(await unhold(callId));
  } else if (cmd === "stop") {
    console.log(await stop(callId));
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py hold <call_id> 90
python app.py unhold <call_id>
python app.py stop <call_id>

The TypeScript surface is the same three commands on @signalwire/sdk, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start hold <call_id> 90

Take the call id from the agent’s own tool webhook, which carries it as call_id. There is no server to expose.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier swaps the SDK’s HTTP layer for a recorder, calls the three helpers, and asserts the following.

a fractional hold raises before any request is made
the spec types ai_hold’s timeout as a string, and its description says both that it must be sent as one and that integers are rejected
what the recipe sent is a string, and it is the number of seconds it was given
calling.ai_unhold documents no params, and none are sent
calling.ai.stop documents control_id as reserved and ignored, and the recipe sends empty params
each body equals the expected {"command", "id", "params"} shape, and the third one carries calling.ai.stop rather than the method’s name
the TypeScript surface sends those same three bodies, with the timeout as a string

Report an issue